Playwright now ships first-party agents: a planner that explores your app into a Markdown test plan, a generator that turns the plan into verified specs, and a healer that repairs failures. The loop is powerful precisely because a human edits the artifact between every stage — skip a gate and you ship the agent's misunderstandings at scale.
Tier: Core · Workflow area: Agentic test stack & self-healing
This playbook runs the full three-agent loop on a real feature, with explicit review gates: you edit the plan before generation, review the specs before merge, and audit every heal before it lands.
npx playwright init-agents --loop=vscode (or --loop=claude).Initialize and inspect the agent definitions. init-agents writes planner, generator, and healer instructions plus a seed.spec.ts into your repo. Read them — they are prompts, and you are allowed to edit them to encode team conventions (locator style, fixture use, forbidden patterns).
Run the planner with a scoped charter. Point it at one feature, not the whole app:
Use the planner agent. Explore the checkout flow of http://localhost:3000
starting from a logged-in state (use the storageState in .auth/user.json).
Produce specs/checkout.md covering: guest vs logged-in checkout, address
validation, payment failure handling, and order confirmation.
Do not plan admin, search, or catalog scenarios.
The planner drives a real browser and emits a Markdown plan of scenarios with steps and expected outcomes.
GATE 1 — edit the plan like a test design review. This is the highest-leverage 20 minutes in the loop. Expect both over-scoping (trivial permutations padding the count) and under-scoping (no negative payment path, no empty-cart edge). Delete, merge, add, and correct expected outcomes that the planner guessed from UI text. A sample plan row worth fixing:
### Scenario: Payment declined
Steps: ... submit card 4000-0000-0000-0002
Expected: user sees "Something went wrong" <- wrong: spec says inline
"Card declined" + cart preserved
Commit the edited plan. It is now a reviewed artifact with your name on it.
Run the generator against the edited plan. The generator writes one spec per scenario, executing each step live to verify selectors and assertions as it goes — expect it to iterate until the test actually passes against the running app.
GATE 2 — review the specs before merge. Verified-against-the-app is not verified-correct. Review for assertion strength (does the order-confirmation test assert the order number, or just the "Thank you" header?), locator quality, and fixture use. Then check the suite is deterministic:
npx playwright test --repeat-each=3 --workers=4
Break something, run the healer. When UI churn or a refactor breaks specs, the healer replays the failure, inspects the live app, and proposes patches:
Use the healer agent on the 3 failures in the last run. For each, output the
diff and a one-line justification. Do not commit.
GATE 3 — audit every heal as a proposed change. The healer cannot distinguish "selector drifted" from "feature broke". For each patch ask: did the app's intended behavior change? If yes, the heal is masking a regression — reject it and file the bug. Land accepted heals as commits with the justification in the message (see the healed-test audit queue playbook for the full workflow).
The loop's artifacts — plan, specs, heal diffs — are checkpoints designed for human judgment. An unedited plan generates confidently wrong tests; an unaudited heal converts a real bug into a green run. The agents do the assembly; the gates do the QA.
--loop=claude): same three agents driven from the terminal; strongest when you want the planner to also read requirement docs in the repo for expected outcomes instead of guessing from the UI.specs/feature.md yourself in the same format.The agents drive a real browser against your app and send page snapshots to the model. On client engagements, that means client UI, data, and URLs enter the assistant — get the tool approved first, run against a test environment with synthetic data only, and never point the planner at production. Where policy requires, use a locally-hosted model endpoint for the loop; the artifacts and gates are identical. Disclose agent-generated tests in deliverable documentation where the client's audit standards require it.
Treat the planner's Markdown plan as the durable asset, not the specs. When the app changes significantly, re-edit the plan and regenerate — cheaper than healing twenty stale specs, and the plan review keeps you, not the agent, as the owner of coverage.