Menu
QA skill for browser-based UI validation and functional test plan execution. Handles authentication and routes to the appropriate reference based on the task.
| name | quality-assurance |
| description | QA skill for browser-based UI validation and functional test plan execution. Handles authentication and routes to the appropriate reference based on the task. |
All paths are relative to the skill's base directory provided when you load the skill.
You must read and follow the reference guide that matches your QA type before doing any work. This is mandatory and must not be skipped — it defines exactly how validation is expected to be performed.
The caller may pass the feature spec for context. Treat it as background only — the presence of Figma references inside the spec does not mean you should run UI validation, and the presence of a test plan does not mean you should run scenarios.
This skill runs headless by default. For auth requirements and full transport selection, see Authentication below. Use bridge only when the task explicitly requires it (i.e., Google SSO or any flow where the browser must carry the user's identity).
When running bridged to the user's Chrome (see Authentication), snapshot the entry page before any interaction and confirm:
If they don't match — or if no user is signed in and the task names a specific account — stop and ask rather than improvising a manual login. The connected Chrome profile is the source of truth for session state.
Default transport: headless Playwright MCP. Drive the browser headlessly unless the task explicitly requires bridge. "Headless" means no painted window — not blind one-shot scripting. The agent retains full interactive control: navigate, click, fill, hover, focus, drive to error states, improvise when an element is not where expected. Deterministic measurement (resize, screenshot, pull computed styles, run pixelmatch) can be scripted via run_code; interactive state exploration uses Playwright MCP's in-the-loop steering. Both run headless.
Bridge transport is a single-purpose escape hatch. Use it only when the browser must carry the user's existing third-party session — practically, Google SSO flows. For every other auth scenario, headless is sufficient.
Transport selection by auth dependency:
| Scenario | Transport |
|---|---|
| No auth required | Headless MCP |
| Email / password credentials | Headless MCP — agent types them |
| OTP, disposable email accepted | Headless MCP + maildrop (<username>@maildrop.cc) |
| OTP, real email required (product blocks disposable email, not Google SSO) | Headless MCP — read OTP via Gmail MCP |
| Google SSO, or any flow where the browser must carry an authenticated third-party session | Bridge only |
Reading an OTP from real Gmail does not require the bridge — the OTP arrives through the Gmail MCP tool channel, not the browser session. The bridge is required only when the browser itself must carry the user's identity.
Credentials in the prompt are informational, not an instruction to log in. In headless mode the agent types them. In bridge mode the connected profile may already hold the session — run the pre-flight check first; if not signed in as that user, ask before logging in manually.
Seed state in the same channel you'll test in. If the test runs in the browser, create preconditions through the browser UI. Do not authenticate via curl and expect that session to carry into the connected browser — they are separate sessions, and data created via curl will appear missing from the browser's perspective.
If the specific browser auth flow has not been specified and is needed, ask before proceeding:
Google SSO (bridge only) — click the "Sign in with Google" button and let the connected Chrome handle it using the existing Google session. Do not enter credentials manually.
Gmail OTP (headless) — trigger the OTP from the app, then use Gmail MCP (gmail_search_messages, gmail_read_message) to find and read the OTP email. Paste it into the browser and continue.
Maildrop OTP (headless) — use <username>@maildrop.cc as the email in the app, then navigate to maildrop.cc/<username> in the browser to read the OTP. Paste and continue.
For API-only scenarios, authentication is handled via curl before making requests. If the auth method has not been specified, ask before proceeding:
Bearer token — obtain a token via the login endpoint, then pass it as a header on subsequent requests:
TOKEN=$(curl -s -X POST "https://api.example.com/auth/login" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "password"}' \
| jq -r '.token')
curl -s -X GET "https://api.example.com/endpoint" \
-H "Authorization: Bearer $TOKEN"
Cookie-based — the server sets a session cookie via a Set-Cookie response header after login. Use -c to capture it and -b to send it on subsequent requests:
# Log in — curl saves Set-Cookie headers automatically
curl -s -X POST "https://api.example.com/auth/login" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "password"}' \
-c /tmp/cookies.txt
# Inspect headers if needed
curl -s -X POST "https://api.example.com/auth/login" \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "password"}' \
-c /tmp/cookies.txt -D -
# Use the cookie in subsequent requests
curl -s -X GET "https://api.example.com/endpoint" \
-b /tmp/cookies.txt
When launching Playwright bridged to the user's Chrome, you may see a "Playwright Extension started debugging this browser" page showing "unknown" connected. This is normal — the connection is established. The browser is in a group, and one of the tabs contains the page the agent navigated to. Do not refresh or relaunch; proceed with the task.
e18) — these are fine for reading page structure, but do not act on them directly: positional refs go stale when the page re-renders (validation, hydration, controlled inputs), causing "ref no longer exists / invalid" failures. When filling, clicking, or selecting, resolve the element by accessible role and name at action time — getByRole('textbox', { name: 'Email' }).fill(...), getByRole('combobox', { name: 'Gender' }).click() — so the locator re-resolves against the live DOM rather than a snapshot that may have moved. This also handles custom components naturally: if a primitive fails (e.g. selectOption on a Radix/shadcn select that isn't a native <select>), fall back to opening it via a role+name click and selecting the option by role+name. Reserve positional refs for the rare case where no stable role/name exists.browser_tabs new / newPage is not supported when Playwright is bridged to the user's Chrome. Reuse the active tab and navigate to change page.Prefer using the fill method over typing character by character unless the input form doesn't propagate the fill as expected. Use type or press only when fill fails to trigger the expected behavior. As a fallback, use run code to execute JavaScript that sets the value directly on the input element.
Re-snapshot between fallbacks. A previous fill or type attempt may have shifted focus or changed the DOM, invalidating any refs you were about to reuse.
React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.
Reviews code changes for correctness, quality, security, and rule compliance. Works on local files or a GitHub PR. Produces a structured report with severity levels and a pass/fail verdict.
Generates a technical specification document for a new feature or product.
Implements a feature based on a provided technical specification, ensuring build stability and strict adherence to the spec through a sub-agent code review. Creates a feature branch, commits changes, and raises a PR on completion.
Sets up a Git worktree for a task or feature. Derives a branch name from the task description, creates an isolated worktree directory, copies env files, and installs dependencies. Use when starting work on a new feature or task in isolation.
Autonomously plans, specs, implements, and raises a PR for a task — without requiring the human to be present for the planning phase. Use this skill when the user hands off a task and asks you to handle it end-to-end, or when phrases like "auto-implement", "handle this autonomously", "fire and forget", or "work on this without me" appear. Also use when the user provides a task description and signals they want to review the output rather than participate in the planning.