Skip to content

The Four-Phase Pattern

When to Use

Use this pattern for every AI test generation cycle. It is the spine — not a shortcut for large tests.

The Four Phases

1. Plan — Planner agent explores the app (via Playwright MCP) and writes a Markdown test plan covering scenarios, steps, expected results, negative assertions, and scope. Output: specs/<feature>.md.

2. Review (human) — A reviewer (developer, PM, QA, designer) reads the plan. Approves, rejects, or edits. The plan is the source of truth. Output: approved/edited specs/<feature>.md.

3. Generate — Generator agent reads the approved plan and writes Playwright code. Each scenario in the plan maps to a test(); each step maps to a // step: comment + Playwright call; each acceptance criterion maps to an expect(). Output: tests/<feature>.spec.ts.

4. Heal — When CI breaks because the UI changed, the Healer agent reads the failing test, opens the site, finds new locators, patches the test. The plan stays unchanged — only the code that fulfills the plan drifts. Output: updated tests/<feature>.spec.ts.

Decision

Skip phase When
Plan Never — even a one-paragraph plan is better than no plan
Review Never — without review, the loop has no spec
Generate Sometimes — for very small additions, hand-write the test from the plan
Heal Sometimes — for major UI rewrites, regenerate from the plan instead

Pattern

Artifacts in version control:

specs/                          # plans — human source of truth
├── contact-form.md
├── search.md
└── user-registration.md

tests/                          # generated code — regenerable from specs/
├── contact-form.spec.ts
├── search.spec.ts
├── user-registration.spec.ts
└── seed.spec.ts                # state bootstrap — handwritten

fixtures/                       # data fixtures referenced by plans + tests
├── users.ts
└── content.ts

Both specs/ and tests/ go to git. The spec is reviewable in PRs; the test is executable. The Healer modifies tests; humans modify specs.

This is the general rule specialized for a generated E2E suite: the party that repairs a suite may not change what it asserts. See Changing Existing Tests for the role-and-phase form that applies outside Playwright.

Why Split Into Four Phases

Phase What it protects against
Plan Auto-generated tests no human ever reviewed at the intent level
Review AI-encoded misinterpretations of what "correct" means
Generate Plan-format chaos — Generator only works against plans that follow a schema
Heal Tests that need rewriting on every UI tweak

Common Mistakes

  • Wrong: Letting the Healer auto-commit → Right: every locator change should be human-approved or the suite drifts away from the plan
  • Wrong: Editing tests, not the plan, when intent changes → Right: the plan is source of truth; next regeneration overwrites edits made to generated code
  • Wrong: No plan stage at all → Right: the most common adoption failure — you lose the only artifact non-developers can review

See Also