Follow the repository's test commands, conventions, and safety requirements. Choose the matching workflow below, then load only the references needed for that step. Resolve reference paths relative to this skill directory.
Troubleshoot a failure
Start with existing failure evidence before preparing a new test run.
- Identify the failure. Match the report to the requested test, Playwright project, and revision. Locate its error, screenshot, error-context file, and trace when available. Separate the primary failure from interrupted tests, teardown errors, and run-level errors; investigate the latter independently if they may be causal.
- Inspect the artifact. For an existing trace, follow trace-inspection.md to select the installed native reader and extract evidence safely. Start with the failing action and its immediately preceding relevant actions. If only supplied excerpts are available or permitted, work within them and state what is missing.
- Correlate actions with state. Check locator parameters, boolean return values, action logs, and available DOM snapshot phases around the suspected transition. A completed click does not prove its handler ran; a present DOM element does not prove visibility or readiness. Distinguish recorded execution from snapshot-replay diagnostics. Return bounded excerpts with action IDs/phases and disclose omitted scope.
- Inspect the implicated source. Read the failing test, its relevant helper/fixture, and only the application code needed to explain the observed sequence. Verify source/revision alignment before treating current code as the cause of a historical failure. Use the reference routes below for the specific symptom rather than loading every debugging guide.
- Reproduce when needed. If the evidence cannot distinguish plausible causes, run the narrowest relevant reproduction and collect a trace. For a requested fix, reproduce the failure before changing behavior and rerun it after the fix. Scope commands to the failing test/project using the repository's runner; widen coverage after the focused signal is useful.
- Report the result. Give the observed sequence with evidence references, the supported explanation versus remaining hypotheses, and any missing evidence. State separately whether an independent reproduction and fix verification occurred. A diagnosis-only request can finish with sufficient artifact evidence; inspecting an archive alone proves neither reproduction nor a fix.
Load operational guidance when the investigation needs it. Existing trace inspection does not require application startup or a backend reset. An application's dependency on a service such as Supabase does not itself require stack setup or service-specific skills during artifact analysis. Load the relevant skills and operational safety instructions before investigating or operating that service, and obtain approval for destructive operations.
Choose a reference
| Task or finding | Read next |
|---|---|
| Existing trace / CI artifact | Trace inspection |
| Locator, missing element, or timeout | Locators, Assertions and waiting |
| Race, intermittent failure, or parallel-only failure | Flaky tests; use Fixtures when isolation is implicated |
| Recorded console or JavaScript error | Console errors |
| Need a fresh reproduction or debugger | Debugging tools |
| Write a new E2E test | Test structure, Locators, Assertions and waiting |
| Refactor tests or page objects | Page Object Model, Fixtures |
| Configure the runner or project dependencies | Configuration, Project dependencies |
| Component/API tests, framework-specific work, mobile, browser APIs, CI, or another specialized task | Full activity catalog — choose the matching category only |
Validate test changes
This loop applies after writing or modifying tests, not to artifact-only diagnosis:
-
Run the affected test with the repository's runner and appropriate project, for example:
npx playwright test path/to/changed.spec.ts --project=chromium --reporter=list -
If it fails, return to artifact-first troubleshooting, fix the demonstrated cause, and rerun the focused test.
-
For timing-sensitive or critical changes, repeat the affected test (for example
--repeat-each=5) before running related coverage required by the repository. -
Report executed checks and their outcomes. If a required check cannot run or remains failing, state the limitation rather than claiming validation.