---
name: web-qa
description:
  Compatibility entrypoint for legacy web-qa requests; route new browser-backed QA work to browser-qa while preserving
  web-evidence and browser-session examples.
---

# Web QA Compatibility

Use this skill only as a compatibility bridge for existing `web-qa` references.

## Contract

Prereqs:

- Prefer `browser-qa` for new browser-backed QA work, acceptance gates, and fix loops.
- Define the target, goal, expected behavior, and required evidence before capturing.
- Choose a project-scoped run directory, preferably from `agent-out project --topic browser-qa --mkdir`.
- Use `web-evidence` for static HTTP/HTTPS captures and `browser-session` for evidence records when session traceability is useful.
- Use Browser, Chrome, Playwright, or `agent-browser` for active browser operations only through the `browser-qa` workflow.
- Do not add skill-local scripts or placeholder scripts; this compatibility skill preserves examples for existing callers.

Inputs:

- Legacy `web-qa` request, target URL, localhost address, deployment preview, or existing browser surface.
- QA goal and acceptance criteria.
- Mode choice: `static` or compatibility handoff to `browser-qa`.
- Optional artifact requirements such as screenshot, DOM observation, console summary, network summary, or static response bundle.

Outputs:

- Static mode writes a redacted `web-evidence capture` bundle, including
  `summary.json`, `headers.redacted.json`, and optional
  `body-preview.redacted.txt`.
- Active browser requests are routed to `browser-qa`, which records browser actions and artifacts with `browser-session`.
- When `browser-session` is used, writes `browser-session.json` with goal, target, steps, statuses, and artifact paths.
- Final response states whether compatibility routing occurred and summarizes evidence paths, pass/fail status, or blocked state without
  exposing secrets.

Exit codes:

- `web-evidence capture` returns `0` for successful captures, `1` for runtime/network/HTTP failures, and `64` for usage errors.
- `browser-session verify` returns `0` when the evidence record is complete and all recorded steps passed, `1` when evidence is incomplete
  or a step failed, and `64` for usage errors.
- Browser, Chrome, Playwright, and `agent-browser` failures are tool-specific and should be handled by `browser-qa`.

Failure modes:

- Required browser or nils-cli evidence tool is unavailable.
- Target is inaccessible, unstable, blocked by network policy, or requires unavailable credentials.
- Static HTTP evidence is insufficient because the claim depends on JavaScript, DOM state, browser storage, screenshots, interaction,
  console logs, network behavior, or authenticated state.
- The requested evidence would retain raw cookies, credentials, auth headers, tokenized URLs, secret form values, or unredacted network
  logs.
- CAPTCHA, MFA, payment, destructive actions, or access-control bypass would be required.
- Artifact directory cannot be created or verified.

## Compatibility Status

`web-qa` is a supported compatibility surface for at least one transition. It is no longer the canonical browser QA workflow.

New browser-backed QA work should invoke `browser-qa`, especially for report-only QA, acceptance gates, and fix loops.

Future removal criteria:

- Catalogs, workflow skills, and automation docs no longer direct new work to `web-qa`.
- Existing external references have been migrated or explicitly accepted as legacy.
- A removal change can update this skill and references as a deliberate breaking change.

## Static Evidence Mode

Use static evidence mode when HTTP status, redirects, headers, and a redacted text preview are enough. Static mode is appropriate for health
checks, public preview availability, simple content checks, and status-page evidence.

Run static mode through `web-evidence capture`. If the static capture is part of a QA acceptance claim, also record it with
`browser-session`.

```bash
run_dir="$(agent-out project --topic browser-qa --mkdir)"
web-evidence capture <url> --out "$run_dir/web-evidence" --label <scenario> --format json

browser-session init \
  --out "$run_dir/browser-session" \
  --target <url> \
  --goal <goal> \
  --browser static-web-evidence \
  --format json

browser-session record-step \
  --out "$run_dir/browser-session" \
  --action "Captured static HTTP evidence with web-evidence" \
  --expectation <expected-behavior> \
  --status pass \
  --artifact "$run_dir/web-evidence/summary.json" \
  --artifact "$run_dir/web-evidence/headers.redacted.json" \
  --artifact "$run_dir/web-evidence/body-preview.redacted.txt" \
  --format json

browser-session verify --out "$run_dir/browser-session" --format json
```

If `web-evidence capture` exits non-zero but writes a bundle, inspect the redacted `summary.json`, record a failed `browser-session`
step if a session was initialized, and report the HTTP/network failure as evidence rather than retrying blindly.

## Active Browser Compatibility

For active browser work, switch to `browser-qa`. Static evidence is insufficient for JavaScript-rendered UI, screenshots or layout,
responsive behavior, DOM interaction, client-side routing, console errors, local storage/session storage, browser-only authentication,
downloads, forms, viewport checks, or console/network summaries.

Active browser work should use the `browser-qa` workflow to choose the driver deliberately:

- `Browser`: local targets, unauthenticated pages, quick interactive open/inspect/screenshot work, and localhost QA.
- `Chrome`: existing cookies, logged-in state, extensions, existing tabs, or another stateful/authenticated browser session.
  Do not export cookies or profile state.
- `Playwright`: repeatable CLI-driven browser paths when the target does not require the user's existing Chrome state.
- `agent-browser`: legacy fallback when `snapshot -i` / `@ref` behavior is needed or native tooling is unavailable.

## Redaction Guardrails

- Keep only redacted evidence artifacts. Do not retain raw cookies, credentials, auth headers, bearer tokens, session storage, local storage
  dumps, secret query parameters, secret form values, or unredacted network logs.
- For screenshots that reveal secrets or personal data, either avoid retaining the screenshot, capture a safer viewport/state, or create a
  redacted derivative before recording the artifact path.
- Summarize console and network evidence to the minimum useful facts. Preserve URLs only after removing secret query parameters and
  fragments.
- Do not type, reveal, or persist passwords, one-time codes, recovery codes, API keys, or customer data in evidence notes.
- Do not commit run directories unless the project explicitly defines a retained, redacted evidence path.

## Blocked States

Stop and report blocked when:

- The requested proof requires login state but Chrome is unavailable or the user has not approved using an existing authenticated browser
  session.
- MFA, CAPTCHA, payment, destructive action, or access-control bypass is required.
- The only available evidence would expose secrets and no redacted artifact can support the claim.
- Browser, Chrome, Playwright, `agent-browser`, `web-evidence`, or `browser-session` is unavailable and no scoped fallback exists.
- Static mode was requested but the requirement depends on active browser behavior.

When blocked after a session has started, record the blocked step as `fail`, run `browser-session verify`, and include the failed
verification result in the final report.
