Menu
Debug Playwright E2E test failures — port conflicts, server startup, test isolation, and post-mortem analysis
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
Cut a Tandem release — six-surface version bump, changelog, tag, GitHub Release publish, smoke checklist
Use when tandem_* MCP tools are available, the user asks about Tandem document editing, or iterating on text collaboratively. Provides workflow guidance, annotation strategy, and tool usage patterns for the Tandem collaborative editor.
Start Tandem dev environment (server + client) and verify MCP connection
Generate a Keep a Changelog entry from git log since the last tag
Capture README screenshots of the Tandem editor UI via Playwright + MCP
Run Playwright E2E tests safely (warns about dev server conflicts)
| name | e2e-debug |
| description | Debug Playwright E2E test failures — port conflicts, server startup, test isolation, and post-mortem analysis |
| disable-model-invocation | true |
Post-mortem guide for Playwright E2E failures in Tandem. Complements the /e2e skill (which covers the happy path).
E2E tests use freePort() which kills any process on :3478/:3479. Confirm with the user that no dev server is in use before running.
Before running E2E tests, verify:
# 1. Server bundle exists (E2E uses pre-built server, not tsx)
ls dist/server/index.js
# 2. Ports are free (or confirm user is OK with kill)
curl -sf http://127.0.0.1:3479/health && echo "⚠ Server running on :3479" || echo "✓ Port free"
curl -sf http://127.0.0.1:3478 && echo "⚠ Hocuspocus running on :3478" || echo "✓ Port free"
# 3. Client build exists (for webServer)
ls dist/client/index.html
If dist/server/index.js is missing or stale:
npm run build:server
Symptom: Timed out waiting for http://127.0.0.1:3479/health
Cause: dist/server/ is stale or missing
Fix: npm run build:server then retry
Symptom: Client page fails to load
Cause: Vite webServer not started (check playwright.config.ts webServer section)
Fix: Verify npm run dev works standalone; check for port conflicts on :5173
Symptom: Tests find unexpected documents open or wrong tab state Cause: Prior test crash left session state on disk Fix: Delete session directory:
%LOCALAPPDATA%\tandem\Data\sessions\~/Library/Application Support/tandem/sessions/~/.local/share/tandem/sessions/Symptom: locator.click: Error: strict mode violation or element not found
Cause: testid was renamed or component restructured
Fix: Check CLAUDE.md Critical Rule #7 for the current testid list. Use [data-testid="..."] selectors, not CSS classes.
Symptom: First test in suite fails, rest pass
Cause: Known Playwright webServer cold-start issue (#230)
Fix: The project uses a retry-on-first-failure workaround. If this regresses, check playwright.config.ts for the retries and webServer.timeout settings.
For a single spec with browser visible:
npx playwright test tests/e2e/specific.spec.ts --headed --workers=1
For trace collection on failure:
npx playwright test tests/e2e/specific.spec.ts --trace on
View the trace:
npx playwright show-trace test-results/specific-spec-ts/trace.zip
display toggle). Use toBeVisible() not toBeAttached().import.meta.url + fileURLToPath, not __dirname.upload:// paths from test fixtures don't support tandem_save.