# Debug a failing test

> For the complete documentation index, see [llms.txt](/llms.txt)

A failing step freezes the run so you can inspect it, instead of dumping a stack
trace.

## In the viewer

1. Open the scenario, click a gutter dot to set a **breakpoint**.
2. Click **Debug** (headed + pause on breakpoints and failure).
3. When it pauses, inspect **Vars / Call stack / Trace**, then **Continue /
   Step / Stop**.

See [Step debugger](/viewer/debugger/).

## From the CLI

```sh
npx @unotest/web e2e checkout --debug
# or target a line directly
npx @unotest/web e2e checkout --break 24:5
```

## With your agent

Ask the agent to fix the failure. It calls `inspect_runtime` at the pause point,
reads the [failure bundle](/concepts/failure-bundles/), and proposes a diff via
`agent_fix`. **You review and commit** — nothing is applied silently.

## Common fixes

| Symptom | Likely fix |
| --- | --- |
| Locator timed out | selector drifted → [stable selector](/concepts/selectors/) |
| Element found but not actionable | add a `waitFor` |
| Expected ≠ actual | update the assertion |

For full diagnostics (JSONL log + artifacts), set `UNOTEST_DEBUG=1`.