Kernel

The Kernel plugin, @vostride/agent-qa-plugin-kernel, gives each web test a Kernel cloud browser. Before the test connects, it creates a browser, or takes one from a browser pool, and hands agent-qa the browser's CDP address. After the test it deletes the browser, or returns it to the pool.

Kernel runs Chromium only, so tests on a Kernel remote use use.browser.name: chromium.

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-kernel@$(npx agent-qa --version)

ConfigureCopy Anchor Link

plugins:
  - name: kernel
    package: "@vostride/agent-qa-plugin-kernel"
    options:
      apiKey: "{{secret:KERNEL_API_KEY}}"

registry:
  remotes:
    - name: kernel
      plugin: kernel
      settings:
        headless: true
        timeoutSeconds: 60

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

Put the key in your secrets file, .env.secrets.local by default, as KERNEL_API_KEY=.... Set use.browser.remote in the config to run every web test on Kernel, or in a suite or test to move only those.

OptionsCopy Anchor Link

Options belong to the plugins entry and describe the account.

The key is sent only as the Authorization: Bearer header, and never appears in logs or run records.

SettingsCopy Anchor Link

Settings belong to each remote and describe one place.

How the request is builtCopy Anchor Link

The plugin builds Kernel's create request in three layers, each overriding the one before:

1. its defaults, headless: true and timeout_seconds: 60;
2. the settings above, in Kernel's field names, so timeoutSeconds is sent as timeout_seconds and viewport.refreshRate as viewport.refresh_rate;
3. extra, last, so a field there overrides both a default and a setting.

For example, settings: { headless: true, extra: { headless: false, kiosk_mode: true } } creates a headful browser in kiosk mode.

Browser poolsCopy Anchor Link

A pool keeps browsers warm, so a test does not wait for one to start. Name the pool on a remote:

registry:
  remotes:
    - name: kernel-pool
      plugin: kernel
      settings:
        pool: shop-tests

• While the pool is empty, the plugin keeps asking, at most once a second, and agent-qa prints waiting for pool shop-tests while it waits. The wait ends when a browser is free or at the remote's connectTimeout, five minutes by default.
• The pool's own configuration decides the browser, so stealth, region, proxy and viewport are refused on a remote with pool, and headless and timeoutSeconds do not apply. Only profile and extra are sent.
• After a test in a new context, the browser goes back to the pool for the next test. After a test with context: reuse, it is discarded, so the next test gets a clean one.

Signed-in profilesCopy Anchor Link

profile loads a Kernel profile, such as one saved with a signed-in test user. It loads read-only: nothing a test does is saved back. A profile lives in the browser's first context, so the remote needs context: reuse:

registry:
  remotes:
    - name: kernel-signed-in
      plugin: kernel
      context: reuse
      settings:
        profile: shop-test-user

Without context: reuse, the remote is refused with kind refused at settings.profile. With pool, the profile goes into the pool request, and Kernel discards that browser after the test.

Links and the live viewCopy Anchor Link

Kernel has no page per session, so a Kernel test shows no session link. A headful browser's live view URL carries a token, so agent-qa masks it along with the CDP address, and never shows it as a link.

Account checkCopy Anchor Link

agent-qa doctor runs the plugin's account check, which creates no browser:

• it lists your browsers to confirm the key works, and warns the API key was refused when Kernel refuses it;
• it reports free sessions, such as 3 of 5 concurrent sessions free, when the key may read the organization's limits;
• it looks up each pool a remote names, and warns pool <pool> not found when Kernel has none by that name.

When a remote is refusedCopy Anchor Link

Each refusal is one line with Kernel's status, the request and Kernel's message, and the wait Kernel asked for on a 429. A browser that is already gone when the plugin deletes it counts as released.

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