Skip to content
Skills Library
Programming · Testing

agent-qa-plugin-browserstack

/agent-qa-plugin-browserstack

Use when configuring agent-qa web or device tests to run on BrowserStack through the BrowserStack plugin, or when a BrowserStack remote is refused.

Repository
agent-qa ↗
Licence
Apache-2.0
Last repository change
11.11.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 11.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Use when configuring agent-qa web or device tests to run on BrowserStack through the BrowserStack plugin, or when a BrowserStack remote is refused.

Original author description

Use when configuring agent-qa web or device tests to run on BrowserStack through the BrowserStack plugin, or when a BrowserStack remote is refused.

How it works

  1. Declare the plugin
  2. A web remote
  3. A device remote
  4. Apps
  5. BrowserStack Local
  6. Links and marks
  7. When a remote is refused
  8. Check and describe
Original SKILL.md headings · 162 lines, 1,130 words
SKILL.md preview
---
name: agent-qa-plugin-browserstack
description: Use when configuring agent-qa web or device tests to run on BrowserStack through the BrowserStack plugin, or when a BrowserStack remote is refused.
---

# BrowserStack remotes for agent-qa

The BrowserStack plugin runs an agent-qa web test on a BrowserStack browser over the Playwright
protocol, and a device test on a BrowserStack Android or iOS device over Appium. It returns each
session's BrowserStack dashboard link and marks the session passed or failed when the test ends.

## Declare the plugin

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

- `username` and `accessKey` are credentials. Write them as `{{secret:<name>}}` references to
  names in the file `workspace.secretsFile` names. Never write the values in the config.
- `apiUrl`, `appApiUrl`, `hubUrl` and `playwrightUrl` default to BrowserStack's own endpoints.
  Leave them unset unless BrowserStack tells you otherwise.
- Add the plugin with `npx agent-qa plugins add @vostride/agent-qa-plugin-browserstack`: it pins the
  package at the project's agent-qa version and writes the `plugins` entry. `agent-qa plugins list`
  prints that line when the package is missing or the version differs.

## A web remote

```yaml
registry:
  remotes:
    - name: browserstack
      plugin: browserstack
      settings:
        os: Windows
        osVersion: "11"
```

- `use.browser.remote: browserstack` in the config, a suite or a test runs the test there.
- Settings: `os` (default `OS X`), `osVersion` (default `Sequoia`), `browser`, `browserVersion`,
  `project` (default `agent-qa`), `build` (default the run id) and `extra`, merged last into the
  capabilities.
- `browser` follows the test's engine by default: `chrome` for Chromium, `playwright-firefox` for
  Firefox, `playwright-webkit` for WebKit. A browser that cannot run the test's engine is refused
  at `settings.browser`.
- Web tests use the Playwright protocol, so BrowserStack must list agent-qa's Playwright version.
  The plugin carries BrowserStack's list. When agent-qa's major.minor is not on it, every web test
  on BrowserStack is refused with kind `version` and one line naming both versions. Run the test
  here or on another remote until a plugin release adds the version.

## A device remote

```yaml
registry:
  remotes:
    - name: browserstack-devices
      plugin: browserstack
      settings:
        appiumVersion: "3.5.2"
  devices:
    bs-pixel:
      platform: android
      remote: browserstack-devices
      model: Google Pixel 9
      os: "15"
  targets:
    shop-android:
      platform: android
      appPackage: com.example.shop
      device: bs-pixel
      app:
        ref: bs://f7c874f21852ba57957a3fdc33f47514288c4ba4
```

