agent-qa-plugin-browserstack Skill
在配置 agent-qa 网页或设备测试通过 BrowserStack 插件运行时使用,或在 BrowserStack 远程连接被拒绝时使用。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
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
plugins:
- name: browserstack
package: "@vostride/agent-qa-plugin-browserstack"
options:
username: "{{secret:BROWSERSTACK_USERNAME}}"
accessKey: "{{secret:BROWSERSTACK_ACCESS_KEY}}"
usernameandaccessKeyare credentials. Write them as{{secret:}}references to
names in the file workspace.secretsFile names. Never write the values in the config.
apiUrl,appApiUrl,hubUrlandplaywrightUrldefault 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
registry:
remotes:
- name: browserstack
plugin: browserstack
settings:
os: Windows
osVersion: "11"
use.browser.remote: browserstackin the config, a suite or a test runs the test there.- Settings:
os(defaultOS X),osVersion(defaultSequoia),browser,browserVersion,
project (default agent-qa), build (default the run id) and extra, merged last into the
capabilities.
browserfollows the test's engine by default:chromefor Chromium,playwright-firefoxfor
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
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).
appiumVersionis the device's ownbstack:options.appiumVersion, then
settings.appiumVersion, then the plugin's default, 3.5.2.
project,buildandextrawork as on a web remote;extramerges intobstack:options.
Apps
app.refwins. When a target sets it (abs://id from an earlier upload, or anhttpsURL),
BrowserStack installs that app and nothing is uploaded.
- The plugin's
uploadApptakes the target'sapp.path. It uploads the file once per content,
under the custom id agent-qa-, 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.
plugins:
- name: browserstack
package: "@vostride/agent-qa-plugin-browserstack"
options:
username: "{{secret:BROWSERSTACK_USERNAME}}"
accessKey: "{{secret:BROWSERSTACK_ACCESS_KEY}}"
local: true
local: truestarts 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.
localIdentifieralone uses a tunnel you already run under that identifier; nothing is started.- The tunnel comes from BrowserStack's
browserstack-localpackage, 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
unreachableat pathoptions.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: setlocalBinaryto the path of a BrowserStackLocal
binary.
EACCES, a file that is not executable: make it executable, or setlocalBinaryto one that
is.
- Any other failure: set
localBinaryto a binary this machine can run. - BrowserStack's tunnel binary takes the access key as
--keyon 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 markedfailed
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.refusedwith a path such assettings.browserorapiUrl: that field is wrong. The line says
why.
refusedwith no path: BrowserStack answered another error. The line has its status and
message.
unreachable: BrowserStack could not be reached. Check the network. At pathoptions.localor
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 doctorruns 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 --jsonlists every option and setting with its type,
default and description.