Playwright Planner Agent Guide for High-Coverage Markdown Test Plans

The Playwright Planner agent explores a running application from a seed test and writes a human-readable Markdown test plan under specs/. Give it a clear, bounded request, a runnable seed, and optional product requirements; then review the plan before Generator writes code. High coverage comes from explicit risks, user states, branches, data boundaries, and expected outcomes, not from asking Planner to "test everything." Planner can observe the environment it receives, but it cannot prove requirement correctness, exhaustive coverage, safe production access, or that an unobserved state behaves as assumed.

Place this workflow inside the Planner, Generator, and Healer pillar. If definitions are missing, complete the init-agents setup; after plan approval, use the Generator agent guide, and route genuine failures to the Healer agent guide. The canonical test-planning strategy guide supplies broader planning context. Browse the QA skills directory and Playwright CLI skill for reusable testing instructions.

The role contract comes from Playwright's current official Planner documentation. Planner's documented inputs are a clear request, a seed test, and an optional PRD. It runs the seed to execute global setup, project dependencies, fixtures, and hooks, and it uses that seed as an example for generated tests. Its output is a precise Markdown plan, illustrated as specs/basic-operations.md. The risk model and review gates below are recommended planning practice, not undocumented agent features.

Define the planning job before opening a browser

Planner works best when the request establishes a decision boundary. "Plan checkout" leaves the account state, market, payment mode, inventory, data ownership, and stopping point unspecified. "Plan guest checkout for one in-stock item in the local test environment, using the fake payment option and stopping after confirmation" gives exploration a controlled shape.

Write a one-paragraph charter with six fields:

1. Target: the application URL, tenant, and feature area.
2. Actor: guest, member, administrator, or another named role.
3. Starting state: data and authentication created by the seed.
4. In scope: journeys and branches Planner may inspect.
5. Out of scope: destructive, privileged, external, or unrelated areas.
6. Deliverable: exact specs/ path plus assumptions to report.

These fields do not force a particular selector or implementation. They tell Planner what evidence it may collect and give reviewers a way to recognize scope drift. A bounded charter is also a security control: an agent should not discover whether account deletion works by trying it against a shared account.

Build a coverage model from risk, not page count

High coverage does not mean clicking every visible control. It means representing materially different outcomes that matter to the product. A useful plan separates state, action, branch, and evidence.

Coverage dimension	Question for Planner	Example checkout scenario	Common planning defect
User state	Who can perform the action?	Guest with an empty cart	Role remains implicit
Data state	Which data changes the outcome?	In-stock item versus unavailable item	Only happy-path fixture is named
Decision branch	Where can behavior diverge?	Accepted versus rejected coupon	Many inputs repeat one outcome
Boundary	Which threshold is meaningful?	Quantity changes from maximum allowed to rejected	Arbitrary values replace business limits
Recovery	How does the user correct an error?	Invalid address is edited and resubmitted	Plan checks error but not recovery
Persistence	What should survive navigation?	Cart remains after returning from delivery step	Session behavior is assumed
Observable result	What proves success or refusal?	Confirmation heading and stable order reference appear	"Checkout works" is not measurable
Cleanup	What state must be removed?	Disposable order and cart are reset	Parallel reruns collide

Use the table as a review lens, not a demand for eight scenarios per feature. One scenario may cover several dimensions. Conversely, two inputs that produce the same validated behavior may not deserve separate end-to-end cases when a lower-level test can cover the data matrix more cheaply.

Before Planner explores, identify the consequences that justify browser coverage: money movement, permission changes, irreversible publication, cross-tenant access, accessibility-critical controls, legal consent, or workflows whose integration is difficult to prove below the UI. Then ask for representative success, refusal, and recovery paths.

Engineer the seed as a planning fixture

The seed is Planner's executable starting contract. Because the official docs say Planner runs its initialization and uses it as an example, the seed influences both what the agent can observe and the style Generator may later copy. Keep it narrow, deterministic, and visibly tied to the intended environment.

This seed provisions a synthetic cart through a project fixture and verifies the tenant and actor before planning begins:

// tests/seed.spec.ts
import { test, expect } from '../fixtures';

