Author Playwright Suites Spec-First in an Agentic IDE

Tier: Core · Workflow area: Automation engineering

This playbook establishes the professional workflow for generating end-to-end tests with Claude Code, Cursor, or Copilot: conventions loaded as persistent rules, a reviewed spec before any code, generation in small increments, and an assertion-strength review before merge. It is the manual-authoring counterpart to the fully agentic planner/generator loop in pb-15.

When to use

• Adding e2e coverage to a feature in a repo that already has Playwright installed and at least loose conventions.
• Repetitive suite expansionfifteen variants of a flow where the agent's speed compounds and your conventions keep output uniform.
• Team standardizationyou want every AI-assisted test, whoever prompts it, to come out in house style.

When NOT to use:

• No conventions exist yet. Write two or three exemplary specs by hand first — the agent amplifies whatever exists, including chaos.
• Exploring what to test. That is charter work (pb-07) or planner work (pb-15); this playbook assumes you already know the behaviors to cover.

Prerequisites

• An agentic coding tool with run permissionClaude Code, Cursor, or Copilot agent mode, allowed to execute npx playwright test in the loop.
• Playwright installed and greenat least one existing passing spec the agent can read as a style exemplar.
• Fixtures that already work (pb-12) — spec-first authoring on a broken harness generates workarounds, not tests.
• Agreed conventionseven a rough list; step 1 turns it into the rules file.

The recipe

1. 1.

   Write the rules file once. In the repo root, CLAUDE.md (Claude Code) or .cursor/rules/playwright.mdc (Cursor):

   Copy

   ## Playwright conventions
   - Locators: getByRole/getByLabel/getByTestId only. Never CSS or XPath.
   - No page.waitForTimeout. Rely on web-first assertions and auto-waiting.
   - Use fixtures from tests/fixtures.ts for auth and seeded data — never
     inline login steps in a spec.
   - One user-visible behavior per test; name as "does X when Y".
   - Assert outcomes users can see (URL, text, ARIA state), not network
     internals, unless the spec says otherwise.
   - New helpers go in tests/support/, exported and typed.
   

2. 2.

   Write the spec before the prompt. Five minutes in a scratch file — behaviors, data, and edge cases you decided on (pb-01 and pb-05 feed this):

   Copy

   Feature: coupon redemption at checkout
   1. Valid coupon reduces total and shows applied badge.
   2. Expired coupon → inline error "This code has expired", total unchanged.
   3. Coupon + already-discounted item → no stacking; explains why.
   4. Removing coupon restores original total.
   Data: use seedCart fixture; coupons in tests/data/coupons.json.
   

3. 3.

   Prompt for one spec file, referencing both artifacts:

   Copy

   Read tests/fixtures.ts and tests/checkout/cart.spec.ts for style.
   Implement tests for the spec in scratch/coupon-spec.md as
   tests/checkout/coupon.spec.ts. Follow the conventions file strictly.
   After writing, run only this file and iterate until green:
   npx playwright test tests/checkout/coupon.spec.ts
   Do not modify fixtures or other specs without asking.
   

   The agent runs the suite, reads failures, and fixes its own selector typos — that loop is the productivity core. Your job resumes when it reports green.

4. 4.

   Review for assertion strength, not style. Style is the rules file's job; your review targets what the agent gets wrong invisibly:

   Copy

   npx playwright test tests/checkout/coupon.spec.ts --repeat-each=3
   grep -n "waitForTimeout\|toBeVisible()" tests/checkout/coupon.spec.ts
   

   Read every expect: does the expired-coupon test assert the total stayed unchanged, or only that the error appeared? Agents systematically write the assertion that detects success and omit the one that detects damage. A strong generated test looks like:

   Copy

   test('does not stack coupon on discounted items', async ({ seededCart }) => {
     await seededCart.addItem('sale-hoodie');
     await seededCart.applyCoupon('SAVE20');
     await expect(seededCart.page.getByRole('alert'))
       .toHaveText(/can't be combined with sale items/);
     await expect(seededCart.total()).toHaveText('€39.99'); // unchanged
   });
   

5. 5.

   Gate the merge like any code. PR review applies the pb-13 rubric; CI runs the file with retries off so latent flake surfaces now, on the branch, not next Tuesday on main.

Make it yours

• Copilot in VS Codeconventions live in .github/copilot-instructions.md; use agent mode for the write-run-fix loop, and paste the spec into the chat since Copilot won't reliably read scratch files unprompted.
• Cypress shopsidentical shape: rules file bans cy.wait(ms) and mandates data-cy selectors; the agent runs npx cypress run --spec in the loop.
• Page-object housesadd "extend the existing page object; never inline locators in specs" to the rules and point the agent at the PO directory first; review that it extended rather than forked the object.

Quality check

• Conventions held without promptingthe generated file passes your own grep gates (no timeouts, approved locators only) purely off the rules file; if not, strengthen the rules file, don't just fix the file.
• Every negative case asserts the non-eventtotals unchanged, no charge created, state not mutated — alongside the visible error.
• 3x repeat run is green--repeat-each=3 before merge; agent-authored waits are the top flake source (pb-19's taxonomy).
• Failure messages are diagnosticdeliberately break the app state once and read the failure; a good test fails with a story, not a timeout.
• Fixtures were reused, not reinventedzero inline logins or ad-hoc seeding in the new spec; harness drift is how suites become unmaintainable (pb-12).
• You can explain every linethe merge standard for generated code is identical to hand-written: nothing lands you couldn't defend in review.