---
title: Debugging a run
description: Read the trace page, open the evidence, watch the browser, and see what the model was sent.
"og:image": "https://e2e.com/docs/images/og/debugging.png?v=38a51086e1"
"twitter:image": "https://e2e.com/docs/images/og/debugging.png?v=38a51086e1"
---
A failed test prints its error and the path to its [trace page](#traces). For
a summary of the whole run, add the `markdown` reporter. It writes
`.e2e/summary.md`.
## Read the failure
The `list` reporter's `Failed Tests` section shows the error, the failing
line, nearby matches for a failed locator, what the app logged, and the
trace page. It quotes the app's first 3 errors (console errors, uncaught
exceptions, failed requests, 5xx responses), redacted like the trace page.
`.e2e/summary.md` quotes them too:
```text
FAIL |web| tests/todos.e2e.ts > shows the remaining count
LOCATOR_NOT_FOUND: locator did not become visible: getByRole("heading", name: "Todos")
❯ tests/todos.e2e.ts:31:3
❯ at http://127.0.0.1:4271/nope
❯ app 2 errors, 2 warnings logged
× console error: Error occurred prerendering page "/todos"
× network error: GET /api/todos 500 Internal Server Error
❯ trace .e2e/results/todos-shows-the-remaining-count-796fac5f12ab34cd/trace.md
```
The exit code tells the type of failure:
| Exit | Meaning | Retry the job? |
| ---: | --- | --- |
| 1 | A test failed | Only if the test is flaky |
| 2 | Configuration, collection, or policy | Fix the reported problem first |
| 3 | Engine, app process, model provider, artifact, or cleanup infrastructure failure | If the cause is temporary |
| 4 | An internal runner error | Report it |
| 130 | The run was interrupted | |
## Traces
By default, each failed, timed out, interrupted, or flaky test gets a trace
page, `trace.md`, in its [results directory](#artifacts). Open it in an
editor's markdown preview so its links work. After the browser or device
the test ran on, it shows:
- **Steps.** The node an action landed on, the values an assertion read
while it waited, the replay cache's decision, what the app logged, where
the page went, and how the screen changed since the step before.
- **App log.** Console output, uncaught exceptions, failed requests, and
4xx and 5xx responses, each with its step: up to 50 lines, errors and
warnings first. An attempt keeps at most 200 errors and warnings and 100
other lines.
- **The agent's last turns.**
- **Screen at failure.** The screenshot and the semantic tree, captured in
at most 5 s. An app that doesn't answer in time gets no screen section.
````markdown
# ✗ todos › shows the remaining count
`tests/todos.e2e.ts` · failed · 2.2s
**ASSERTION_FAILED**
```text
expect.toHaveText failed
locator: getByRole("status", name: "Remaining")
expected: text "1 remaining"
observed: text "0 remaining" (match count 1)
```
Ran on: browser `chromium 141.0.7390.37` · user agent `Mozilla/5.0 (Macintosh; …) HeadlessChrome/141.0.7390.37 Safari/537.36`
Look at: `tests/todos.e2e.ts:15`
## Steps
1. ✓ `app.open` `/todos` (37ms in beforeEach) — `tests/todos.e2e.ts:4`
2. ✓ `agent.act` "Add a todo named Milk." (429ms, 2 model calls) — `tests/todos.e2e.ts:12`
- cache: no replay: nothing recorded for this step yet; recording saved (`.e2e/cache/1227d5a6….json`)
- type "Milk" into textbox "New todo" (17ms)
- press "Enter" on the focused field (5ms)
- ✗ network error: `POST /api/todos 500 Internal Server Error`
- screen: 6 changes since step 1 at `/todos`, 38 nodes
- `added listitem "Milk Delete Milk" testid="todo"`
- `added checkbox "Milk"`
- `changed status "Remaining" text="1 remaining" (was: status "Remaining" text="0 remaining")`
- 3 more
3. ✓ `locator.check` `getByLabel("Milk")` (13ms) — `tests/todos.e2e.ts:14`
- check checkbox "Milk" (13ms)
- screen: 3 changes since step 2 at `/todos`, 38 nodes
- `added checkbox "Milk" [checked]`
- `changed status "Remaining" text="0 remaining" (was: status "Remaining" text="1 remaining")`
- `removed checkbox "Milk"`
4. ✗ `expect.toHaveText` `getByRole("status", name: "Remaining")` (1.6s) — **ASSERTION_FAILED** — `tests/todos.e2e.ts:15`
- expect gave up after 16 reads in 1.6s: text "0 remaining" (1 match) x16
## App log
What the app logged, oldest first, with the step it happened in.
- step 2 · ✗ network error: `POST /api/todos 500 Internal Server Error`
## Screen at failure
`http://127.0.0.1:4271/todos` · viewport 1280x720 · 38 nodes

```text
#n29 textbox "New todo"
#n30 button "Add"
#n35 listitem "Milk Delete Milk" testid="todo"
#n36 checkbox "Milk" [checked]
#n40 status "Remaining" text="0 remaining"
```
````
An assertion that read one value the whole time has a wrong expectation, or
the app never reached that state: look in the app log for a failed request.
An assertion whose readings changed (`"2 remaining" x3 -> at 410ms "1
remaining"`) raced the app. `screen: unchanged` after an action means the
action had no visible effect. On web, a step's screen is the one an action
left. On a device, it's the screen the step acted on.
The [`trace`](/reference/config#trace) mode sets which tests keep a page.
`--trace` keeps one for every test of a run, passing ones included.
`--trace off` writes none. A test's own `trace` option wins over both.
## Artifacts
Each test gets one directory under `.e2e/results/` (or
[`