# Debugging a failure

> Read a failure card, inspect the recorded steps and use the run evidence to decide what to fix.

Source: https://rehearsal.dev/retest/docs/essentials/debugging

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

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.

```text
Check failed     toHaveText
Locator          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 space
Waited           5s for toHaveText, looked 14 times, limit 5s

tests/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

`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.

```sh
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" --json
```

Replace `<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

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](https://rehearsal.dev/retest/docs/reference/results.md) lists the full set of statuses and failure kinds.

## 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.

```sh
npx retest report .retest/runs/<time>
npx retest run --reporter html
```

Open `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](https://rehearsal.dev/retest/docs/guides/recordings-and-evidence.md) explains capture settings and their limits.

## 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](https://rehearsal.dev/retest/docs/guides/console-and-network.md) explains what each engine can show.

## 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](https://rehearsal.dev/retest/docs/reference/run-folder.md) to find a particular file when the terminal report cannot explain the interruption.

## 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.

```sh
npx retest run --last-failed
```

Each 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](https://rehearsal.dev/retest/docs/essentials/running-tests.md); `--last-failed` leaves those results out.

## Next steps

- [Console and network](https://rehearsal.dev/retest/docs/guides/console-and-network.md): Understand diagnostic capture and engine coverage.
- [Recordings and evidence](https://rehearsal.dev/retest/docs/guides/recordings-and-evidence.md): Keep screenshots, videos and other run artifacts.
- [Results and exit codes](https://rehearsal.dev/retest/docs/reference/results.md): Look up a status or failure kind.