---
name: browser-qa
description:
  Canonical browser-facing QA workflow for report-only, acceptance-gate, and fix-loop checks using Browser, Chrome,
  Playwright, web-evidence, browser-session, and workflow evidence primitives.
---

# Browser QA

Use this skill when a browser-facing claim needs QA judgment, real browser evidence, or a bounded fix loop.

## Contract

Prereqs:

- Target, scenario, expected behavior, and required evidence are known or can be derived from the user request, plan acceptance criteria,
  issue report, release check, CI/deploy preview, or project-specific test plan.
- Browser tooling is available for active checks: Browser, Chrome, Playwright, or the legacy `agent-browser` fallback when explicitly needed.
- `web-evidence` and `browser-session` are available when static or active evidence records are retained.
- A project-scoped run directory is available for artifacts, preferably from `agent-out project --topic browser-qa --mkdir`.
- Browser QA is required only when acceptance depends on browser behavior, not for every implementation task.

Inputs:

- Target URL, localhost address, deployment preview, existing browser surface, or static HTTP/HTTPS endpoint.
- QA mode: `report-only`, `acceptance-gate`, or `fix-loop`.
- Scenario source: user request, plan acceptance criteria, issue report, release validation, CI/deploy preview, PR delivery, or local test plan.
- Optional driver preference: Browser, Chrome, Playwright, `agent-browser`, or static `web-evidence`.
- Optional artifact requirements such as screenshot, DOM observation, console summary, network summary, Playwright output, or
  `browser-session.json`.

Outputs:

- A concise QA result with pass/fail/blocked status, checked scenarios, browser actions performed, and evidence artifact paths.
- `browser-session.json` for active browser QA, including goal, target, steps, statuses, artifacts, and `browser-session verify` outcome.
- Redacted screenshots, DOM observations, console summaries, network summaries, Playwright outputs, or static `web-evidence` bundles when
  they are safe and useful.
- Optional rendered report using `assets/templates/qa-report-template.md` when the user requests a QA report, fix-loop summary, or ship-readiness
  decision.
- For fix-loop mode, before/after evidence, project validation results, and linked `test-first-evidence`, `canary-check`,
  `review-evidence`, or `skill-usage` records when those primitives apply.

Exit codes:

- N/A (workflow-only skill; failures surface through Browser, Chrome, Playwright, `agent-browser`, `web-evidence`, `browser-session`,
  `test-first-evidence`, `canary-check`, `review-evidence`, `skill-usage`, or project validation commands).

Failure modes:

- Target is unavailable, unstable, blocked by network policy, or requires credentials the user has not approved using.
- Static evidence is requested but the claim requires JavaScript, layout, screenshots, DOM interaction, authenticated state, console output,
  network behavior, or browser storage/state.
- Active browser tooling is unavailable and no scoped fallback can perform the required check.
- Requested evidence would retain raw cookies, credentials, auth headers, bearer tokens, tokenized URLs, secret form values, storage dumps,
  customer data, or unredacted network logs.
- The check requires CAPTCHA, MFA, payment, destructive actions, access-control bypass, or unsafe credential handling.
- Fix-loop scope exceeds the user's request, lacks failing evidence or a recorded waiver, or cannot be validated with project-required checks.

## Entrypoint

- None. This is a scriptless workflow skill. Use existing tools and evidence primitives; do not add placeholder scripts.

## Mode Selection

Use the lightest mode that can prove or disprove the claim:

- Static evidence: use `web-evidence` only when HTTP status, headers, redirects, and a redacted text preview are enough. Static evidence does
  not prove browser behavior.
- Report-only: inspect with Browser, Chrome, Playwright, or `agent-browser`; record observations and artifacts; do not edit files, commit,
  or run a fix loop.
- Acceptance-gate: prove or disprove a browser-facing acceptance criterion for plan execution, release, CI, issue follow-up, PR delivery, or
  project validation. Active browser checks require real browser work before success can be recorded.
- Fix-loop: reproduce the browser issue with scoped evidence, capture failing-test evidence or an explicit waiver before production behavior
  edits, make the smallest fix, run project validation, capture after evidence, and record the final outcome.

Choose active browser QA when acceptance depends on JavaScript-rendered UI, screenshots, layout, responsive behavior, DOM interaction,
client-side routing, downloads, forms, authenticated browser state, cookies, console output, network behavior, or deploy-preview inspection.

## Scenario Intake

Normalize each scenario before acting:

- Source: user request, plan task, issue report, release gate, CI/deploy preview, PR review, or project test plan.
- Target: URL, localhost route, browser tab, deploy preview, or static endpoint.
- Expected behavior: visible UI state, interaction result, console/network condition, artifact requirement, or static response property.
- Mode: static evidence, report-only QA, acceptance-gate QA, or fix-loop QA.
- Safety: credential, privacy, destructive-action, payment, MFA, CAPTCHA, and data-retention constraints.

