---
title: "Web testing"
description: "Configure agent-qa web targets and per-test browser overrides for Playwright-managed Chromium, Firefox, and WebKit runs, including viewport and headless settings."
canonical_url: "https://vostride.com/docs/agent-qa/guides/web-testing"
md_url: "https://vostride.com/docs/agent-qa/guides/web-testing.md"
last_updated: "2026-10-18T00:19:04+05:30"
---

> [Documentation index](https://vostride.com/docs.md) · [Site index](https://vostride.com/llms.txt)
> Follow the Markdown links to read individual pages; the indexes list the available documentation.

# Web testing

> Configure agent-qa web targets and per-test browser overrides for Playwright-managed Chromium, Firefox, and WebKit runs, including viewport and headless settings.

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](https://vostride.com/docs/agent-qa/configuration/global-config.md) and [Test](https://vostride.com/docs/agent-qa/configuration/test.md).

## 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
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
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
`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
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
Use [Auth state](https://vostride.com/docs/agent-qa/guides/auth-state.md) 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.

## Documentation navigation

- [All documentation](https://vostride.com/docs.md)
- Parent: [What is agent-qa](https://vostride.com/docs/agent-qa.md)
- Previous: [Write your first test](https://vostride.com/docs/agent-qa/guides/first-test.md)
- Next: [Auth state](https://vostride.com/docs/agent-qa/guides/auth-state.md)