test('seed guest checkout planning state', async ({ page, createGuestCart }) => {
  const cart = await createGuestCart({ sku: 'TEST-SHOE-42', quantity: 1 });

  await page.goto('/checkout?cart=' + cart.id);
  await expect(page.getByRole('heading', { name: 'Guest checkout' })).toBeVisible();
  await expect(page.getByText('QA Sandbox')).toBeVisible();
  await expect(page.getByText('TEST-SHOE-42')).toBeVisible();
});

createGuestCart is an illustrative repository fixture, not built into Playwright. A real project should import its approved fixture layer. The seed deliberately stops before entering an address or placing an order; those actions belong to the flow being planned.

Review the seed against these questions:

• Does it create unique data when tests may run concurrently?
• Does it prove the expected tenant, locale, role, and feature state?
• Does it avoid plaintext secrets and production endpoints?
• Is cleanup owned by a fixture, teardown, or disposable environment?
• Does it expose repository conventions that Generator should preserve?
• Can it run by itself with the normal Playwright Test runner?

If the seed fails, stop planning. Planner cannot turn an unavailable service or broken fixture into trustworthy coverage. A browser that happens to show a login screen is not equivalent to the intended authenticated state.

Write a Planner request that exposes assumptions

The following is a prompt for the coding-agent host, not a Playwright command:

Use the Playwright Planner agent with tests/seed.spec.ts. Explore guest checkout
for the synthetic item already in the cart. Plan the successful fake-payment flow,
required-field validation, a rejected postal code, recovery after correction, and
cart persistence when navigating back from delivery.

Use only the QA Sandbox tenant and the fake payment method. Create at most one
disposable order. Do not open account administration, contact a real payment
provider, or infer behavior that cannot be observed. Save the plan to
specs/guest-checkout.md. For every scenario, record the seed, preconditions,
test data, numbered steps, expected results, cleanup, and any unverified assumption.
Stop after writing the Markdown file for review.

The request names outcomes without prescribing locators. It permits one final submission but blocks real payment and unrelated administration. It also asks Planner to distinguish observation from inference. That distinction improves the artifact: "postal code X displayed an unsupported-region message" is evidence; "all unsupported regions behave the same" is an assumption unless tested or supplied by a requirement.

Avoid prompts that reward volume, such as "generate 100 cases." They encourage superficial permutations. Ask instead for a scenario set that covers specified risks and explain what can be delegated to API, component, or unit tests. Planner's role is to produce a plan, not to maximize a count.

Shape the Markdown as an executable contract

The artifact conventions describe specs as structured, human-readable plans containing scenarios, steps, expected outcomes, and data. A publication-ready internal template should preserve those documented elements and add ownership details needed by the team.

# Guest checkout test plan

## Scope
Guest checkout in QA Sandbox for one synthetic in-stock item and fake payment.

## Assumptions requiring review
- The rejected postal code supplied below is stable test data.
- Order confirmation may create one disposable order.

## Scenario 1: Correct an unsupported postal code
**Seed:** tests/seed.spec.ts
**Preconditions:** Cart contains TEST-SHOE-42; shopper is a guest.
**Data:** Rejected postal code 00000; accepted postal code 10001.

### Steps
1. Enter the otherwise valid delivery address with postal code 00000.
2. Continue to delivery.
3. Replace 00000 with 10001 after the refusal appears.
4. Continue again.

### Expected results
- The first submission stays on the address step.
- An error identifies the postal-code field and explains the region is unsupported.
- Previously valid address fields keep their values.
- After correction, the error clears and the delivery step becomes visible.

### Cleanup
The cart fixture deletes its synthetic cart after the test.

This example gives Generator observable outcomes. It avoids implementation-specific selectors and does not assert an exact error sentence unless exact copy is a requirement. It also says which valid values must persist, preventing a test that only checks for any red message.

Plans should use stable scenario identifiers or descriptive headings. One-to-one alignment with generated tests is preferred where feasible according to the official page. A reviewer should be able to map a test title back to a scenario without searching model logs.

Separate observations, requirements, and recommendations

Planner may receive both a PRD and a running app. Those sources can disagree. A plan should not silently combine them. Record each important statement as one of three classes:

