Claude Code in Playwright

Appearance

Exercise 4.1: Using Test Agents - Plan, Generate, Heal ​

Overall ​

Learn how to use the three-agent pattern (Planner, Generator, Healer) with Claude Code to create comprehensive end-to-end tests. You'll see how each specialized agent role focuses on a specific phase of the testing process, resulting in better test quality and maintainability.

Download Exercise Files

📦 Download Exercise 4 Starter Files

Extract the ZIP file to get started with this exercise.

Project Structure ​

4-planner-generator-healer/
├── package.json
├── playwright.config.ts
├── tsconfig.json
└── tests/
    ├── seed.spec.ts
    ├── smartdocs-login.spec.ts
    ├── fixtures/
    │   └── auth.ts
    └── utils/
        ├── dismiss-splash-page.ts
        └── totp.ts

What is seed.spec.ts?

seed.spec.ts is a test that prepares the application with the initial environment before running other tests.

Steps ​

Step 1: Open the Exercise Folder ​

Open the exercise folder in your preferred IDE (VSCode, IntelliJ, or any other):

Step 2: Update Test Credentials ​

Open .env file and update the following values:

bash
LOGIN_URL=https://sso.uat.bgl360.com.au/?app=smartdocs&&appFilter=smartdocs
USERNAME=[YOUR USERNAME FROM WORKSHOP USERS PAGE]
PASSWORD=[YOUR PASSWORD FROM WORKSHOP USERS PAGE]
TOTP_KEY=[YOUR TOTP KEY FROM WORKSHOP USERS PAGE]

Step 3: Add Playwright MCP (if not already installed) ​

Command:

bash
claude mcp add playwright npx -- @playwright/mcp@latest

Step 4: Launch Claude Code ​

Command:

bash
claude

Now verify the MCP connection:

Command to verify MCP:

/mcp

Step 5: Phase 1 - Planning Agent ​

Use the Planner Agent to explore the application and create a comprehensive test plan.

Prompt:

You are Playwright Test Planner Agent.
Explore the Entity Edit screen, by clicking the "pen-to-square" icon in the last column of the entities table.
Create a comprehensive test plan of editing an entity, and save it as a markdown file.
DO NOT generate any test code.

What to Expect:

  • Claude will navigate through the application using the login fixture
  • Browser opens and automatically logs in
  • Claude clicks the edit icon for an entity
  • The edit screen is explored and documented
  • A test plan markdown file is created

What to Observe:

  • Browser Navigation: Automatic login followed by navigation to the entities table
  • UI Exploration: Claude clicks and explores the entity edit interface
  • Screenshot Analysis: Claude captures and analyzes the edit form
  • Documentation Creation: A markdown file (e.g., entity-edit-test-plan.md) is generated
  • Comprehensive Coverage: Test plan includes validation rules, field types, and edge cases

Why This Matters: The Planner Agent focuses solely on understanding and documenting what needs to be tested, without being distracted by implementation details. This creates a clear roadmap for test development.

Step 6: Phase 2 - Generator Agent ​

Use the Generator Agent to transform the test plan into executable test code.

Prompt:

You are Playwright Test Generator Agent.
Create a single integration test that covers editing an entity.
Generate only one end-to-end test case with no detailed breakdown or additional scenarios.
Select a random entity from the first 10 entities in the list to edit.

What to Expect:

  • Claude reads the test plan created in Step 5
  • A new test file is generated with complete test code
  • Test uses the existing login fixture
  • Test includes proper selectors, actions, and assertions

What to Observe:

  • Test File Creation: A new .spec.ts file appears in the tests folder
  • Fixture Integration: Test imports and uses the loggedInPage fixture
  • Proper Structure: Test includes setup, actions, and assertions
  • Best Practices: Code follows Playwright conventions and patterns
  • Single Test Focus: One comprehensive test covering the entity edit flow

Why This Matters: The Generator Agent focuses on creating clean, maintainable test code based on the plan, ensuring consistency and following established patterns.

Step 7: Phase 3 - Healer Agent ​

Use the Healer Agent to run the test and automatically fix any issues.

Prompt:

You are Playwright Test Healer Agent.
Run the generated test case and fix any errors.

What to Expect:

  • Claude runs the test automatically
  • If failures occur, Claude analyzes the errors
  • Test code is updated to fix issues
  • Test runs again until it passes

What to Observe:

  • Automatic Test Execution: Test runs without manual intervention
  • Error Detection: Claude identifies failing assertions or selectors
  • Debugging Process: Claude examines screenshots and error messages
  • Code Fixes: Test code is updated with corrected selectors or timing
  • Verification: Test runs again to confirm fixes work
  • Success: Green checkmark when test passes consistently

Why This Matters: The Healer Agent handles the tedious debugging work, fixing timing issues, updating selectors, and ensuring tests are stable and reliable.

Step 8: Verify in UI Mode ​

Run the final test in UI mode to see it execute successfully:

Run in a New Terminal

Important: Open a new terminal window to run this command. Do NOT run it in your Claude Code conversation, as it will launch an interactive UI that keeps the terminal busy.

Command:

bash
npm run test:ui

What to Observe:

  • Test runs smoothly from start to finish
  • All actions execute correctly (navigation, editing, saving)
  • Assertions pass successfully
  • Test completes without errors

Expected Outcome ​

You should have:

  • A comprehensive test plan document created by the Planner Agent
  • Working test code generated by the Generator Agent
  • A stable, passing test refined by the Healer Agent
  • Understanding of how specialized agent roles improve test quality
  • Confidence in the three-phase approach for complex test scenarios