| name | debug-e2e-test |
| description | Debug and fix failing Playwright E2E tests. Use when tests fail, when asked to fix failing tests, or when investigating test failures. Analyzes test output, screenshots, error context, and uses Playwright MCP to identify root causes. |
Skill: Debug E2E Test
This skill provides a systematic workflow for debugging and fixing failing Playwright E2E tests in the test-app.
When to Use This Skill
Use this skill when:
- A Playwright E2E test is failing
- Asked to fix a failing test
- Investigating why tests are broken
- Tests pass locally but fail in CI
- Need to understand what a test failure means
Prerequisites
- Dev server must be running (
cd test-app && npm run dev)
- Playwright MCP tools available
- Failed test has generated artifacts in
test-results/
Screenshot Output
Playwright MCP is configured to save screenshots to the workspace-level temp/ directory (set via --output-dir in .vscode/mcp.json). Screenshots taken during live debugging with MCP tools will appear there. The temp/ folder is gitignored.
Debugging Workflow
Step 1: Run the Specific Failed Test
Run ONLY the specific failing test using the -g flag to get focused output:
npx playwright test <test-file>.spec.ts -g "test name"
Step 2: Analyze the Test Output
Read the terminal output carefully and extract:
- Test location: File path and line number
- Failure type: What assertion failed
- Expected vs Actual: What the test expected vs what it got
- Error message: The specific error
- Artifact paths: Screenshot and error-context locations
Step 3: Load the Screenshot
Test-run failure screenshots land in:
test-results/<test-name>/test-failed-1.png
Screenshots taken manually during MCP exploration land in:
temp/
Use the read_media_file tool (or the Playwright MCP screenshot tool) to view either.
Step 4: Read the Error Context
Read the error-context.md file from the test results directory.
Key things to look for:
- Are the elements the test is looking for present?
- Are there unexpected elements?
- Are there console errors indicating broken functionality?
- Is the page structure what the test expects?
Step 5: Read the Test Code
Read the failing test code to understand:
- What is it trying to test?
- What user actions does it simulate?
- What assertions does it make?
- Are the selectors specific enough?
Step 6: Compare Test Expectations with Implementation
Use grep or semantic_search to find the actual component/page being tested:
grep -r "text the test looks for" test-app/src/
Check:
- Does the text match exactly? (case, spacing, punctuation)
- Are the element types correct?
- Does the page structure match expectations?
Step 7: Use Playwright MCP (If Needed)
If the issue isn't clear from the screenshot and error context, use Playwright MCP to interact with the live app:
- Navigate to the page:
playwright_navigate
- Take a screenshot:
playwright_screenshot
- Get HTML:
playwright_get_visible_html
- Click elements:
playwright_click
- Inspect what happens:
playwright_get_visible_text
Common Starting Workflow
The most common Playwright MCP exploration starts with the test-app and involves opening the inspector panel:
- Navigate to the test app:
http://localhost:5173
- Click the toggle button (⊕) — this opens the sidebar/panel container with the inspector iframe
- Click the "Primary" button on the page — this sends
ELEMENT_SELECTED to the panel and populates the inspector with the Button component's properties (Box Model, Typography, Backgrounds, etc.)
From here you can interact with the panel iframe (scrubbers, dropdowns, color chips, footer buttons) to inspect or reproduce the issue. The panel lives inside an iframe at /panel/ — remember that Playwright MCP will show iframe elements with f* prefixed refs (e.g. f1e5).
Step 8: Fix the Issue
Based on your findings, fix either the test, the code, or both.
Step 9: Verify the Fix
npx playwright test <test-file>.spec.ts -g "test name"
Tips for Effective Debugging
- Always run the single test first - Don't debug from full suite output
- Start with artifacts - Screenshot + error-context tell you 90% of issues
- Use MCP sparingly - Only when artifacts don't show the problem
- Check obvious things first - Routes, text, element types
- One test at a time - Fix and verify before moving to next failure
- Read the DOM snapshot - Often more useful than screenshot for structural issues
Related Skills
- write-e2e-test: Create new E2E tests
- debugging: Verify error-free UI before testing
