Your First Test

A walkthrough from fresh plugin install to a passing BDD test, using the Show-Buff demo app as the target.

Prerequisites

• Node.js ≥ 20
• Claude Code CLI installed: npm install -g @anthropic/claude-code
• ANTHROPIC_API_KEY set in your shell environment
• Dev server running (or use the Show-Buff hosted URL)
• Specwright plugin initialised in your project (npx @specwright/plugin init)

Step 1 — Edit e2e-tests/instructions.js

Open e2e-tests/instructions.js and replace its contents with the following minimal module config targeting the Show-Buff Lists page:

export default [
  {
    moduleName: '@ListsPage',
    category: '@Modules',
    subModuleName: [],
    fileName: 'lists',
    pageURL: 'https://specwright-show-buff.vercel.app/lists',
    instructions: [
      'Verify the Lists page shows a "Create List" button',
      'Clicking "Create List" opens a form with a name input field',
      'Submitting an empty name shows a validation error',
    ],
    explore: true,
    runExploredCases: false,
    runGeneratedCases: false,
  },
];

Step 2 — Open the project in Claude Code

From your project root:

claude .

Step 3 — Run /e2e-automate

Type the following in the Claude Code prompt and press Enter:

/e2e-automate

The 10-phase pipeline starts. Phases 1–3 are near-instant (config parsing and input processing). Phase 4 is where the real work begins.

Phase 4 — Browser exploration

A real browser opens and the planner agent navigates to pageURL. By default the browser runs headless (no visible window). To watch it in real time, add this to e2e-tests/.env.testing:

HEADLESS=false

During Phase 4 the agent:

1. Authenticates (if AUTH_STRATEGY is set)
2. Navigates to the Lists page
3. Takes an accessibility tree snapshot
4. Clicks through interactive elements, discovering selectors
5. Writes e2e-tests/playwright/generated/seed.spec.js
6. Writes e2e-tests/plans/lists-plan.md

This takes 1–3 minutes depending on page complexity.

Phase 6 — Human approval gate

The pipeline always pauses here. The full test plan is printed to the Claude Code prompt — scenario names, selectors, data table shapes.

• Review the scenario names and check selectors look correct.
• Type approve (or yes / proceed) to continue.
• To reject, explain what to change (e.g. "rename scenario 2 to 'Empty name shows inline error'"). The agent will revise and re-present.

Phase 7 — Generated files

After approval, two agents run sequentially:

1. @bdd-generator writes the Gherkin feature file
2. @code-generator writes the Playwright step definitions

Output files land at deterministic paths:

e2e-tests/features/playwright-bdd/@Modules/@ListsPage/lists.feature
e2e-tests/features/playwright-bdd/@Modules/@ListsPage/steps.js

Running the tests

npx bddgen && npx playwright test --project setup --project main-e2e --grep "@ListsPage"

# or with the pnpm shorthand:
pnpm test:bdd --grep "@ListsPage"

Viewing results

pnpm report:playwright

This opens the Playwright HTML report in your browser with screenshots, traces, and step-level timings.

Tip: Set runGeneratedCases: true in instructions.js to have the pipeline run tests automatically in Phase 8. The healer agent will attempt to fix any failures before the final review.