• Observed: Planner performed the action and saw the result in the seeded environment.
• Required: approved product material says the result must occur.
• Assumed: the result was not verified and needs a decision or safer data.

If the PRD says a guest cart expires after thirty days but the planning session cannot wait thirty days, that is a requirement, not an observed browser result. The plan can propose a time-controlled test or lower-level coverage; it should not claim the expiration was explored live.

Similarly, a visible success message does not prove a backend side effect unless the plan has an approved observable for it. A scenario can assert the confirmation UI and, if the repository provides a safe API fixture, verify server state in generated code. Planner should name the required evidence rather than invent how a nonexistent fixture works.

Design expected results that can fail meaningfully

"The page works" and "the user is successful" do not tell Generator what to assert. Strong expected results name the user-visible state, state transition, persisted value, or denied effect.

For each action, ask:

1. What becomes visible, enabled, selected, focused, or navigable?
2. What must remain unchanged?
3. What data is created, updated, or rejected?
4. What proves the user reached the next state?
5. What evidence distinguishes the expected branch from a nearby false positive?

An order scenario should not pass merely because any "Thank you" text exists. It may need a confirmation heading, an order reference, a summary containing the purchased item, and evidence that duplicate submission is unavailable. The exact combination depends on product risk and approved requirements.

Do not overfit to transient presentation. If color or pixel position is not the contract, keep it out of the plan. If accessibility semantics are part of acceptance, say which role, name, focus movement, or announcement is expected. The plan should describe behavior at the level the test is meant to protect.

Reduce combinatorial plans deliberately

A form with five fields and ten invalid values can produce thousands of combinations. Browser coverage should select interactions whose integrated outcome differs. Use pairwise or boundary reasoning as a team method, but do not present it as a hidden Planner algorithm.

A practical reduction sequence is:

1. List business rules and distinct outcomes.
2. Identify one representative input for each outcome.
3. Add boundaries where behavior changes.
4. Cover one recovery path for consequential errors.
5. Move pure validation permutations to a lower layer.
6. Retain end-to-end combinations only when integration creates unique risk.

For example, empty first name and empty city may share the same required-field mechanism. The plan can test the form-level summary plus one field association in the browser while component tests cover every label. A rejected shipping region has a different business outcome and deserves its own end-to-end scenario.

High coverage is defensible selection, not raw scenario quantity. Record what is intentionally omitted and where it should be tested.

Review the plan before generation

Planner's Markdown output is a proposed artifact. Review it with product, QA, and engineering perspectives before Generator consumes it.

Use this acceptance rubric:

• Every scenario names its seed and preconditions.
• Data is synthetic, specific, and safe to create or mutate.
• Steps describe user behavior in a reproducible order.
• Expected results are observable and map to approved intent.
• Material success, refusal, boundary, and recovery paths are represented.
• Duplicate scenarios do not differ only by cosmetic input values.
• Assumptions and unverified branches are visible.
• Cleanup and parallel-isolation needs are identified.
• Privileged or irreversible actions have explicit controls.
• Scenario headings can become clear test titles.

Reject or edit a plan that wanders outside scope, treats observations as requirements, or names selectors copied from a temporary DOM. Planner explores the app to understand flows; Generator is the role that verifies selectors and assertions live while implementing the approved plan.

Failure paths during planning

Planning symptom	What it usually means	Correct response
Seed ends on a login page	Auth state, dependency, or base URL did not initialize	Fix the seed and rerun it normally before planning
Planner cannot reach a branch	Data, role, flag, or environment lacks the state	Supply safe setup or mark the branch unverified
Plan contains invented expected results	Prompt or source material left behavior ambiguous	Separate requirement, observation, and assumption
Dozens of nearly identical cases appear	Request rewarded quantity instead of distinct risk	Collapse by outcome and move permutations down the pyramid
Plan submits destructive actions repeatedly	Scope lacks a mutation budget or disposable resource	Stop exploration and redesign test data boundaries
Steps depend on current element IDs	Artifact captured implementation rather than behavior	Rewrite in user and outcome language
No cleanup is described	State ownership was omitted	Add fixture or teardown responsibility before generation
PRD and app disagree	Requirement or implementation may be wrong	Record the discrepancy and obtain a product decision

