| name | e2e-testing |
| description | Plans, generates, runs, and heals end-to-end tests using Playwright Test Agents (Planner, Generator, Healer) and the official `@playwright/mcp` server. Drives a spec-first feature-flow loop, proposes `data-testid` source diffs only when accessibility-tree locators fail, and stays token-aware via snapshot mode and `--last-failed` reruns. Use when adding E2E coverage, verifying a user journey, hardening a flaky flow, or wiring Playwright MCP into a repo. Triggers on "test this flow", "add e2e", "verify the user journey", "write e2e test", "feature test", "playwright agents", "/e2e-testing".
|
| disable-model-invocation | false |
| license | MIT |
| metadata | {"author":"mthines","version":"1.0.0","workflow_type":"slash-command","tags":["e2e","playwright","playwright-mcp","test-agents","spec-first","locators","token-economy","browser-automation"]} |
E2E Testing
Drive end-to-end tests through Playwright's MCP-backed Test Agents โ Planner,
Generator, Healer โ released in Playwright 1.56 (Oct 2025).
The user writes (or approves) a Markdown feature spec; agents generate the
test, run it against a real browser via the accessibility tree, and self-heal
when locators drift.
This SKILL.md is a thin index.
Decision rules live in rules/*.md and load on demand.
Worked references (agent reference, MCP tool catalog, pyramid math) live
in references/*.md.
Literal boilerplate the skill emits lives in templates/*.md.
Do not preload everything โ load only what the current phase asks for.
When to use
Reach for this skill when any of the following is true:
- A feature has user-facing flow that integration tests cannot fully cover.
- A bug repros only through real navigation (multi-page, auth, real network).
- A flake needs a Healer pass instead of a manual locator hunt.
- The repo has no
@playwright/mcp wiring yet and needs Phase 0 setup.
Do not reach for this skill when:
- A unit or component test would catch the same bug โ defer to
tdd and the layer rule in
rules/layer-decision.md.
- The change is a pure refactor with no behavioural surface.
- You are adding test infrastructure unrelated to a real flow.
Phase 0 โ Preflight (mandatory gate)
Before any agent loop, verify the repo is wired for Playwright Test Agents.
Halt and ask the user before installing anything.
Run these checks (read-only):
jq '.devDependencies | keys[]' package.json | grep -E '@playwright/(test|mcp)'
ls specs/ tests/seed.spec.ts playwright.config.ts 2>/dev/null
Decision table:
| State | Action |
|---|
| Both deps present + artefacts exist | Proceed to Phase 1. |
| Deps missing | Halt. Print install plan, ask permission before running. |
| Deps present, artefacts missing | Halt. Print npx playwright init-agents --loop=claude, ask first. |
Playwright present but version < 1.56 | Halt. Test Agents require 1.56+. Ask permission to upgrade. |
Print the exact commands; do not run them silently.
The install plan template is in templates/install-plan.md.
Phase 1 โ Spec-first feature flow
The agent loop is spec โ generate โ run โ heal.
The spec is human-readable Markdown, not code.
Full rules: rules/spec-first-flow.md.
specs/<flow>.md โโ
โโโ Generator โโ tests/<flow>.spec.ts โโ run โโ pass?
โ โ no
โ โผ
โโโโโโโโโโโโโโโโโโโโโ Healer โโโโโโโโโโโโโโโ failing test
โ
โผ
patched test or `data-testid` proposal
Two entry points:
- Spec already drafted by the user.
Skip the Planner.
Run the Generator on
specs/<flow>.md.
- App exists, no spec yet.
Run the Planner against the live app to draft
specs/<flow>.md.
User reviews the Markdown plan before generation.
Use the Markdown template in templates/spec.md.
Locator ladder (when generating or healing)
The Generator and the Healer both walk the accessibility tree.
Pick locators in this order โ never skip a rung:
getByRole('button', { name: 'Save' }) โ accessibility-tree native.getByLabel, getByPlaceholder, getByText โ user-facing strings.getByTestId('save-draft') โ escape hatch only.
data-testid is a source change, not a test workaround.
When the Healer cannot find a stable locator at rungs 1โ2, propose a source
diff that adds data-testid to the component, and offer the diff for user
approval before patching the test.
Full rules and decision criteria: rules/locator-strategy.md.
Phase 2 โ Token-aware execution
Playwright MCP defaults to snapshot mode (accessibility tree, text-only).
Do not enable --caps=vision unless an explicit pixel-level concern exists.
Full rules: rules/token-budget.md.
Defaults the skill prescribes:
- Snapshot mode (no vision) for all agent calls.
- Run only the changed spec on iteration:
npx playwright test --last-failed.
- Run the Healer only on failure, not on every save.
- Reuse
storageState from tests/seed.spec.ts to skip auth on every run.
- Cap the heal loop at three attempts per failing test before escalating.
Phase 3 โ Verification
After the Generator produces a test:
- Run the test once against the live app.
It must pass on first run, or the Healer must converge in โค 3 attempts.
- Invoke
test-provenance-guard on
the generated file to ensure the test imports production code instead
of a private re-implementation.
- Open
playwright.config.ts and confirm trace: 'on-first-retry' is set
so a future failure produces a trace bundle.
If the heal loop fails to converge:
- Invoke
confidence(analysis) on the test failure.
- If confidence is below 90%, escalate to the user with the trace, the spec,
and the proposed locator changes โ do not keep healing blindly.
Decision flow at a glance
| Signal | Do |
|---|
| Bug fixable by a unit or component test | Use tdd, not this skill. |
| Multi-page user flow, auth, or real network involved | Spec-first feature flow (Phase 1). |
| Flaky existing test | Healer pass only; do not rewrite without spec context. |
| Locator unstable, no stable role / label | Propose data-testid diff (rule: locator-strategy). |
| Repo missing Playwright or MCP | Phase 0 halt + ask permission. |
| Heal loop > 3 attempts | Stop, run confidence(analysis), escalate. |
| Test passes on first run, never seen failing | Run test-provenance-guard before declaring done. |
Composes with
tdd โ owns the unit and component layers.
This skill defers to it for anything below E2E.test-provenance-guard โ runs after
Generator output to catch tests-by-construction.confidence โ gate when the heal loop fails.holistic-analysis โ if a flow is failing
for reasons no test rewrite can fix, step back instead of patching.playwright-trace-analyzer โ
consume the trace produced by a failed test on retry.
References
Templates
- Writing E2E for logic a unit test catches.
- Running the Healer on every save.
- Patching the test with brittle CSS selectors instead of proposing a
data-testid diff.
- Enabling
--caps=vision without a pixel-level requirement.
- Ignoring Healer suggestions and keeping a
.skip() in CI.
- Generating tests against a stub server, not the real app.
Definition of done
