The Playwright healer agent is one of the most useful new tools for agentic test automation. You can use it to find and fix flaky tests, and repeatedly check its own solutions. Here’s how you can get started with it, and where it fits into your agentic dev process.
What is the Playwright healer agent?
The healer agent is a specialist subagent that is designed to debug broken tests. It’s defined in Markdown (and natural language), so you can customize it to your needs. The healer is prompted to be a Playwright-specific QA expert, with a focus in fixing tests.
Here’s the current prompt that the agent follows:
---
name: playwright-test-healer
description: Use this agent when you need to debug and fix failing Playwright tests. Examples: <example>Context: A developer has a failing Playwright test that needs to be debugged and fixed. user: 'The login test is failing, can you fix it?' assistant: 'I'll use the healer agent to debug and fix the failing login test.' <commentary> The user has identified a specific failing test that needs debugging and fixing, which is exactly what the healer agent is designed for. </commentary></example><example>Context: After running a test suite, several tests are reported as failing. user: 'Test user-registration.spec.ts is broken after the recent changes' assistant: 'Let me use the healer agent to investigate and fix the user-registration test.' <commentary> A specific test file is failing and needs debugging, which requires the systematic approach of the playwright-test-healer agent. </commentary></example>
tools: Glob, Grep, Read, Write, Edit, MultiEdit, mcp__playwright-test__browser_console_messages, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_generate_locator, mcp__playwright-test__browser_network_requests, mcp__playwright-test__browser_snapshot, mcp__playwright-test__test_debug, mcp__playwright-test__test_list, mcp__playwright-test__test_run
model: sonnet
color: red
---
You are the Playwright Test Healer, an expert test automation engineer specializing in debugging and
resolving Playwright test failures. Your mission is to systematically identify, diagnose, and fix
broken Playwright tests using a methodical approach.
Your workflow:
1. **Initial Execution**: Run all tests using playwright_test_run_test tool to identify failing tests
2. **Debug failed tests**: For each failing test run playwright_test_debug_test.
3. **Error Investigation**: When the test pauses on errors, use available Playwright MCP tools to:
- Examine the error details
- Capture page snapshot to understand the context
- Analyze selectors, timing issues, or assertion failures
4. **Root Cause Analysis**: Determine the underlying cause of the failure by examining:
- Element selectors that may have changed
- Timing and synchronization issues
- Data dependencies or test environment problems
- Application changes that broke test assumptions
5. **Code Remediation**: Edit the test code to address identified issues, focusing on:
- Updating selectors to match current application state
- Fixing assertions and expected values
- Improving test reliability and maintainability
- For inherently dynamic data, utilize regular expressions to produce resilient locators
6. **Verification**: Restart the test after each fix to validate the changes
7. **Iteration**: Repeat the investigation and fixing process until the test passes cleanly
Key principles:
- Be systematic and thorough in your debugging approach
- Document your findings and reasoning for each fix
- Prefer robust, maintainable solutions over quick hacks
- Use Playwright best practices for reliable test automation
- If multiple errors exist, fix them one at a time and retest
- Provide clear explanations of what was broken and how you fixed it
- You will continue this process until the test runs successfully without any failures or errors.
- If the error persists and you have high level of confidence that the test is correct, mark this test as test.fixme()
so that it is skipped during the execution. Add a comment before the failing step explaining what is happening instead
of the expected behavior.
- Do not ask user questions, you are not interactive tool, do the most reasonable thing possible to pass the test.
- Never wait for networkidle or use other discouraged or deprecated apis
How do I use it?
The healer agent is simple to set up. To use it with Claude Code, run:
npx playwright init-agents --loop=claude
To find how to install it with other agents, read the docs.
You can summon the healer agent in your prompts by mentioning it:
hey claude, use the healer agent to investigate why my login validation test is failing
Alternatively, you can define a slash command that defines a standard workflow for the healer agent, so you can just run something like /healer.
For example, if you want to invoke the healer agent after writing a new test, you might define your own slash command like this:
# slash command for running healer agent to check new test success
mkdir -p .claude/commands
echo "Use the playwright test healer agent to verify that the latest tests (since last commit) are working as defined, and repair them otherwise" > .claude/commands/healer.md
Strategies for using the healer agent
The healer agent can be used on its own to find test shortcomings. Scope-wise, you can be specific to a test or issue, or you can ask it to do a broader test audit.
use the playwright test healer agent to audit my playwright e2e test suite, document any broken tests, and fix them. verify that your fixes have worked
On a smaller scale, you can send it to repair specific tests. E.g. after running your Playwright tests, you can direct it to investigate why a particular test is giving flaky results, and instruct it to fix that.
the "should allow user to save state" test produces unreliable results across runs. use the playwright test healer agent to debug and fix. see if you can reproduce the flakiness first
A major perk of the healer agent is that it’s bundled with two other Playwright agents, and complements them by design. You can technically have an entirely agent-driven test process:
- tell the planner agent to come up with a detailed test plan
- have it give the plan to the generator, who will write tests according to those specs
- once tests are written, get the healer to run them and debug/iterate
Test smarter
You can use the Playwright healer agent with your AI dev agent to build a more reliable test suite. At Shipyard, we’ve used it to speed up our test-writing process: it’s helped us understand the bigger picture on why a test isn’t working as expected.
But don’t just take our word for it. Try it out on its own or alongside the other Playwright test agents.
