---
title: Web testing
description: Configure web targets and browser overrides for agent-qa tests that run through Playwright-managed Chromium, Firefox, or WebKit.
---



Web tests run against a target with `platform: web`. The target supplies the base `url`; the test supplies the journey.

For the complete file-backed config shape, see [Global Config](/docs/agent-qa/configuration/global-config) and [Test](/docs/agent-qa/configuration/test).

## Configure a web target [#configure-a-web-target]

`url` is required for every web target.

```yaml
registry:
  targets:
    issue-tracker-web:
      platform: web
      url: http://localhost:3000
```

Point `url` at the environment you want the agent to open: a local dev server, preview URL, staging app, or production-safe test tenant.

## Set browser defaults [#set-browser-defaults]

Global `use` values apply to tests unless a suite, test, or CLI flag overrides them.

```yaml
use:
  browser:
    name: chromium
    headless: true
    viewport:
      width: 1280
      height: 720
  timeout:
    navigation: 30s
    step: 90s
    test: 10m
  logCapture:
    console: true
    network: true
```

Supported browser names are `chromium`, `firefox`, and `webkit`.

## Override browser behavior per test [#override-browser-behavior-per-test]

Use per-test `use` when one flow needs a different engine, visible browser, viewport, timeout, or log capture behavior.

```yaml
test-id: t_vog-earing-wap-git-tim-assert-teras-mill-aus-ila
name: Verify responsive task filters
target: issue-tracker-web
use:
  browser:
    name: webkit
    headless: false
    viewport:
      width: 390
      height: 844
  timeout:
    navigation: 60s
    step: 2m
  logCapture:
    console: true
    network: false
steps:
  - Open the Tasks page.
  - Open the filter drawer.
  - Verify the status filters are visible.
```

`use.timeout.navigation` controls navigation actions. `use.timeout.step` controls one step. `use.timeout.test` controls the whole test run.

## Capture browser logs only when useful [#capture-browser-logs-only-when-useful]

`logCapture.console` allows the agent to read console logs during a web run. `logCapture.network` allows it to inspect network logs. Disable either one when a test should not depend on that signal.

```yaml
use:
  logCapture:
    console: false
    network: true
```

When console capture is disabled, a step that explicitly asks the agent to read console logs has no console data to use. Keep step wording aligned with the configured capture settings.

## Use CLI overrides for one-off runs [#use-cli-overrides-for-one-off-runs]

CLI browser flags take precedence over file-backed browser values for that run.

```bash
npx agent-qa run tests/find-task.yaml --browser firefox --headless false
```

Use file-backed config for committed project defaults and CLI flags for local debugging, CI matrix jobs, or temporary cross-browser checks.

## Reuse a signed-in browser session [#reuse-a-signed-in-browser-session]

Use [Auth state](/docs/agent-qa/guides/auth-state) when a web product should start already authenticated.

```yaml
target: issue-tracker-web
use:
  authState: qa-admin
steps:
  - Open the dashboard.
  - Verify the account menu is visible.
```

Auth state is resolved by target and logical name. Tests do not reference storage-state file paths directly.