Debugging a failure
Read a failure card, inspect the recorded steps and use the run evidence to decide what to fix.
When a test fails, read its failure class and any compared values, then follow the recorded steps to find the cause. This page shows how to use the terminal card and saved evidence before deciding what to fix.
Read the failure card Link to Read the failure card
The terminal prints a card for a failed test. This shortened example comes from the task test running against an app that drops the last letter of the saved title.
Check failed toHaveTextLocator getByTestId('saved-task')Page "Tasks" at http://127.0.0.1:4173/- Expected "Release checklist"+ Received "Release checklis"Compared whole text, ends trimmed, each run of spaces or line breaks read as one spaceWaited 5s for toHaveText, looked 14 times, limit 5stests/task.retest.ts:7:48 5 │ await page.getByTestId('task-title').fill('Release checklist') 6 │ await page.getByTestId('save-task').click()› 7 │ await expect(page.getByTestId('saved-task')).toHaveText('Release checklist') 8 │ })The locator found the saved-task element, but its text never matched during the five-second budget. The comparison line explains how Retest treated whitespace, so the missing letter is not a formatting difference. Check the save behaviour before increasing the timeout.
The full card also gives the failing source line, available screenshots and diagnostics, and commands to rerun or inspect the test. Copy its commands because they include the actual test id and target, which may differ from the examples here.
Inspect the recorded steps Link to Inspect the recorded steps
retest inspect reads a saved folder without running tests or opening a browser. First inspect the whole run, then pass the test id from the report to see that test's timeline.
npx retest inspect .retest/runs/<time>npx retest inspect .retest/runs/<time> --test "tests/task.retest.ts > saves a task"npx retest inspect .retest/runs/<time> --test "tests/task.retest.ts > saves a task" --jsonReplace <time> with the folder printed by your run. The timeline lists navigations, actions and checks in time order. Under a locator check, it prints how many times it looked and the deciding observation, labelled passed on or failed on, rather than every observation.
If the test ran on several targets, add a selector such as --target web=chromium to inspect one variant. --json emits the test result, events and available diagnostics as one document, which is useful for a coding agent or your own tools.
Follow the kind of failure Link to Follow the kind of failure
A text mismatch needs a different investigation from a locator that found nothing or a browser that disappeared. Use the failure kind to choose the next thing to check.
| Failure | What to check next |
|---|---|
check_failed | Compare the expected state with the received value and screenshot. Did the app reach the wrong state, or is the expectation wrong? |
not_found | Check the page address, accessible name and locator scope. The element may be inside a frame or absent from this screen. |
ambiguous | Narrow the locator to one control or container before sending input. |
not_actionable | Read the named readiness problem, such as a disabled control or a covering overlay. |
setup_failed | Check the browser, server log, secret source or sign-in setup named in the message. |
not_awaited or no_assertions | Await the reported operation or add a check that proves the outcome. |
unsupported | Check the guide for that capability and engine before changing the test. |
outcome_unknown | Inspect the app state before repeating the action, because input may already have arrived. |
A test marked error could not be checked or cleaned up reliably. inconclusive means a required AI check could not decide; not_run means the test never ran. These outcomes do not count as passes. Results and exit codes lists the full set of statuses and failure kinds.
Open the HTML report Link to Open the HTML report
For a visual view of the same evidence, build the report from the run folder. You can do this after a failure or request it as part of the next run.
npx retest report .retest/runs/<time>npx retest run --reporter htmlOpen report.html inside that run folder. It needs no server and loads no external resources. The report links screenshots, shows each app's steps and includes the console and network records the engine could capture. If the run recorded video, its timeline can seek the recording to a step.
Keep the folder together when moving or sharing it, because screenshots and recordings use relative paths. A missing or withheld artifact is named with its reason rather than silently shown as available. Recordings and evidence explains capture settings and their limits.
Read the app's diagnostics Link to Read the app's diagnostics
If the saved title never appears, look for a failed save request or an app error around the click. The report and inspect --test show captured console and network metadata together with the capture's scope and completeness.
An empty log only tells you that nothing was captured in that scope. For example, Firefox captures requests but no console messages, and request bodies are not recorded. Console and network explains what each engine can show.
Investigate an interrupted run Link to Investigate an interrupted run
A run normally writes result.json when it ends. If it stopped before that file was written, inspect and report rebuild what they can from events.jsonl and mark the run incomplete. They never turn a partly recorded run into a pass.
The run folder also keeps test-file output, browser output and logs from servers Retest started. Use the Run folder reference to find a particular file when the terminal report cannot explain the interruption.
Rerun after the fix Link to Rerun after the fix
After changing the app or test, copy the card's rerun command to check the same target again. Use --last-failed to rerun results marked failed, error or not_run from the last run.
npx retest run --last-failedEach rerun creates a new folder, leaving the earlier failure available for comparison. For an inconclusive AI check, select the test explicitly as described in Running tests; --last-failed leaves those results out.