browser-qa

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.