Hyperbrowser

The Hyperbrowser plugin, @vostride/agent-qa-plugin-hyperbrowser, gives each web test a Hyperbrowser browser session. Before the test connects, it creates the session through Hyperbrowser's API and hands agent-qa its CDP address. After the test it stops the session.

Hyperbrowser runs Chromium only, so tests on a Hyperbrowser remote use use.browser.name: chromium. Stealth, proxies, CAPTCHA solving, ad, tracker and annoyance blocking and cookie banner acceptance are off unless a setting turns them on, so a test sees your app the way your users do.

InstallCopy Anchor Link

Install the plugin at exactly the version of agent-qa your project runs:

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

ConfigureCopy Anchor Link

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

use:
  browser:
    name: chromium
    headless: true
    remote: hyperbrowser

Put the key in your secrets file, .env.secrets.local by default, as HYPERBROWSER_API_KEY=....

OptionsCopy Anchor Link

Options belong to the plugins entry and describe the account.

The key is sent only as the x-api-key header, and never appears in logs, run records or doctor output.

SettingsCopy Anchor Link

Settings belong to each remote and describe one place.

Proxies and CAPTCHA solving need a paid Hyperbrowser plan.

How the request is builtCopy Anchor Link

The plugin builds Hyperbrowser's create request in this order, each part overriding the one before:

1. the lifetime, timeoutMinutes;
2. the features that change the page, each sent off unless a setting turns it on;
3. the proxy fields: proxy: true turns Hyperbrowser's proxy on, and a proxy object also sends the country, state and city it gives;
4. the other settings, each only when it is set;
5. extra, last, so a field there overrides both a default and a setting.

For example, settings: { extra: { useUltraStealth: true } } asks for Hyperbrowser's Enterprise stealth mode. Enterprise proxy servers go through extra too, with the password as a secret reference:

settings:
  extra:
    proxyServer: "http://proxy.example.com:8080"
    proxyServerUsername: "<proxy user>"
    proxyServerPassword: "{{secret:HYPERBROWSER_PROXY_PASSWORD}}"

Lifetime and disconnectsCopy Anchor Link

By default the plugin asks for a 720-minute session, the longest Hyperbrowser allows. agent-qa stops every session itself after its test; the lifetime only bounds a session it could not stop.

The plugin never asks Hyperbrowser to keep a session alive, so Hyperbrowser stops a session whose connection drops. A session left behind by a killed job stops with its connection. If a job is killed while a session is still being created, that session was never connected, so it runs until timeoutMinutes. Lower timeoutMinutes to bound it.

RecordingCopy Anchor Link

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 a remote to turn recording off for its sessions, as hyperbrowser-unrecorded does above.

Video replay is off unless you ask for it with extra: { enableVideoWebRecording: true }. It needs web recording, so do not combine it with recording: false.

The session link is the session's page in Hyperbrowser's dashboard, returned only when it is an https:// URL. Hyperbrowser's live view URL and session token let anyone who has them watch and drive the session, so agent-qa masks both and never shows them.

Signed-in profilesCopy Anchor Link

profile loads a Hyperbrowser profile by ID, and nothing a test does is saved back to it. A profile lives in the browser's first context, so the remote needs context: reuse:

registry:
  remotes:
    - name: hyperbrowser-signed-in
      plugin: hyperbrowser
      context: reuse
      settings:
        profile: <Hyperbrowser profile ID>

Account checkCopy Anchor Link

agent-qa doctor runs the plugin's account check, which reads your active sessions and opens none:

• an accepted key reads the API key was accepted, with the number of active sessions when Hyperbrowser gives it, such as 2 active sessions;
• a refused key warns the API key was refused.

When a remote is refusedCopy Anchor Link

Hyperbrowser chooses the session ID, so when a create request fails there is no session to stop. On release, a session Hyperbrowser has already stopped counts as stopped.

npx agent-qa plugins describe hyperbrowser --json lists every option and setting with its type, default and description.