When Planner cannot verify a state safely, a truthful gap is the correct output. Do not ask it to fill missing evidence with likely behavior. A reviewer can provide a fixture, approve a mock, change the environment, or decide that another test layer is appropriate.

Hand off a stable plan to Generator

After approval, freeze the relevant plan revision in the same change set as generated tests. Tell Generator the exact specs/ file, and preserve the seed reference. The official Generator example comments both source paths in the test file, which makes future review and healing easier.

If reviewers modify the plan after code generation, decide whether to regenerate or manually update the tests. Do not let intent and implementation drift silently. A material requirement change should alter both artifacts or explicitly retire the obsolete scenario.

A concise handoff prompt can say:

Use the Generator agent to implement the approved plan at
specs/guest-checkout.md. Preserve the fixtures and import style demonstrated by
tests/seed.spec.ts. Generate tests under tests/checkout/. Do not add scenarios
that are absent from the plan. Report any step or expected result that cannot be
verified live, and stop for code review after writing the tests.

This request does not guarantee maintainable output; it constrains the task and surfaces gaps. The next guide supplies the code-review standard.

Version scope and practical limitations

Playwright introduced Planner with the other test agents in version 1.56. This guide follows the stable 1.61-era documentation available July 14, 2026. Regenerate definitions after Playwright updates because the official setup page says new tools and instructions are delivered that way.

The documented Planner contract is intentionally narrow. It does not claim exhaustive state-space coverage, production-safe exploration, formal requirements validation, automatic prioritization, or guaranteed one-to-one generated output. It observes the application state reachable from the seed and writes a plan. Coverage quality still depends on the request, data, environment, source requirements, and review.

The current page documents the Node.js agent setup. Do not assume an identical initializer or artifact contract for other Playwright language bindings without their official documentation. Host-specific orchestration may differ even when all clients expose a Planner role.

Frequently Asked Questions

What input does the Playwright Planner agent require?

The official docs list a clear request and a seed test. A PRD is optional. The seed establishes the environment and demonstrates fixtures, hooks, dependencies, and repository conventions.

Where does Planner save the test plan?

Playwright illustrates a Markdown output such as specs/basic-operations.md. Name the desired file in the request and review that artifact before generation.

Does Planner write Playwright test code?

Planner's documented output is a Markdown plan. Generator is the separate role that transforms the plan into Playwright Test files.

Can Planner guarantee complete test coverage?

No. It can explore reachable flows and propose scenarios, but completeness depends on requirements, state, data, permissions, risks, and review. Ask for explicit dimensions and record omissions.

Why is the seed test so important?

Planner runs it to execute initialization and uses it as an example for later generated tests. A wrong tenant, broad account, or flaky setup corrupts both observation and downstream style.

Should Planner explore production?

The official docs do not instruct teams to use production. Prefer a controlled test environment with synthetic, disposable data. If production observation is ever considered, organizational authorization and strict read-only controls are separate requirements.

How many scenarios should a plan contain?

There is no official target count. Include scenarios that represent materially different risks and outcomes. Remove cosmetic permutations and allocate them to lower test layers when appropriate.

What should I do when Planner cannot verify a branch?

Keep the limitation visible. Add safe data or a fixture, obtain approved requirements, move the check to another layer, or leave the scenario marked unverified. Do not manufacture an expected result.

Can I send the plan directly to Generator?

Technically the roles can run sequentially, but a review gate is the safer team policy. Confirm scope, data, expected outcomes, assumptions, and cleanup before converting the plan into code.

From reviewed intent to executable coverage

Use the Generator agent guide to preserve the plan's intent in maintainable code and the Healer guide when a named test later fails. The init-agents tutorial covers definition lifecycle, while the complete agent pillar explains ownership across all three roles.

The role behavior and artifact shape are defined by the official Playwright Planner page and test-agent conventions. For broader human planning techniques, continue with the test-planning strategy guide. The QA skills catalog and Playwright CLI skill provide reusable context without changing Planner's documented limits.