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

$ 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 #Link to 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.

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.

$ 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 #Link to 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:

$ 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 #Link to 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.

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

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.

Platform support #Link to Platform support

Recording works on Chromium-family browsers, Firefox and WebKit. iOS simulator apps, macOS apps and Electron apps 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 #Link to Next steps

• Debugging a failureUse the failed check and its evidence to find the cause.
• AI checksAsk a judge about screenshots or recorded steps.
• Run folder and eventsRead the saved files and recording records.