# Recordings and evidence

> Record test sessions, open their reports and understand missing or withheld evidence.

Source: https://rehearsal.dev/retest/docs/guides/recordings-and-evidence

When a failure screenshot leaves you wondering what happened earlier, record the test session. The run folder keeps the video alongside screenshots, steps and results so you can review the sequence after the run ends.

## Prepare recording tools

Recording needs Retest's media process and ffmpeg. Install ffmpeg with your system's package manager, then run the command below to build the media process from source shipped with Retest.

> [!NOTE]
> **Build requirements**
>
> The media build needs matching `cargo` and `rustc` tools from Rust 1.88 or later. It supports macOS on Apple silicon and Linux x64; other platforms have no media build path. ffmpeg needs a supported encoder and container, which `retest doctor` checks when recording is configured.

```sh
npx retest install media
```

A run finds the installed media binary in Retest's checked cache. You can override it with `RETEST_MEDIA_BINARY`, or name ffmpeg with `RETEST_FFMPEG`. Runs never install these tools themselves, and a run without recording needs neither tool.

## Record a run

Recording is off by default. Enable it in `retest.config.ts`; there is no recording command-line flag. This config records the task app and keeps recordings from attempts that did not pass.

```ts filename="retest.config.ts"
import { chrome, defineConfig } from '@rehearsal-labs/retest'

export default defineConfig({
  apps: { web: chrome({ baseUrl: 'http://127.0.0.1:4173' }) },
  recording: {
    record: true,
    keep: 'failures',
    fps: 10,
    size: { width: 1280, height: 720 },
  },
})
```

Each recorded app gets a separate video for each attempt. Capture starts before its first action and ends after the final assertion and host check. `size` sets the video dimensions; configure the target's viewport separately.

```sh
npx retest doctor
npx retest run tests/tasks.retest.ts --reporter html
```

`record: true` selects every app whose pixel rules allow recording. Use `recording.apps` to override that choice per app, such as `apps: { web: false }` to leave the browser out. Choose `keep: 'all'`, the default, when you also need successful recordings.

## Open the report

The HTML reporter writes `report.html` in the run folder and also prints the terminal report. Open that file in a browser to read the steps and their evidence. Clicking a recorded step moves the video to that moment.

You can also build the report later from an existing folder. Use the folder path printed by the run:

```sh
npx retest report .retest/runs/<time>
```

The command reads saved events and results without running tests again. The report needs no server and loads nothing from the network. Keep the whole run folder when moving or sharing it because evidence links use relative paths.

## Understand evidence status

The test's outcome and its evidence status answer different questions. A test can pass its checks while its recording is incomplete. The report shows the missing evidence separately, with a reason for each gap.

| Evidence state | Meaning |
| --- | --- |
| `complete` | The requested recording has no known evidence gap. |
| `partial` | Some usable recording remains, but parts are missing or withheld. |
| `unavailable` | No requested recording could be completed as a usable video. |
| `not_requested` | The attempt did not request a recording. |

To require complete evidence, add `required: true` inside `recording`. Missing or incomplete evidence then gives the run `evidence_incomplete` and exit 2, while each test keeps its observed outcome. If a test also failed its checks, exit 1 takes precedence.

Recordings sample the screen. Chrome supplies frames as the page paints, while Firefox and WebKit use repeated screenshots. Even a complete capture does not prove that nothing appeared between frames. For exact outcomes, keep assertions in the test.

## Find the evidence

The result and report link each artifact to its app and attempt. Screenshots, videos, comparison images and frames go under `artifacts/`; console and network records go under `diagnostics/`. The [run folder reference](https://rehearsal.dev/retest/docs/reference/run-folder.md) describes the files and event records.

When a test fails, Retest tries to capture each app's page, subject to the pixel policy and the app still being available. A missing screenshot has a recorded reason. Screenshot comparisons keep their own expected, actual and difference images, and AI checks keep the images they sent to their judge.

With `keep: 'failures'`, Retest removes a passed attempt's recordings and their thumbnails after the attempt finishes. Recordings used by an AI check remain. Screenshots, saved frames, diagnostics, downloads, reports and logs remain too, so that setting does not erase all evidence from passing tests.

## Control pixel capture

You can forbid screenshots or recordings separately for each app. Both are allowed by default; allowing recordings does not turn recording on.

```ts filename="retest.config.ts"
defineConfig({
  // Keep your apps and recording settings here.
  pixels: {
    web: { screenshots: 'allowed', recordings: 'never' },
  },
})
```

Add `pixels` to your existing config to keep screenshots while forbidding browser recordings. The screenshot rule also covers comparison images and images sent to AI checks. A capture forbidden by policy is not taken, and the run says why.

After browser secret entry sends input, screenshots and recording frames are withheld, including for password fields. Capture resumes when a new document opens or the session ends. Changing the path within the same document does not resume capture.

Native secret entry keeps pixels by default, relying on the platform's masking for secure fields. Set `recording: { nativeWithholding: true }` to withhold plain or unreadable native fields until Retest verifies that the secret is no longer shown. This also affects screenshots when recording is off.

> [!WARNING]
> **Text redaction does not protect images**
>
> An app can display a secret outside a withholding stretch, for example on the page after sign-in. That value can appear in an allowed image. Store and share run folders according to the data those images may contain.

## Platform support

Recording works on Chromium-family browsers, Firefox and WebKit. [iOS simulator apps](https://rehearsal.dev/retest/docs/platforms/ios.md), [macOS apps](https://rehearsal.dev/retest/docs/platforms/macos.md) and [Electron apps](https://rehearsal.dev/retest/docs/platforms/electron.md) explain their platform setup. Popups have no recording; recording their opener reports that missing capture as a gap.

If capture or media setup fails, read the recording's reason in the report and run `retest doctor` with the same config. An unfinished file named by `partialPath` has not been verified as playable; use a recording's `path` for a completed video.

## Next steps

- [Debugging a failure](https://rehearsal.dev/retest/docs/essentials/debugging.md): Use the failed check and its evidence to find the cause.
- [AI checks](https://rehearsal.dev/retest/docs/guides/ai-checks.md): Ask a judge about screenshots or recorded steps.
- [Run folder and events](https://rehearsal.dev/retest/docs/reference/run-folder.md): Read the saved files and recording records.