Playwright Testing

Playwright Testing (live, via MCP)

Live browser testing for the manual-QA team. You drive a real browser through the Playwright MCP server (@playwright/mcp) to explore a web app or execute a test case step-by-step against a running app. You never write or run Playwright test code — no Page Object Model, no pytest, no .spec.ts files. The output is a verdict plus evidence, not a test suite.

Writing actual Playwright test code is test-automation-engineer's job (a different factory's copy of this skill). Here, the browser is your hands.

When to use

• app-profiler — explore a running web app: map key flows, capture reliable selectors and fragile areas into app_profile.md.
• test-runner — execute one web TC-NNN case live: run each step, verify, collect evidence, return a structured result.
• Web / PWA / hybrid only. Native iOS/Android → use the mobile-testing skill. (PWA/hybrid with a mobile viewport is still this skill.)

Core loop — snapshot first

The Playwright MCP exposes browser_* tools. The loop for every check:

1. browser_navigate(url) — go to {{base_url}}/path (substitute base_url from the run prompt). Navigation auto-waits for load.
2. browser_snapshot() — the accessibility snapshot gives each element a target ref plus its role and accessible name. You need the ref before you can act, and role/name is what you assert on.
3. Act by passing that ref as target (plus a short human-readable element description): browser_click, browser_type, browser_fill_form, browser_select_option, browser_press_key, browser_hover.
4. browser_wait_for({text}) / ({textGone}) — wait for the expected text to appear, or a spinner/loader text to disappear, before continuing.
5. browser_snapshot() again, then collect evidence: browser_take_screenshot, browser_console_messages, browser_network_requests.

Refs go stale. Every target ref comes from the latest snapshot — after any navigation or DOM change, re-browser_snapshot before acting again. The server is versioned; this skill is written against the browser_* toolset and parameter names can shift between @playwright/mcp releases.

MCP tool quick reference

target* is the ref from the latest browser_snapshot (a unique CSS selector also works); always pass element too — a short description of what you're acting on.

{{base_url}} rule

All test-case URLs are written {{base_url}}/path. Substitute the real base URL from the run prompt into the browser_navigate(url) call at execution time — this keeps cases environment-agnostic across dev / staging / prod.

Filling a form (one call)

browser_fill_form fills every field in a single call. Each field is {element, target, name, type, value}, where type ∈ textbox | checkbox | radio | combobox | slider (checkbox/radio value is "true"/"false"; combobox value is the option text):

browser_snapshot()                       # get refs first
browser_fill_form(fields=[
  {element:"Email field",    target:"<ref>", name:"Email",    type:"textbox",  value:"qa@example.com"},
  {element:"Password field", target:"<ref>", name:"Password", type:"textbox",  value:"Passw0rd!"},
  {element:"Remember me",    target:"<ref>", name:"Remember", type:"checkbox", value:"true"},
])

For a single field, browser_type(element, target, text, submit:true) types and presses Enter in one step.

Mapping test-case steps to MCP tools

Test cases are written in plain language. Map each step verb to a tool call:

Selecting elements from the snapshot

browser_snapshot returns each interactive element with a target ref and its role + accessible name. Prefer, in order: the snapshot's role + accessible name → data-testid → visible text → a stable selector. Avoid brittle positional CSS (nth-child, deep descendant chains). When a clean ref isn't obvious, a unique CSS selector passed as target is valid. Framework-specific selector hints (MUI, shadcn/ui, Ant Design) and gotchas: references/patterns.md.

Waiting

browser_navigate and the action tools auto-wait for the page/element. For app-side state, use browser_wait_for — never a fixed sleep when a condition works:

Evidence and verification before PASS

• browser_take_screenshot(type:"png", filename:"reports/screenshots/{TC_ID}_{YYYY-MM-DD}.png") — visual proof. (Filenames are relative to the MCP output dir.)
• browser_console_messages(level:"error") — check for silent JS errors even when the UI looks fine; they're the worst bugs. browser_network_requests confirms the API calls actually fired.
• Verify the Expected Final State in a final browser_snapshot before recording PASS. A PASS without a confirming snapshot of the expected state is invalid (apply verification-before-completion).

Failure handling

On a mismatch, apply systematic-debugging:

1. browser_snapshot + browser_take_screenshot — capture evidence first.
2. State actual vs expected ("Login screen still visible; expected Dashboard").
3. Retry once with a better target (different selector strategy).
4. Still failing → record FAIL with a snapshot excerpt in failure_reason.

Result hand-off

When run by test-runner inside a led suite, end the response with the single structured JSON result block the test-run-lead collects (tc_id, result PASS/FAIL/BLOCKED, steps, screenshot, failure_reason, …). The lead and test-reporter consume that block — see the test-runner agent for the exact schema.

Bug report format

When you find an issue (outside a structured run):

## [SEVERITY] Title
Steps: 1. Navigate to… 2. Click… 3. Observe…
Expected: what should happen
Actual: what happens
Evidence: screenshot, console error, network response
Frequency: Always / Intermittent / Once

Reference

references/patterns.md — live interaction recipes (login, forms, dialogs, dropdowns, file upload) as exact browser_* call chains, framework-specific selector hints, and common gotchas.