v0.2.x to v0.3.x

What's newCopy Anchor Link

agent-qa v0.3 can run tests somewhere other than your machine, and describes every device in the committed config.

• Remote browsers and devices. List a Playwright server, a CDP endpoint or an Appium server under registry.remotes, and pick it with use.browser.remote or a device's remote. See Remote browsers and devices.
• First-party plugins. BrowserStack, Hyperbrowser, Kernel and Steel each have a plugin that creates a session before a test and releases it after. plugins is now one list of named entries, and the plugin kit lets you write your own.
• Devices by model. A device says what it is, such as model: Pixel 8 and os: "15", and agent-qa finds it on this machine. A target names its default device. agent-qa devices shows where each device runs and what this machine has.
• New commands. agent-qa plugins list, agent-qa plugins describe <entry>, agent-qa plugin validate <target>, agent-qa devices and agent-qa doctor --remote <name>.

How to upgradeCopy Anchor Link

v0.3 upgrades in place. Your tests, suites, hooks, knowledge and recorded runs carry over; only some config keys change.

Upgrade this project from agent-qa v0.2 to v0.3. Do the work, rather than only describing it.

Read the upgrade guide first: https://vostride.com/docs/agent-qa/migrate/v0-2-to-v0-3.md

v0.3 upgrades in place. Keep the tests, suites, hooks, knowledge and recorded runs.

1. Find agent-qa.config.yaml and the files it names. Stop any agent-qa dashboard or MCP server you started.
2. Upgrade agent-qa with this repository's package manager. If the project uses a Claude or Codex subscription, upgrade @vostride/agent-qa-subscription-auth too.
3. Run npx agent-qa validate. Every removed key is refused with a sentence that says what to do. Fix each one, using the tables in the guide.
4. If agent-qa.local.yaml exists, move each device into registry.devices in agent-qa.config.yaml, described by model and os, and each app path into its target's app.path, and set the target's device. Run npx agent-qa devices to see the model names this machine has. Then delete agent-qa.local.yaml.
5. If the project ran on BrowserStack, install @vostride/agent-qa-plugin-browserstack at exactly the agent-qa version, and add its plugins entry, remote and devices as the guide shows. Ask me to put BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY in the secrets file; never write their values yourself.
6. Run npx agent-qa validate until it passes, then npx agent-qa doctor and npx agent-qa plugins list, and fix what they report.
7. Run one of my own tests or suites and report its verdict.

Never print secrets or put credentials in YAML or commands. Report what you changed, and anything I still need to do.

1. Update the packagesCopy Anchor Link

   npm install -D agent-qa@latest

   If you sign in with a Claude or Codex subscription, update @vostride/agent-qa-subscription-auth to the latest version too.

2. ValidateCopy Anchor Link

   npx agent-qa validate

   Every removed key is refused with one sentence that says what to do, and a leftover agent-qa.local.yaml stops every command that loads the config. Work through them with the tables below.

3. Check the setupCopy Anchor Link

   npx agent-qa devices
   npx agent-qa doctor

   Then run one of your own tests or suites.

What changed in your filesCopy Anchor Link

pluginsCopy Anchor Link

plugins is a list of named entries, and plugins.auth is gone. The subscription sign-in plugin becomes the subscription entry:

# v0.2
plugins:
  auth:
    - package: "@vostride/agent-qa-subscription-auth"

# v0.3
plugins:
  - name: subscription
    package: "@vostride/agent-qa-subscription-auth"

plugins.providers is gone. A model provider plugin must be an @vostride/agent-qa-* package, so a third-party one is refused; use openai-compatible or anthropic-compatible with a baseURL instead.

agent-qa.local.yamlCopy Anchor Link

agent-qa no longer reads agent-qa.local.yaml, and refuses to start while the file exists:

agent-qa.local.yaml is no longer read: describe each device under registry.devices with model and os (id pins one unit), and set app.path on the target. Delete the file.

Move each part into agent-qa.config.yaml, then delete the file:

# v0.2: agent-qa.config.yaml
registry:
  devices:
    pixel:
      platform: android
      transport: local
  targets:
    my-app:
      platform: android
      appPackage: com.example.app
      appActivity: .MainActivity

# v0.2: agent-qa.local.yaml
devices:
  pixel:
    avd: Pixel_8_API_35
apps:
  my-app:
    path: builds/my-app-debug.apk

# v0.3: agent-qa.config.yaml
registry:
  devices:
    pixel:
      platform: android
      model: Pixel 8
  targets:
    my-app:
      platform: android
      appPackage: com.example.app
      appActivity: .MainActivity
      device: pixel
      app:
        path: builds/my-app-debug.apk

registry.devicesCopy Anchor Link

A test without use.device now runs on its target's device. --device still picks a device for a run, but only one on this machine.

BrowserStackCopy Anchor Link

agent-qa no longer reads BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY from the environment, and has no built-in BrowserStack transport. Install the plugin, put the two values in your secrets file, and add an entry and a remote:

npm install --save-dev --save-exact @vostride/agent-qa-plugin-browserstack@$(npx agent-qa --version)

plugins:
  - name: browserstack
    package: "@vostride/agent-qa-plugin-browserstack"
    options:
      username: "{{secret:BROWSERSTACK_USERNAME}}"
      accessKey: "{{secret:BROWSERSTACK_ACCESS_KEY}}"

registry:
  remotes:
    - name: browserstack-devices
      plugin: browserstack
  devices:
    bs-pixel:
      platform: android
      remote: browserstack-devices
      model: Google Pixel 9
      os: "15"

A target's app.browserstack becomes app.ref, or leave app.ref out and the plugin uploads app.path for you. registry.providers is gone.

Other removed keysCopy Anchor Link

These went away in late v0.2 releases. Each one is refused with a message that says what to do.

CommandsCopy Anchor Link