Playwright Test Agents: Planner, Generator, Healer and Quality Gates
A practical guide to Playwright test agents, with a small pilot, review gates and checks that generated or repaired tests still detect defects.
On this page
What are Playwright test agents?
Playwright provides three test agents: a planner that explores an application and writes a plan, a generator that turns a plan into tests, and a healer that investigates failing tests. The official documentation describes their workflow and supported coding-agent integrations. Checked on 22 October 2026.
The planner can use a seed test to inherit fixtures and setup. The generator checks interactions against the running application. The healer reruns failures and proposes repairs; its documented outcomes can include a skipped test when it considers the feature broken. A successful agent session therefore needs a separate review of test outcomes.
Start with a small pilot
Our recommendation is to begin with one business journey in a disposable staging environment. Choose a flow whose expected result a reviewer can describe without reading the generated code: for example, adding an item to a basket and confirming that its quantity and total update correctly.
Before asking an agent to explore, record:
- The starting account, permissions and test data.
- The intended user action and observable result.
- Two ways the feature could be wrong while the page still loads.
- The environments and actions the agent may use.
Use synthetic accounts and keep destructive or paid operations outside the pilot. Give the agent a stable starting point and keep credentials outside prompts and committed test files.
Playwright documents initialization for supported agent loops, including:
npx playwright init-agents --loop=codex
Run setup inside an existing project with a deliberately selected Playwright version, then inspect the generated changes. Follow the official setup instructions for your integration; regenerate agent definitions after upgrading Playwright.
Review each handoff
The following review gates are our editorial recommendations for a team pilot.
| Handoff | Evidence to inspect | Reason to pause |
|---|---|---|
| Planner to generator | Preconditions, steps and expected results for the chosen journey | The plan only lists pages to visit or buttons to click |
| Generator to test suite | Assertions that distinguish success from a plausible wrong result | The test finishes after navigation without checking the business outcome |
| Healer to reviewer | Original failure, patch, rerun and a comparison of assertion meaning | The patch deletes the assertion, skips the case or accepts the broken behavior |
| Pilot to CI | Results on the intended build with isolated data and reproducible setup | The test depends on a previous test or an unexplained local state |
A reviewer should be able to explain which defect each assertion would catch. If an assertion only checks that a heading exists, it cannot establish that a basket total is correct.
Check whether a repair preserves intent
Keep the original expected result beside the proposed patch. A locator update can be appropriate after a deliberate interface change, but the resulting assertion still needs to check the same requirement.
For the basket example, compare these outcomes:
- A renamed button requires a new accessible-name locator; quantity and total checks remain.
- A changed tax rule requires an approved expected-value update tied to the new requirement.
- A wrong total causes the test to fail; replacing the total check with a page-title check loses the relevant protection.
Treat skipped, quarantined and disabled cases as unresolved coverage in the pilot report. Give each an owner and a reason. Do not include them in the count of scenarios demonstrated to pass.
Prove that the test can fail for the right reason
On a disposable branch or controlled staging build, introduce a small known defect matching the agreed requirement. For example, make the quantity update leave the displayed total unchanged. Run the generated test and inspect the assertion that fails. Restore the feature and rerun the same test.
Keep the two results with the test revision and build identifiers. If both builds pass, strengthen the assertions before expanding the pilot. If both fail, investigate setup or the test's assumptions. A controlled defect check is useful evidence for that scenario; it does not establish complete application coverage.
Measure the useful work
Track a small set of outcomes over several changes: scenarios reviewed, known defects caught, unexplained failures, skipped cases, repair proposals rejected for weakened assertions, and reviewer time. Record the agent, Playwright version and relevant configuration so comparisons have context.
Decide whether to expand based on this evidence. More generated files and a higher pass count alone do not establish that the suite protects more business behavior.
Sources and scope
The agent roles, setup command and healer outcome caveat come from Playwright Test Agents. For the underlying test design, see Writing tests, including test isolation and web-first assertions. The pilot, review gates and controlled-defect exercise above are our editorial recommendations, rather than claims that a particular application or generated suite has been validated.