- The session asks BrowserStack's hub with `bstack:options`: the credentials, `appiumVersion`,
  `projectName`, `buildName` (the run id) and `sessionName` (the test's name).
- `appiumVersion` is the device's own `bstack:options.appiumVersion`, then
  `settings.appiumVersion`, then the plugin's default, `3.5.2`.
- `project`, `build` and `extra` work as on a web remote; `extra` merges into `bstack:options`.

## Apps

- `app.ref` wins. When a target sets it (a `bs://` id from an earlier upload, or an `https` URL),
  BrowserStack installs that app and nothing is uploaded.
- The plugin's `uploadApp` takes the target's `app.path`. It uploads the file once per content,
  under the custom id `agent-qa-<first 32 hex of the file's SHA-256>`, and reuses the newest
  upload listed under that id after that. It answers the `bs://` ref the session installs.
  BrowserStack keeps an upload for 30 days.

## BrowserStack Local

Use BrowserStack Local when the target is reachable only from this machine, for example
`localhost` or a host behind a VPN.

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

- `local: true` starts the plugin's own tunnel on the run's first acquire, with a fresh identifier
  (or `localIdentifier` when set too), and every web and device session of the run asks for it.
  The plugin stops the tunnel when the run ends, on stdin close and on `SIGTERM`.
- `localIdentifier` alone uses a tunnel you already run under that identifier; nothing is started.
- The tunnel comes from BrowserStack's `browserstack-local` package, which finds or downloads
  BrowserStack's binary. `localBinary` names a binary to run instead and needs `local: true`.
- The tunnel logs to a fresh file under the temp directory, never into the project.
- A tunnel that cannot start refuses the session with kind `unreachable` at path `options.local`,
  or `options.localBinary` when that is set; the line names the tunnel's log.
- Before it starts the tunnel, the plugin checks that this machine can run the binary. A binary
  this machine cannot run refuses the session the same way, with no log because the tunnel never
  ran, and the line's fix follows the cause:
  - `EBADARCH`, a Mac binary built for another CPU: install Rosetta
    (`softwareupdate --install-rosetta --agree-to-license`) or set `localBinary` to a binary
    built for this Mac. `browserstack-local` downloads BrowserStack's Intel build on every Mac,
    which an Apple Silicon Mac runs only under Rosetta.
  - `ENOENT`, a path that does not exist: set `localBinary` to the path of a BrowserStackLocal
    binary.
  - `EACCES`, a file that is not executable: make it executable, or set `localBinary` to one that
    is.
  - Any other failure: set `localBinary` to a binary this machine can run.
- BrowserStack's tunnel binary takes the access key as `--key` on its command line, by
  BrowserStack's design, so other users of the same machine can read it with `ps`.

## Links and marks

- When a session starts, the plugin returns its dashboard link to agent-qa: BrowserStack's
  `browser_url`, which needs a BrowserStack login. The shareable `public_url` is never returned.
- A passed test is marked `passed`. A failed test, or agent-qa's own error, is marked `failed`
  with the reason. A cancelled test stays unmarked.
- A web session is found through BrowserStack's REST API: the one running session in the build
  named for the run, whose name is the test's and that started after agent-qa asked for it. When
  none or several match, the test gets no link and the session stays unmarked, with one line on
  the plugin's stderr. A guessed session is never marked.

## When a remote is refused

- `auth`: BrowserStack refused the username or access key. Check the secrets' values.
- `capacity`: BrowserStack answered 429. The account's parallel sessions are in use, or the API
  rate limit was hit. Wait, or lower the run's concurrency.
- `version`: BrowserStack does not list agent-qa's Playwright version. Web tests cannot run there.
- `refused` with a path such as `settings.browser` or `apiUrl`: that field is wrong. The line says
  why.
- `refused` with no path: BrowserStack answered another error. The line has its status and
  message.
- `unreachable`: BrowserStack could not be reached. Check the network. At path `options.local` or
  `options.localBinary`, the BrowserStack Local tunnel did not start. When the tunnel ran, its log
  is named in the line; when this machine cannot run the binary, the line says how to fix it.

## Check and describe

- `agent-qa doctor` runs the plugin's account check. It reads the Automate and App Automate plans
  and reports running, allowed and queued parallel sessions for each. It warns when the
  credentials are refused, when a product is not on the account and when BrowserStack does not
  list agent-qa's Playwright version. It opens no session.
- `agent-qa plugins describe <entry> --json` lists every option and setting with its type,
  default and description.

Versions

The database has no other skills named agent-qa-plugin-browserstack.

Database snapshot: 13.11.2026 · package version b3d2eb4f9c10 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100browserstack
    Run tests on BrowserStack. Use when user mentions "browserstack", "cross-browser", "cloud testing", "browser matrix", "test on safari", "test on firefox", or "browser compatibility".
  • 100browserstack
    Run tests on BrowserStack. Use when user mentions "browserstack", "cross-browser", "cloud testing", "browser matrix", "test on safari", "test on firefox", or "browser compatibility".
  • 100browserstack
    Run tests on BrowserStack. Use when user mentions \"browserstack\", \"cross-browser\", \"cloud testing\", \"browser matrix\", \"test on safari\", \"test on firefox\", or \"browser compatibility\".
  • 95agent-qa-plugin-kernel
    Use when configuring agent-qa web tests to run in Kernel cloud browsers through the Kernel plugin, or when a Kernel remote is refused.
  • 95agent-qa-plugin-steel
    Use when configuring agent-qa web tests to run in Steel cloud browsers through the Steel plugin, or when a Steel remote is refused.
  • 100browserstack-migration-skill
    Migrate test automation from BrowserStack to TestMu AI (formerly LambdaTest) in any language or framework. Covers Automate (Selenium), App Automate (Appium, Espresso, XCUITest), the BrowserStack SDK and browserstack.yml, browserstack-cypress-cli, Playwright and Puppeteer over…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.