Reading a failure

When a test fails, do not panic — the information you need is almost always right there. Follow this checklist to diagnose what went wrong and decide what to do next.

Step 1: Read the error message

Open the HTML report (pnpm run report) and click the failed test. The top of the result shows:

• The error message — for example TimeoutError: locator.click() timed out or expect(received).toBe(expected).
• Which step failed — the step timeline highlights the exact action that errored. Everything before it succeeded.

Read both carefully before doing anything else. The step that failed tells you where in the flow things went wrong; the error message tells you how.

Step 2: Watch the trace and video

Click the Trace or Video link in the report for that test.

• Video — watch the browser playback to see what the page looked like when the test ran. Look for unexpected popups, loading spinners, or missing elements.
• Trace — step through the timeline to inspect the DOM snapshot at the moment of failure. You can see exactly which element the test was trying to interact with and what was actually on the page at that instant.

See Reports, traces & videos for how to navigate the trace viewer.

Step 3: Decide what kind of failure it is

Symptom	Likely cause
Test used a name or ID that doesn't exist in the app	Data problem
Dropdown or field value doesn't match what the test typed	Data problem
A page or feature the test expects is missing or broken	App bug
A selector timed out on a page that otherwise looks correct	Could be either — dig deeper
The test was working before a recent data change	Data problem

Data problems

If the failure looks like the test was trying to use a value that isn't in the application (wrong project name, wrong person, missing estimate), the fix is in tests/data/.

See Editing data files for step-by-step instructions on changing a value safely and validating it before committing.

Real app bugs

If the trace shows the page is genuinely broken — a button is missing, a form throws an error, a route returns 404 — that is a bug in the application, not in the test.

Step 4: When to escalate to a developer

Escalate to a developer when:

• The trace shows a JavaScript error or network request failure that you cannot explain.
• A page or feature that used to work has stopped working and no data file has changed.
• The failure reproduces consistently across multiple test runs on the same environment.
• You are unsure whether the behaviour you are seeing is intentional.

When you escalate, share:

1. The full error message from the report.
2. A screenshot or short description of what the trace showed at the failing step.
3. The environment (TEST_ENV) you were running against.

Step 5: When to re-run /review-test

If the test itself looks suspicious — wrong selector, incorrect assertion, logic that no longer matches how the feature works — ask the AI to review it:

See /review-test for how the command works and when to use it.

Re-running /review-test is appropriate when:

• The feature behaviour has changed and the test needs to be updated to match.
• The test assertion checks for something that is no longer correct.
• The selector used in the test has drifted from the current DOM.

When in doubt, re-run the test first

Before concluding there is a bug, re-run the failing test once on its own (pnpm exec playwright test -g "<test title>"). Intermittent network or timing issues occasionally cause one-off failures that do not repeat.