When the scenario is browser-facing and tied to a plan, keep the plan concise and link evidence artifact paths from execution state instead
of copying large reports into the plan.

## Driver Selection

- Browser: use the Codex in-app Browser for local targets, unauthenticated pages, quick interactive inspection, screenshots, and localhost QA.
- Chrome: use the user's Chrome profile only when the task needs existing cookies, logged-in state, extensions, existing tabs, or another
  user-profile-dependent browser session. Do not export cookies or profile state.
- Playwright: use the repo Playwright wrapper when a repeatable CLI-driven browser path is better than interactive inspection and the target
  does not require the user's existing Chrome state. Keep Playwright artifacts under `out/playwright/` through the existing wrapper contract.
- `agent-browser`: use only as a legacy fallback when `snapshot -i` / `@ref` behavior is needed or native Browser/Chrome/Playwright tooling
  is unavailable or insufficient.
- `web-evidence`: use only for deterministic static HTTP/HTTPS evidence when browser behavior is not required.

## Evidence Requirements

Active QA success requires real browser work plus a verified session record:

1. Create a project-scoped run directory.
2. Initialize `browser-session` with the target, goal, mode, and chosen driver.
3. Perform the real browser action: open, inspect, interact, capture, or run Playwright.
4. Record each meaningful step with artifact paths.
5. Run `browser-session verify` and record the outcome in the final report, execution state, issue comment, release note, or PR evidence as
   appropriate.

Useful artifact types include screenshots, DOM observations, console summaries, network summaries, Playwright screenshots/snapshots/traces,
static `web-evidence` `summary.json`, `headers.redacted.json`, `body-preview.redacted.txt`, and `browser-session.json`.

## Report Template

Use `assets/templates/qa-report-template.md` when the user asks for a report, a fix-loop
summary, or a ship-readiness decision. Keep the report as a summary layer over
recorded evidence; do not treat scores or prose as a substitute for
`browser-session`, screenshots, Playwright outputs, static `web-evidence`, or
project validation artifacts.

The template includes:

- Overall `Health Score: {SCORE}/100`.
- Category scores for Console, Links, Visual, Functional, UX, Performance, and
  Accessibility.
- Evidence index paths for `browser-session.json`, screenshots, DOM
  observations, console summaries, network summaries, Playwright output, and
  static `web-evidence`.
- Before/after screenshot fields for fix-loop evidence.
- Ship Readiness verdict, metric table, and PR summary line.

Score only what was actually checked. Mark untested categories as `N/A` and
explain the coverage gap instead of inventing precision.

## Redaction Guardrails

- Keep browser QA evidence project-scoped and redacted by default.
- Do not retain raw cookies, credentials, auth headers, bearer tokens, tokenized URLs, secret query strings, secret form values, local storage
  dumps, session storage dumps, customer data, or unredacted network logs.
- For screenshots that reveal secrets or personal data, avoid retaining the screenshot, capture a safer viewport/state, or create a redacted
  derivative before linking it.
- Summarize console and network evidence to the minimum useful facts; remove secret query parameters and fragments from URLs.
- If only unsafe evidence is available, do not retain it. Record the check as blocked, explain what unsafe evidence would be required, and
  link only safe diagnostic artifacts.
- Do not commit run directories unless the project explicitly defines a retained, redacted evidence path.

## Fix Loop

Use fix-loop mode only when the user has asked for repair or the workflow being executed authorizes repair.

1. Reproduce the issue with browser evidence and record the failed or blocked `browser-session` step.
2. Before editing production behavior, record failing-test evidence with `test-first-evidence` or record an explicit waiver with substitute
   validation.
3. Make the smallest scoped fix; stop and report blocked if the fix exceeds scope or requires unsafe credentials/actions.
4. Run project-required validation. A local one-command `canary-check` may supplement the gate but cannot replace required tests.
5. Capture after evidence with active browser QA when the original claim depended on browser behavior.
6. Link `review-evidence` when findings need durable review tracking. Link `skill-usage` only when the workflow invocation needs a retained
   usage record.

## Relationship To Nearby Skills

- `web-evidence`: static HTTP/HTTPS evidence primitive; it does not drive a browser.
- `browser-session`: browser QA evidence ledger; it records goals, steps, statuses, and artifact paths but is not a browser driver.
- `playwright`: CLI-driven browser runtime wrapper with artifacts under `out/playwright/`.
- `agent-browser`: optional legacy browser automation fallback.
- `web-qa`: compatibility entrypoint for older requests; route new browser-backed QA work to `browser-qa`.
- `test-first-evidence`, `canary-check`, `review-evidence`, and `skill-usage`: workflow evidence primitives linked when their specific
  record contracts apply.
