// 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.
| 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. |
This skill provides a systematic workflow for debugging and fixing failing Playwright E2E tests in the test-app.
Use this skill when:
cd test-app && npm run dev)test-results/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.
Run ONLY the specific failing test using the -g flag to get focused output:
npx playwright test <test-file>.spec.ts -g "test name"
Read the terminal output carefully and extract:
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.
Read the error-context.md file from the test results directory.
Key things to look for:
Read the failing test code to understand:
Use grep or semantic_search to find the actual component/page being tested:
grep -r "text the test looks for" test-app/src/
Check:
If the issue isn't clear from the screenshot and error context, use Playwright MCP to interact with the live app:
playwright_navigateplaywright_screenshotplaywright_get_visible_htmlplaywright_clickplaywright_get_visible_textThe most common Playwright MCP exploration starts with the test-app and involves opening the inspector panel:
http://localhost:5173ELEMENT_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).
Based on your findings, fix either the test, the code, or both.
npx playwright test <test-file>.spec.ts -g "test name"
Always start a fresh browser session after any file change, walk through the full user flow, and monitor for errors before proceeding with further work.
Set up and run different development service arrangements for testing specific features. Use when starting dev servers, testing Storybook addon (SB8 or SB10), testing Tailwind v3 vs v4, testing Astro, or when asked which services to run. Covers compound tasks, port assignments, and which services need each other.
Defines the interaction behavior of global mode buttons (Select, Insert) and component row buttons (Place, Replace). Use when modifying button states, colors, labels, tab visibility, or page interaction behavior. Must review and update these tables before making changes.
Canonical naming for all Convey UI parts, features, and concepts. Reference when discussing, documenting, or writing code for any part of the app. Ensures consistent terminology across humans and AI agents.
Build panel UI components that live-preview Tailwind className changes in the user's app via WebSocket. Use when creating any control (dropdown, scrubber, color picker, toggle, etc.) that lets users hover/scrub values before committing. Covers the preview/revert/stage lifecycle, the onHover/onLeave prop contract, and the focus-trap pattern that prevents preview leaks.
Canonical terminology for Tailwind CSS concepts used throughout the codebase. Reference this skill to ensure consistent naming in code, docs, and conversation.