> ## Documentation Index
> Fetch the complete documentation index at: https://e2e.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Reporters

> Receive run events and publish results with a custom reporter.

A reporter receives the run's events as they happen and the finished run
once its report is written. `reporters` in `e2e.config.ts` lists built-in
reporters by id beside reporter objects.

```ts title="e2e.config.ts"

export default {
  targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
  reporters: ['list', 'junit', github()],
} satisfies E2EConfig;
```

To pass a built-in reporter options, call its factory from `e2e/reporters`
in place of the id: `junit({ outputFile: 'reports/junit.xml' })`. An id is
its factory called with no options.

The built-in reporters use only the [`Reporter`](#custom-reporters) contract,
so a reporter of your own can do anything they do.

## Reference

### Built-in reporters

| Reporter | Description |
| --- | --- |
| [`list`](#list) | Terminal progress and run summary |
| [`dot`](#dot) | Compact progress and run summary |
| [`json`](#json) | Report document to stdout |
| [`junit`](#junit) | Writes `<output>/junit.xml` |
| [`markdown`](#markdown) | Writes `<output>/summary.md` |
| [`github()`](#github) | Pull request comment and job summary |
| [`htmlReporter()`](#htmlreporter) | Writes `<output>/report.html` |

| Throws | When |
| --- | --- |
| `INVALID_CONFIG` | `reporters` is not an array. |
| `INVALID_CONFIG` | An id other than `list`, `dot`, `json`, `junit`, or `markdown`. |
| `INVALID_CONFIG` | A factory not called, such as `junit` for `junit()`. |
| `INVALID_CONFIG` | An entry that is neither an id nor an object with a `name` and at least one hook. |
| `INVALID_CONFIG` | Two reporters that [print to](#printsto) one stream, such as `list` and `dot`. |

#### `list`

Renders terminal progress, failures, and the run summary.

```ts
reporters: ['list'], // default
```

- `list({ stream })` sets the terminal stream it [prints to](#printsto):
  `'stdout'` or `'stderr'`. Without it, `list` prints to stdout, or to
  stderr beside `json`.
- It renders the same events
  [`onEvent`](#onevent) receives, with what your code prints
  ([`onOutput`](#onoutput)) and the `--step` prompt
  ([`onStepPrompt`](#onstepprompt)).
- On a TTY a live view shows the running tests. When stdout is not a
  terminal (piped, redirected, most CI), each test prints as it finishes.
- Its [`onSummary`](#onsummary) prints every reporter's summary rows under
  its summary.
- The output ends with a `Failed` row per failed test: its file and line,
  its error's first line, and its trace page when one was written, so `e2e run | tail` still
  names what broke.

#### `dot`

Prints one character when each selected test finishes.

```ts
reporters: ['dot'],
```

| Passed | Flaky | Failed | Timed out | Interrupted | Skipped |
| --- | --- | --- | --- | --- | --- |
| `.` | `~` | `F` | `T` | `I` | `-` |

Rows wrap after 80 marks. Colors follow the terminal settings; `NO_COLOR`
disables them. The run header, failure details and locations, summary, and
step prompts use the same format as `list`.

It prints to stdout by default; `dot({ stream: 'stderr' })` moves it. Beside
`json`, as in `--reporter dot,json`, `dot` prints all of it to stderr, so
stdout holds the JSON report.

Unlike Playwright, e2e uses ASCII marks and prints only the final result
after retries, with no mark for each retried attempt.

#### `json`

Prints the report document to stdout.

```ts
reporters: ['json'],
```

It [prints to stdout](#printsto) and takes no output, so what your code
prints goes to stderr.

#### `junit`

Writes `junit.xml` beside the report.

```ts
reporters: ['list', 'junit'],
```

- `junit({ outputFile: 'reports/junit.xml' })` from `e2e/reporters` writes
  it elsewhere, as a path from the project root. Default: `junit.xml` in the
  [output directory](https://e2e.com/docs/reference/config#output).
- Its [`reportFiles`](#reportfiles) renders `run.report` as one file with a
  `JUnit` row. It is the smallest complete example of a reporter, and it
  writes nothing when the report was not written.
- When a test that failed, timed out, passed only on a retry, or failed as
  [`test.fail`](https://e2e.com/docs/reference/test#fail) expected recorded a failure screenshot, its `<testcase>` links it as
  `<system-out>[[ATTACHMENT|<path>]]</system-out>`, which GitLab CI shows in
  the pipeline test report. The path is relative to `$CI_PROJECT_DIR`, or to
  the project root when that is unset; screenshots outside it get no link.

#### `markdown`

Writes `summary.md` beside the report.

```ts
reporters: ['list', 'markdown'],
```

It does what `junit` does with `summary.md`, through
[`renderMarkdownReport`](#rendermarkdownreport), and takes the same
`outputFile`: `markdown({ outputFile: 'reports/summary.md' })`.

<a id="rendermarkdownreport" />

##### `renderMarkdownReport`

Renders a report as the Markdown page the `markdown` reporter writes, so
your own reporter can post the same page elsewhere.

```ts

const reporter: Reporter = {
  name: 'wiki',
  async onRunFinished(run) {
    const page = renderMarkdownReport(run.report, { traces: run.traces });
    await fetch('https://wiki.example.test/runs', { method: 'POST', body: page });
  },
};
```

- `traces` links each block to its trace page by result id.
- [`@e2e-dev/github`](https://e2e.com/docs/github) is that reporter for GitHub Actions.

#### `github()`

`@e2e-dev/github` posts the run as one pull request comment from GitHub
Actions, keeps it current on reruns, and writes the same text to the job
summary.

```ts

const reporter = github({ key: 'chromium' });
```

- `key` tells one job's comment apart from another's when the workflow, job,
  and project are the same, as in a matrix. Without it, matrix replicas of
  one job share a comment, and the last one to finish wins. Never use the
  run id: a rerun must find the old comment. The key also names the comment
  in its headline: `e2e chromium: 77 passed`.
- It reads the token, the event, and the repository when the run finishes,
  never when the config loads.
- With `--last-failed`, it folds the rerun into [`lastRun`](#onrunfinished)
  to show both runs as one comment.
- Setup and permissions are on [Pull request comments](https://e2e.com/docs/github).

#### `htmlReporter()`

`@e2e-dev/html-reporter` writes the run as one page you open in a browser:
the tests by file with status tabs and a search box, and for each test its
attempts, error, steps, screenshots, and video.

```ts

const reporter = htmlReporter({ media: 'embed' });
```

- Its [`reportFiles`](#reportfiles) writes `report.html` beside the report,
  with the report document embedded. The page opens from disk with no server, or with
  [`npx e2e report`](https://e2e.com/docs/reference/cli#e2e-report).
- A run that writes no report writes no page either, so the previous run's
  page stays, as `junit.xml` does. See [Output](https://e2e.com/docs/reference/cli#output).
- `media` decides what happens to screenshots, videos, and downloads:

  | `media` | The page | To share it |
  |---|---|---|
  | `'link'` (default) | links them from `<output>/results/` by relative path | keep the output directory together, as one CI artifact |
  | `'embed'` | holds them, so the one file is the whole report | send the file; device videos make it tens of megabytes per minute |
  | `'none'` | leaves them out and shows text only | send the file |

  A download link saves the file instead of opening it. A download the
  runner could not scan for secrets, such as a PDF or a zip, stays out of an
  embedded page, and a video a hosted browser or device service keeps stays
  a link to it.
- `outputFile` puts the page elsewhere, as a path from the project root (pass that path to `e2e report <path>` when running from the project root).
- The page shows only the run that wrote it: after `--last-failed`, the
  rerun's tests without the failures it carried over, and under
  `e2e explore`, the exploration without its findings.
- The tests list as a tree: each file, its describe blocks, then their tests,
  failures first. Selecting a file's path folds its tests away.
- A run that selected more than one target gets target tabs above the status
  tabs. Picking one shows only its tests and their counts; the URL carries
  the choice, so a filtered view keeps working as a link.
- Each step shows where it starts in the attempt's video; selecting the time
  plays the video from there, and the step the video is on stays
  highlighted. The video's timeline marks each step's start, and its speed
  button steps from 0.25× to 4×; a recording under five seconds starts
  slowed down. A phone recording sits beside the steps instead of above
  them.
- A failed assertion that reports expected and received values (a locator
  assertion, say) shows them with the characters that differ marked. When
  the test file is in the project, the failure shows the code around the
  failing call, and each step opens to the code that ran it. The page keeps a few lines of the
  test files around each step for this, so a shared report shows them too.
- **copy prompt** on a failed attempt's error copies the failure for a coding
  agent: the error, the steps, what the failed step did, and the paths of
  whichever of its trace page, screen tree, screenshot, and video exist, from
  the project root.
- Agent steps show their explanation, the actions they took, the model,
  tokens and cost, whether the step replayed from the cache, and their last
  turns.
- The page follows the system's light or dark theme. The sun and moon at the
  top hold one, and the browser keeps the choice for every report it opens.

### Custom reporters

A reporter object has a `name` and at least one hook. Each hook goes to
every reporter that has it. Use `onEvent` for live progress, `reportFiles`
for files beside the report, and `onRunFinished` to send the final report
somewhere.

```ts title="e2e.config.ts"

const upload: Reporter = {
  name: 'upload',
  async onRunFinished(run) {
    const response = await fetch('https://example.test/runs', {
      method: 'POST',
      body: JSON.stringify(run.report),
    });
    const { url } = (await response.json()) as { url: string };
    return [{ label: 'Results', text: url }];
  },
};

export default {
  targets: [{ engine: web(), app: { url: 'localhost:3000' } }],
  reporters: ['list', upload],
} satisfies E2EConfig;
```

| Member | Type |
| --- | --- |
| [`name`](#name) | `string` |
| [`printsTo`](#printsto) | `'stdout' \| 'stderr'` |
| [`onEvent`](#onevent) | `(event: RunEvent) => void` |
| [`onOutput`](#onoutput) | `(output: ReporterOutput) => void` |
| [`onStepPrompt`](#onstepprompt) | `(prompt) => void` |
| [`reportFiles`](#reportfiles) | `(run, signal) => ReportFile[]` |
| [`onRunFinished`](#onrunfinished) | `(run, signal) => Promise<…>` |
| [`onSummary`](#onsummary) | `(rows: ReporterSummary) => void` |

```ts
interface Reporter {
  readonly name: string;
  readonly printsTo?: 'stdout' | 'stderr';
  onEvent?(event: RunEvent): void;
  onOutput?(output: ReporterOutput): void;
  onStepPrompt?(prompt: StepPrompt | undefined): void;
  reportFiles?(run: FinishedRun, signal: AbortSignal): readonly ReportFile[] | Promise<readonly ReportFile[]>;
  onRunFinished?(run: FinishedRun, signal: AbortSignal): Promise<ReporterSummary | void>;
  onSummary?(rows: ReporterSummary): void;
}
```

Cached steps expose `cache.recordedBy: { provider, model }` in `report.json`
and on the trace page when the recording has it. Older recordings omit it.
The console prints `replayed · recorded with provider/model` only when that
identity differs from the configured model. It stays quiet for multi-agent
runs and for pinned agents whose model is not in the run header.

#### `name`

The reporter's label in diagnostics. Required and non-empty. It may match a
built-in's name: a reporter named `json` is still yours, and `--reporter`
never replaces it.

```ts
name: 'upload',
```

#### `printsTo`

The terminal stream the reporter prints to, as [`list`](#list) and
[`json`](#json) print to stdout. One reporter per stream can set it, since
two would garble each other.

```ts
printsTo: 'stdout',
```

- Its hooks write to `process.stdout` or `process.stderr` directly. The
  runner doesn't redact that output, so print only what the events and the
  report hold: those are redacted already.
- When the reporter printing to stdout has no [`onOutput`](#onoutput), as
  `json`, what the runner prints itself goes to stderr, so stdout holds only
  what that reporter prints.
- `--step` needs the reporter printing to stdout to have
  [`onStepPrompt`](#onstepprompt), as `list` does.
- A second Ctrl-C never stops its `onRunFinished`: its output is local.
- A run embedded through [`e2e/runner`](https://e2e.com/docs/reference/runner) skips a
  reporter that sets `printsTo` and has `onOutput`, such as `list` and `dot`.

#### `onEvent`

Receives every run event as it happens, as plain JSON.

```ts
onEvent(event) {
  switch (event.type) {
    case 'test-finished':
      console.log(event.result.test.title, event.result.status);
      break;
    default:
  }
},
```

[Events](#events) lists them.

<Note>
`onEvent` must not block and must not throw. Do slow work in
`onRunFinished`. A throw quarantines the reporter for the rest of the run and
prints one line on stderr naming the reporter, the event type, and the error.
The run's outcome is unchanged.
</Note>

#### `onOutput`

Receives what your code prints, as it prints it, redacted: a test's
output, and what the runner process prints while the run is underway (a test
file while it loads, a test filter, other reporters).

```ts
onOutput({ stream, text, target, pair }) {
  socket.send(JSON.stringify({ source: target === undefined ? 'runner' : pair?.testId, stream, text }));
},
```

```ts
interface ReporterOutput {
  readonly stream: 'stdout' | 'stderr';
  readonly text: string;   // one write, which may end mid-line
  readonly target?: string; // the target of a test's output; absent for the runner's
  readonly pair?: { testId: string; agent: string; repeat: number }; // the test running then
}
```

- Unless a reporter that [prints to the terminal](#printsto) has
  `onOutput`, as `list` and `dot` do, the runner also prints output and run errors
  to the terminal as written. A reporter that only records output never
  silences the terminal.
- A reporter that prints to the terminal and has `onOutput` prints run
  errors too: handle the `run-error` [event](#events), or a run that stops
  early, such as on `NO_TESTS`, prints nothing.
- Once its `onOutput` throws or rejects, the runner prints output and run
  errors itself for the rest of the run.
- A test's output is also an `output` [event](#events).
- What a reporter prints from inside `onOutput`, or from work it starts
  there, goes to the terminal as written, never back to `onOutput`.

#### `onStepPrompt`

Receives the [`--step`](https://e2e.com/docs/debugging#step-through-a-test) prompt to show on
the terminal, or `undefined` to take it down. `--step` in the background
answers each prompt over its socket instead and calls no reporter.

Each held step has an `attachId`. Use it to
[attach over MCP](https://e2e.com/docs/reference/mcp#attaching-to-a-held-test). The ID stays
the same across holds of the attempt.

```ts
onStepPrompt(prompt) {
  overlay.show(prompt === undefined ? '' : `Step ${prompt.steps[0].number}: ${prompt.steps[0].step.label}`);
},
```

Unless a reporter that [prints to the terminal](#printsto) has it, the
prompt also prints on stderr as one line. So does every prompt after that
reporter's `onStepPrompt` throws or rejects, the one the run waits on
included.

#### `reportFiles`

Returns the files to write for the finished run. The runner writes each one
atomically, creating its directory.

```ts
reportFiles: (run) => [{ path: 'reports/status.txt', content: run.report.run.status, label: 'Status' }],
```

```ts
interface ReportFile {
  readonly path: string;    // absolute, or from the project root
  readonly content: string;
  readonly label?: string;  // the summary row's label; its text is the path
  readonly note?: string;   // printed after the path, such as `(one file, 2.1 MB)`
}
```

- It has the same one-minute deadline and `signal` as `onRunFinished`, but a
  second Ctrl-C never stops it. A file from the previous run is never left
  beside the new report.
- A file at `report.json`'s path, a file that can't be written, or a return
  value that isn't a list of files is one line on stderr.

#### `onRunFinished`

Runs once the report and every report file are written and the terminal
summary prints, with the finished run and an `AbortSignal`.

```ts
async onRunFinished(run, signal) {
  await fetch('https://example.test/runs', { method: 'POST', body: JSON.stringify(run.report), signal });
  return [{ label: 'Results', text: 'https://example.test/runs/0192c' }];
},
```

```ts
interface FinishedRun {
  readonly report: Report;                 // the report-1 document, as written
  readonly status: RunStatus;              // report.run.status
  readonly exitCode: RunExitCode;
  readonly projectRoot: string;            // what the terminal shows paths relative to
  readonly reportPath: string | undefined; // absent when the run stopped before its tests or the write failed
  readonly outputDir: string;              // the output directory, .e2e by default
  readonly artifactsRoot: string;          // what the report's artifact paths are relative to
  readonly aiTracePath: string | undefined;
  readonly traces: ReadonlyMap<string, string>;      // result id -> its trace page, from the project root
  readonly lastRun?: Report;               // with --last-failed, the report the rerun selected from
  redact(text: string): string;            // masks the config's fixed secret values (not provider-resolved ones) in text from outside the report
}

type ReporterSummary = readonly { label: string; text: string }[];
```

- All reporters run concurrently, each with a one-minute deadline.
- A timeout, exception, or invalid return value is reported on stderr. The
  run's status, exit code, and report do not change.
- One Ctrl-C still lets reporters finish. A second Ctrl-C stops waiting for
  them, except those that set [`printsTo`](#printsto).
- `signal` aborts when the budget runs out or the run is forced to stop.
- The runner writes the trace pages, `results/<test>/trace.md`, before it
  calls `onRunFinished`.

<Note>
Hand `signal` to every request and timer. The CLI exits without waiting for
a reporter it abandoned, cutting off what it still does; under
[`e2e/runner`](https://e2e.com/docs/reference/runner), that work keeps your process alive.
</Note>

##### Summary rows

The rows a reporter resolves with, and the rows of its labeled report files,
reach every [`onSummary`](#onsummary). `list` and `dot` print them under
their summary, in the same layout as their own rows. The `json` reporter
does not carry them.

```
   Test Files  2 passed (2)
        Tests  6 passed (6)
     Start at  14:02:11
     Duration  8.41s

        JUnit  .e2e/junit.xml
      Results  https://example.test/runs/0192c…
```

##### Artifacts

- Artifact paths in the report are POSIX paths relative to `artifactsRoot`.
- `path`, `size`, and `sha256` are optional: an artifact whose file never
  appeared, or that a redaction withheld, is recorded without them. Check for
  `path` before reading.
- A video a hosted service keeps has an `http(s)` `url` in place of `path`.

##### Reruns with `--last-failed`

- The rerun's own report lists the tests it left out as unselected. A
  reporter that keeps one place current, the way `@e2e-dev/github` keeps a
  pull request comment, folds the rerun into `lastRun` to show both runs as
  one.
- A test the rerun owed but another filter left out is in the rerun's
  `run.carried`. It holds the test's last result, the serial group its
  attempts live on, and the `beforeAll` or `afterAll` failure whose scope
  holds it, from whichever earlier run reported them.
- A fold shows the carried result in place of the unselected one and counts
  a carried failure or hook error against the outcome.
- The artifacts both reports name are on disk under `artifactsRoot`.

<a id="test-filters" />
##### Test filters

- A test a [test filter](https://e2e.com/docs/filters) left out is an unselected result with
  `skip.cause` `filtered` and `skip.filter` naming the filter.
- `run.filters` holds one record per filter that was called, in order:
  `name`, `candidates`, `excluded` (the tests left out once serial groups
  took back their members), `note` (cut to 1024 characters; for a filter
  that failed or timed out, the warning saying why), and `outcome`, set
  when the filter left nothing out: `failed` when it threw or returned an
  invalid result, `timed-out` when it ran past 5 minutes. A filter left with
  no tests is not called and has no record.
- Once the filters have decided, `run.changes` holds the change they
  judged, by counts: `base` (the merge base), `files`, and `skipped` (why
  no filter ran, such as `no files changed since abc1234`). It is present when filters are configured and
  the run passed `--changed-since`, except under `e2e explore`, on
  `--watch` reruns, and when the run ends before the filters decide. On
  `--last-failed`, or with no tests to judge, it holds `skipped` alone.
- A failure while the filters decide, such as `INVALID_CHANGED_SINCE` for a
  ref that names no commit, is in `run.errors` with `phase` `filter`. A
  malformed `changedSince` has `phase` `config`.

#### `onSummary`

Receives the summary rows of every reporter, the built-ins first, then the
others in `reporters` order: each labeled report file's, then what its
`onRunFinished` returned.

```ts
onSummary(rows) {
  for (const row of rows) console.log(`${row.label}: ${row.text}`);
},
```

It runs last, once every `onRunFinished` is done or given up on, and also
after a second Ctrl-C.

## Events

`onEvent` receives one of these facts. Each event also has a sequence
number, `seq`, and an ISO timestamp, `at`.

```ts
type RunEventFact =
  | { type: 'run-started'; runId; projectId; projectRoot; artifactsRoot; ci; targets; agents?; model?; judge?; stepping? }
  | { type: 'plan'; total; files: { file; target; tests }[] }
  | { type: 'notice'; target; message }
  | { type: 'output'; target; pair; stream: 'stdout' | 'stderr'; text }
  | { type: 'setup'; step: SetupStep; state: 'started' }
  | { type: 'setup'; step: SetupStep; state: 'finished'; durationMs; outcome?: 'reused' | 'failed' | 'timed-out' }
  | { type: 'run-hold'; heldMs: number; heldSince: number | null }
  | { type: 'test-started'; testId; agent; repeat; title; file; serialId; target }
  | { type: 'step'; testId; agent; repeat; target; progress: StepProgress }
  | { type: 'test-finished'; result: RunEventResult }
  | { type: 'serial-group'; group: SerialGroupRecord }
  | { type: 'explore'; progress: ExploreProgress }
  | { type: 'run-error'; error: SerializedError }
  | { type: 'run-interrupted'; mode: 'graceful' | 'forced' }
  | { type: 'run-stopped'; failures; limit }
  | { type: 'run-finished'; status; exitCode; durationMs?; reportPath?; aiTracePath?; traces? };
```

- `run-started` comes first and `run-finished` last.
- `targets` on `run-started` names the targets the run selected with
  `--target`, in config order, or every configured target without it or
  when `--target` names an unknown target, which fails the run with
  `UNKNOWN_TARGET`. The report's `run.targets` still lists every configured
  target.
- `judge` on `run-started` is the run agent's judge model, present only when
  judgments use a model other than `model`. `stepping` is `true` when the
  run holds each step for `--step`.
- `setup` brackets the work before the tests start. Its `step.kind` is
  `collect`, `filter` (one [test filter](https://e2e.com/docs/filters), by its `name`),
  `prepare`, `service`, or `app`. An `app` step's `url` is the URL its
  readiness probe polls, with a free port filled in and no userinfo or query. `outcome` is `reused`
  when a service or app command attached to a process already serving its
  URL, `failed` when
  a filter threw or returned an invalid result, and `timed-out` when a
  filter ran past 5 minutes.
- A `notice` names what its line is about in `target`: a target, `app`,
  `collect`, `filter` for a test filter's progress and summary, or `run`.
- `output` is one write a test made to stdout or stderr; `pair` names the
  test running at the time and is undefined between tests.
- `run-hold` is emitted at the start and end of each interval with every
  running worker held.
  `heldMs` is the total time in milliseconds across completed intervals when
  every running worker was held.
  `heldSince` is the current interval's start in Unix milliseconds, or `null`
  when no such interval is open.
- `durationMs` on `run-finished` matches the report's `run.durationMs`.
- `test-finished` carries the full result record, including every attempt's
  artifacts.
- `explore` appears only in an `e2e explore` run: `started`, `planning`,
  `step-started`, `step-finished`, `finding`, and `finished`. The record of
  all of it is `run.explore` in the report.
- New event types are added over time. Handle the types you know and ignore
  the rest; leave the `default` branch of a `switch` empty.

### Tests and attempts

- A test pinned to several agents starts and finishes once per agent, so key
  running state by test id, target, and agent together.
- Ordinary tests emit `test-started` once for that combination. Serial
  members emit it on each group attempt they execute.
- Use step progress [identity](#step-progress) to distinguish retries.
- An attempt that fails before any step emits no step progress and appears
  in the final result.

<Note>
Secrets are redacted before events are built. Error messages and skip
reasons are only stripped of ANSI escapes and control characters other than
tab, newline, and the `\r` of a `\r\n` line break, so treat them as untrusted.
</Note>

### Step progress

The `phase` field describes step progress:

- `start` and `end` mark the step's boundaries.
- `event` reports a completed model turn, tool call, or observation.
- `activity` reports work starting: `observe`, `action`, or `model`.
- `replay` reports when replay from the cache starts or returns control to
  the agent.

```ts
type StepProgress = (
  | { phase: 'start'; kind: StepKind; api: string; label: string }
  | {
      phase: 'end';
      kind: StepKind;
      api: string;
      label: string;
      status: 'passed' | 'failed' | 'blocked' | 'timed-out' | 'cancelled';
      durationMs: number;
      modelCalls: number;
      error?: SerializedError;
      explanation?: string;
    }
  | { phase: 'event'; api: string; event: StepEvent }
  | { phase: 'activity'; api: string; activity: 'observe' | 'model' | 'action' }
  | { phase: 'replay'; api: string; active: boolean }
) & { identity?: StepProgressIdentity };
```

An `end` phase's `error` and `explanation` are redacted. Keep its `status`,
including `blocked` and `cancelled`. Do not treat every non-passed step as a
product failure.

Every step phase the runner emits includes `progress.identity`:

```ts
{ attemptId: string; attemptIndex: number; stepId: string; stepIndex: number; actor?: string }
```

- The IDs match the final report. Both indexes start at zero.
- A retry has a new attempt ID and a higher attempt index; its step indexes
  start again at zero.
- Serial-group members share the group's attempt ID and index. Each
  member's step IDs stay distinct.
- Use `stepId` to match start, activity, event, replay, and end phases,
  including nested steps.
- `actor` names the session a step ran on when it is not the test's own: one
  the test opened with [`launch()`](https://e2e.com/docs/core#open-a-host-inside-a-test).
- `identity` is optional in the type so a reporter can also accept older
  streams.

## What `--reporter` does to reporter objects

`--reporter` replaces only the built-in reporters; your own reporters and
those of packages still run. A built-in the flag names keeps the options the
config gave it.

<CodeGroup>
```bash npm
npx e2e run --reporter list,junit
```

```bash pnpm
pnpm exec e2e run --reporter list,junit
```

```bash bun
bunx e2e run --reporter list,junit
```
</CodeGroup>

- With `reporters: ['list', junit({ outputFile: 'reports/junit.xml' })]`,
  `--reporter junit` runs that `junit` alone, still writing
  `reports/junit.xml`.
- A config with no reporter that prints to the terminal with
  [`onOutput`](#onoutput) has no run view. Run errors still print on
  stderr, each as `CODE: message`.

## Where a reporter runs

Hooks run in the runner process. Workers also load the config, so
reporter construction must have no side effects. `--watch` hands one
reporter every run, each starting with its first event.

- Read tokens and start requests inside handlers.
- Adding a reporter leaves [cached traces](https://e2e.com/docs/cache#what-must-match) valid.

## Types

`Reporter`, `FinishedRun`, `ReportFile`, `ReporterOutput`, `ReporterSummary`, `StepPrompt`,
`Report`, `RunEvent`, and `RunEventOf` are exported from the main
entrypoint, and so is `renderMarkdownReport(report, options)`. `e2e/reporters`
exports `list`, `dot`, `json`, `junit`, and `markdown`, with
`ListReporterOptions`, `DotReporterOptions`, `JunitReporterOptions`, and
`MarkdownReporterOptions`.

## Related

[Pull request comments](https://e2e.com/docs/github) sets up `@e2e-dev/github`. The
[CLI reference](https://e2e.com/docs/reference/cli#output) lists what the built-in reporters write.
