agent-qa-plugin-hyperbrowser Skill
在配置 agent-qa 网页测试通过 Hyperbrowser 插件运行于 Hyperbrowser 云浏览器时使用,或在 Hyperbrowser 远程连接被拒绝时使用。
安装方式:把技能目录放入 ~/.claude/skills/(Claude Code)或在 claude.ai 设置中启用;也可复制右侧安装命令一键添加。
技能指令原文(SKILL.md)
Hyperbrowser remotes for agent-qa
The Hyperbrowser plugin gives an agent-qa web test a Hyperbrowser browser session. Before the test
connects it creates a session through Hyperbrowser's API, and after the test it stops the session.
Hyperbrowser runs Chromium only. Stealth, proxies, CAPTCHA solving, ad, tracker and annoyance
blocking and cookie auto-accept are off unless a setting turns them on, so a test sees the app the
way its users do.
Declare the plugin and a remote
plugins:
- name: hyperbrowser
package: "@vostride/agent-qa-plugin-hyperbrowser"
options:
apiKey: "{{secret:HYPERBROWSER_API_KEY}}"
registry:
remotes:
- name: hyperbrowser
plugin: hyperbrowser
- name: hyperbrowser-unrecorded
plugin: hyperbrowser
settings:
recording: false
- The
pluginsentry holds the account:apiKey, which is required, andapiUrl, which defaults
to https://api.hyperbrowser.ai. Write the key as a {{secret:}} reference to a name in
the file workspace.secretsFile names. Never write the key itself in the config.
- The remote holds one place:
pluginnames thepluginsentry, andsettingshold that place's
Hyperbrowser settings.
use.browser.remote: hyperbrowserin the config, a suite or a test runs the test there.- Add the plugin with
npx agent-qa plugins add @vostride/agent-qa-plugin-hyperbrowser: 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.
Settings
timeoutMinutes(default720, 1 to 720): minutes before Hyperbrowser stops the session. It
overrides the team default in Hyperbrowser's settings. The plugin never asks for keep-alive, so
Hyperbrowser also stops a session whose connection drops, and agent-qa stops every session after
its test. A session whose create was in flight when the job was killed was never connected, so
it runs until timeoutMinutes.
recording(unset by default): Hyperbrowser's web recording. Unset keeps the account's default,
which records. recording: false turns it off.
stealth,solveCaptchas,adblock,trackers,annoyances,acceptCookies(each default
false): Hyperbrowser's stealth mode, CAPTCHA solving, ad, tracker and annoyance blocking and
automatic acceptance of cookie banners.
proxy(defaultfalse):true, or{ country, state, city }with any of the three. Proxies
and CAPTCHA solving need a paid Hyperbrowser plan.
screen({ width, height }in pixels),region(for exampleus-eastoreurope-west),
extensions (extension ids): Hyperbrowser's own create fields, sent only when set.
profile: a Hyperbrowser profile id. It loads read-only: nothing the test does is saved back. It
needs context: reuse on the remote, because the profile lives in the browser's first context:
- name: hyperbrowser-signed-in
plugin: hyperbrowser
context: reuse
settings:
profile: <Hyperbrowser profile id>
extra: any other Hyperbrowser request field. It is merged last, so it overrides the settings
above. Video replay is extra: { enableVideoWebRecording: true }, and needs recording on.
Enterprise proxy servers go here as proxyServer, proxyServerUsername and
proxyServerPassword; write the password as a {{secret:}} reference.
When a remote is refused
auth: Hyperbrowser refused the API key. Check the secret's value.capacity: Hyperbrowser answered 429. The account has no free sessions, or is rate limited.
Wait, or lower the run's concurrency.
refusedwithHyperbrowser answered 403 to POST /api/session:: a feature the remote
turns on is not on the plan, for example Proxy usage requires a paid plan. Turn that setting
off, or change the plan.
refusedwith pathsettings.profile: the remote setsprofilewithoutcontext: reuse. Add
context: reuse to the remote.
refusedwith pathsettings.timeoutMinutes: the lifetime is outside 1 to 720. Set a value in
that range, or leave it out for 720.
refusednaming a browser or platform: Hyperbrowser runs Chromium web tests only. Use
use.browser.name: chromium, or another remote.
refusedatoptions.apiUrl: the endpoint must usehttps://with no user or password, unless
it points at this machine.
unreachable: Hyperbrowser could not be reached. Check the network andapiUrl.
Recording
Hyperbrowser records sessions by default and keeps the replay on its dashboard, behind its login.
agent-qa's masking does not reach that replay, so a secret a test types may show in it. Set
recording: false on the remote to turn recording off. The session link opens the session's page
in Hyperbrowser's dashboard. Hyperbrowser's live view URL and the session token let anyone who has
them watch and drive the session, so agent-qa masks both and never shows them as the link.
Check and describe
agent-qa doctorruns the plugin's account check. It reads the active sessions to prove the key,
reports how many there are, and opens none.
agent-qa plugins describe hyperbrowser --jsonlists every option and setting with its type,
default and description.