Local config

Keep machine-specific provider credentials, device bindings, and app artifact paths in agent-qa.local.yaml instead of shared project config.

agent-qa.local.yaml stores values that vary by developer machine or CI runner. The init command creates it and adds it to .gitignore.

Web projects often need no local device binding at all. A web target can live entirely in agent-qa.config.yaml:

registry:
  targets:
    issue-tracker-web:
      platform: web
      product: issue-tracker
      url: http://localhost:3000

Use agent-qa.local.yaml when credentials or device/app paths should stay off the shared config:

providers:
  browserstack:
    username: ${BROWSERSTACK_USERNAME}
    accessKey: ${BROWSERSTACK_ACCESS_KEY}

devices

devices:
  android-local:
    serial: RZCT90BCMWW
    appPackage: com.company.issuetracker

Description: Per-device local match data keyed by registry.devices name.

Possible values: local Android and iOS match fields.

Required: only when a selected mobile device profile needs local bindings.

Default: no local device bindings.

Web tests usually do not set devices.

devices.android.avd

devices:
  android-local:
    avd: Pixel_8_API_35

Description: Android emulator name.

Possible values: Android Virtual Device name.

Default: not set.

devices.android.serial

devices:
  android-local:
    serial: RZCT90BCMWW

Description: Android device serial.

Possible values: serial reported by Android tooling.

Default: not set.

devices.android.appPackage

devices:
  android-local:
    appPackage: com.company.issuetracker

Description: Android app package override for this machine.

Possible values: package name string.

Default: inherited from registry.devices or target config.

devices.android.appActivity

devices:
  android-local:
    appActivity: .MainActivity

Description: Android app activity override for this machine.

Possible values: activity string.

Default: inherited from registry.devices or target config.

devices.android.automationName

devices:
  android-local:
    automationName: UiAutomator2

Description: Android automation engine.

Possible values: provider-supported automation name.

Default: not set.

devices.android.browserName

devices:
  android-local:
    browserName: Chrome

Description: Browser name for Android browser sessions.

Possible values: provider-supported browser name.

Default: not set.

devices.android.platformVersion

devices:
  android-local:
    platformVersion: "15"

Description: Android platform version.

Possible values: version string.

Default: not set.

devices.ios.udid

devices:
  ios-local:
    udid: 00008110-001234567890801E

Description: iOS device UDID.

Possible values: UDID string.

Default: not set.

devices.ios.bundleId

devices:
  ios-local:
    bundleId: com.company.issuetracker

Description: iOS bundle ID override for this machine.

Possible values: bundle ID string.

Default: inherited from registry.devices or target config.

devices.ios.automationName

devices:
  ios-local:
    automationName: XCUITest

Description: iOS automation engine.

Possible values: provider-supported automation name.

Default: not set.

devices.ios.platformVersion

devices:
  ios-local:
    platformVersion: "18"

Description: iOS platform version.

Possible values: version string.

Default: not set.

apps

apps:
  android-release:
    path: apps/issue-tracker-debug.apk

Description: Per-target app install overrides keyed by registry.targets name.

Possible values: path and browserstack.

Required: only when a native target needs a machine-specific app artifact.

Default: inherited from global target config.

Web tests usually do not set apps.

apps.path

apps:
  android-release:
    path: apps/issue-tracker-debug.apk

Description: Local app artifact path for this machine.

Possible values: relative path string.

Default: inherited from registry.targets.<target>.app.path.

apps.browserstack

apps:
  android-release:
    browserstack: bs://uploaded-app-id

Description: BrowserStack app reference override.

Possible values: BrowserStack app reference.

Default: inherited from registry.targets.<target>.app.browserstack.

providers

providers:
  browserstack:
    username: ${BROWSERSTACK_USERNAME}
    accessKey: ${BROWSERSTACK_ACCESS_KEY}

Description: Local provider credentials. For BrowserStack, agent-qa checks agent-qa.local.yaml first, then BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY.

Possible values: provider-specific credential objects.

Required: only when the provider needs local credentials.

Default: no local provider credentials.

providers.browserstack.username

providers:
  browserstack:
    username: ${BROWSERSTACK_USERNAME}

Description: BrowserStack username.

Possible values: string or environment-variable interpolation handled by your shell/tooling before use.

Default: falls back to BROWSERSTACK_USERNAME when local config does not provide a value.

providers.browserstack.accessKey

providers:
  browserstack:
    accessKey: ${BROWSERSTACK_ACCESS_KEY}

Description: BrowserStack access key.

Possible values: string or environment-variable interpolation handled by your shell/tooling before use.

Default: falls back to BROWSERSTACK_ACCESS_KEY when local config does not provide a value.

Generate local bindings

Use the devices command to scan connected devices and generate local bindings:

>npx agent-qa devices init

Review the generated file before running mobile tests. Local config should not be committed.

Local config

On this page