Web testing

agent-qa tests web apps through Playwright, in a browser it installs and manages itself. Your everyday browsers are untouched.

Add a targetCopy Anchor Link

A target names the app and where it runs:

registry:
  targets:
    shop-local:
      platform: web
      url: http://127.0.0.1:3000
      environment: local

A test picks it with target: shop-local. The target's url is where each test starts. Add one target per environment you test, such as local, staging and preview. environment is a label only: agent-qa runs every target the same way, so point tests at production only with accounts and data you can afford to change.

Install a browserCopy Anchor Link

npx agent-qa init downloads Chromium when it sets up a web project, and a re-run offers to install it again when this machine has none. Install it yourself for a project set up with --no-browsers, or on a CI runner:

npx agent-qa install-browsers --chromium

Use --firefox, --webkit or --all for the others, and --with-deps on Linux to install the system libraries too.

Browser settingsCopy Anchor Link

use:
  browser:
    name: chromium
    headless: true
    viewport:
      width: 1280
      height: 720

name is chromium, firefox or webkit. These settings live under use, so a suite or a single test can override them. To watch a run, use --no-headless:

npx agent-qa run tests/checkout.yaml --no-headless

AGENT_QA_HEADLESS=false does the same through the environment.

Remote browsersCopy Anchor Link

Tests run in a browser agent-qa launches on this machine unless your files pick a remote: a Playwright server, a CDP endpoint, or a cloud browser service through a plugin.

registry:
  remotes:
    - name: grid
      protocol: playwright
      url: wss://grid.example.com/playwright
      query:
        token: "{{secret:GRID_TOKEN}}"

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

Set use.browser.remote in the config for every test, or in a suite or test to move only those. See Remote browsers and devices, and Plugins for BrowserStack, Hyperbrowser, Kernel and Steel.

TimeoutsCopy Anchor Link

use:
  timeout:
    step: 20m
    test: 90m
    navigation: 2m

A step that runs past step fails. A test that runs past test ends with the timeout verdict. navigation bounds page loads. The values above are what init writes.

Console and network logsCopy Anchor Link

agent-qa records the browser console and network traffic for every step:

use:
  logCapture:
    console: true
    network: true

Read them in the dashboard's Console and Network tabs, or with agent-qa runs evidence <runId> --test 0 --step 2 --kind network --json.

Accessibility checksCopy Anchor Link

agent-qa runs axe-core accessibility checks on web pages:

services:
  accessibility:
    enabled: true
    standard: wcag2aa
    runAfter: test-end
    failOnViolation: false

Results appear in the dashboard's A11y tab and through --kind a11y evidence.

Session videosCopy Anchor Link

Every run records a video of the browser session by default. Turn it off for one run with --no-record, for one test with meta.record: false, or for the project:

services:
  recording:
    enabled: true
    keepFailuresOnly: true

keepFailuresOnly drops the videos of tests that passed.

Tests behind a loginCopy Anchor Link

Sign in once by hand and let tests reuse the session: Saved logins. For logins that need fresh data on every run, use a hook.

Run JavaScript in the pageCopy Anchor Link

A step can run a snippet in the page and use its result:

steps:
  - Verify the cart badge shows {{runJS:"document.querySelectorAll('.cart-item').length"}} items.