/playwright-driver

name: playwright-driver
user-invocable: false
tags: [test, driver, web, playwright]
model: haiku
model-preference: sonnet
model-preference-codex: gpt-5.4-mini
model-preference-cursor: claude-sonnet-4-6
description: >
  Use this skill when executing web tests via the canonical `playwright` npm package
  (Microsoft, Apache-2.0). Dispatched by `skills/test-runner/` to execute
  web tests against a target, captures token-frugal AX-tree snapshots +
  screenshots + console output under `.orchestrator/metrics/test-runs/<run-id>/`,
  and exits with deterministic JSON output the orchestrator can parse.

Playwright Driver Skill

Soul

Before anything else, read and internalize `soul.md` in this skill directory. It defines WHO you are — a thin executor, not an orchestrator. Every action in this session should reflect that identity.

Phase 0: Bootstrap Gate

Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If GATE_CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion. If GATE_OPEN, continue.

<HARD-GATE> This driver wraps `playwright` (Apache-2.0, Microsoft). It does NOT use `@playwright/mcp` for browser drive — MCP is ~4× more expensive in tokens per test (Microsoft's own benchmark: ~114K tokens MCP vs ~27K CLI). The R5 grep-canary in `scripts/lib/validate/check-playwright-mcp-canary.mjs` enforces this: any reference to `@playwright/mcp` or `playwright-mcp` under `skills/playwright-driver/**` or `scripts/lib/test-runner/**` fails validate-plugin. </HARD-GATE>

Package Note — PRD Correction (Read This First)

**The PRD originally referenced `@playwright/cli` — that wording is WRONG. Do not use it.**

| Package | Version (2026-05-14) | Status | |---|---|---| | `playwright` | 1.60.0 | **Canonical — use this** | | `@playwright/test` | 1.60.0 | Test framework (same release train) | | `@playwright/cli` | 0.1.13 | Unrelated, unstable — DO NOT USE | | `@playwright/mcp` | 0.0.75 | MCP adapter — R5 hard-gate blocks this |

Verified via `npm view playwright version` → `1.60.0` (2026-05-14 probe). The binary the orchestrator dispatches is named `playwright` (not `playwright-cli`), and it is deliberately the TARGET repo's own `@playwright/test` dependency — the driver never relies on a globally installed binary, so `scripts/lib/playwright-driver/runner.mjs` aborts with exit 2 when the target cannot resolve Playwright locally rather than letting `npx` download it mid-run. Use `playwright@^1.60.0` for compatible-minor updates or pin to `playwright@1.60.0` for reproducibility.

Install

Install into the TARGET repo — that is the only install this driver uses, in CI and locally alike:

npm install --save-dev @playwright/test@1.60.0
npx playwright install chromium    # download browser binaries

Both commands run in the target repo, so `npx` resolves the local binary. A global install is neither used nor sufficient: the driver's preflight requires `@playwright/test` (or `playwright`) under the target's own `node_modules`.

Canonical Usage

The orchestrator (`skills/test-runner/`) dispatches this driver via Bash. Session naming follows the artifact-paths contract:

RUN_ID="${pid}-${ms_timestamp}"      # from scripts/lib/test-runner/artifact-paths.mjs:makeRunId()
RUN_DIR=".orchestrator/metrics/test-runs/${RUN_ID}"

# Output paths via env vars (Playwright canonical):
#   PLAYWRIGHT_HTML_OUTPUT_DIR=${RUN_DIR}/report
#   PLAYWRIGHT_JSON_OUTPUT_FILE=${RUN_DIR}/results.json
#   PLAYWRIGHT_HTML_OPEN=never
PLAYWRIGHT_HTML_OUTPUT_DIR="${RUN_DIR}/report" \
PLAYWRIGHT_JSON_OUTPUT_FILE="${RUN_DIR}/results.json" \
PLAYWRIGHT_HTML_OPEN=never \
playwright test \
  --output "${RUN_DIR}/test-results" \
  --reporter html,json \
  --trace on \
  --project chromium

> Canonical: see https://playwright.dev/docs/test-reporters — reporter names are comma-separated; paths flow via env vars. See `scripts/lib/playwright-driver/runner.mjs` for the canonical invocation.

The orchestrator provides `RUN_ID` and `RUN_DIR` via environment variables, plus the resolved navigation URL `TARGET_URL` and expected pages for the selected scope in driver context. The driver executes Playwright and ensures the per-page capture contract below before handing artifacts to the evaluator. `--target` still names the target repository; it is not the navigation URL.

Artifact Layout

All artifacts land under `${RUN_DIR}/`. Structure:

.orchestrator/metrics/test-runs/<run-id>/
  results.json          # Playwright JSON reporter output — orchestrator parses this
  report/
    index.html          # HTML report (served via `playwright show-report ${RUN_DIR}/report`)
  test-results/
    <test-name>/
      trace.zip         # Playwright trace bundle (open via `playwright show-trace`)
  screenshots/          # pre-created by runner.mjs; content written by test fixtures
    <page-slug>-w1440.png   # desktop screenshot
    <page-slug>-w390.png    # mobile screenshot; additional per-step captures may coexist
  ax-snapshots/         # pre-created by runner.mjs; content written by test fixtures
    <page-slug>-w1440.yaml  # desktop aria snapshot
    <page-slug>-w390.yaml   # mobile aria snapshot
    axe-<route-slug>-<timestamp>.json  # axe-core JSON output (written by test fixture using @axe-core/playwright, NOT by driver)
  console.log           # NDJSON console output (written by test fixture via page.on('console', ...), NOT by driver)

**Division of responsibility:**

• **runner.mjs (driver):** spawns `playwright test`, sets reporter env vars (`PLAYWRIGHT_HTML_OUTPUT_DIR`, `PLAYWRIGHT_JSON_OUTPUT_FILE`, `PLAYWRIGHT_HTML_OPEN`), pre-creates `ax-snapshots/` and `screenshots/` directories before spawn so test fixtures can write into them without racing, captures the process exit code, and routes reporter output to `results.json` / `report/`.
• **Driver skill:** arrange capture for every expected page at widths **1440 and 390**, using the recipe below in the target-local Playwright harness.