> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.doc-detective.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.doc-detective.com/_mcp/server.

# Record video automatically

> Turn on autoRecord to record every driver-based context from start to finish.

Record every driver-based context end to end without adding explicit `record` steps. Automatic recording is useful for a video archive or for replaying exactly what happened when a test fails. New to recording? Start with [Record video](/docs/test-docs/record-video-guide).

## Before you begin

Make sure you have the following:

* [Doc Detective installed](/docs/get-started/installation).
* A directory where you can create a `.spec.json` file.
* A visible display, or, on Linux and in CI, the `ffmpeg` engine's Xvfb virtual display. Automatic recording uses the [`ffmpeg` engine](/docs/test-docs/record-video-guide#choose-a-recording-engine), which needs a display to capture (see [Docker and headless](/docs/ci/docker-and-headless)).

The steps in this guide work the same in every authoring style. Write them in a standalone `.spec.json`, [inline in a doc source file](/docs/test-docs/inline), or let Doc Detective [detect them from prose](/docs/test-docs/detected).

## Record video automatically

Turn on `autoRecord` to record every driver-based context from start to finish without explicit `record` steps. Doc Detective captures each context end to end, which is useful for a video archive or for replaying exactly what happened when a test fails.

Enable it at the config, spec, or test level. A test's setting overrides a spec's, which overrides the config's:

**`config.json`**

```json title="config.json"
{
  "autoRecord": true,
  "output": "./test-results"
}
```

The CLI flag does the same for a single run; use `--no-auto-record` to override a config file that enables it:

```bash
doc-detective --auto-record
```

Desktop contexts capture with the `ffmpeg` engine. Doc Detective saves each video on a stable path in the per-run artifact tree. The same context therefore lands on the same relative path in every run:

```
<output>/.doc-detective/runs/<runId>/specs/<specId>/tests/<testId>/contexts/<contextId>/recordings/<contextId>.mp4
```

An automatic recording coexists with any explicit `record` and `stopRecord` steps in the same context. An untargeted `stopRecord` never stops the automatic recording, so a stray `stopRecord: true` can't cut the full-context video short. On Linux, each runner records its own virtual display with Xvfb, so concurrent automatic recordings stay isolated. On Windows and macOS, concurrent automatic recordings share the same physical display and overlap. Doc Detective warns when a run records concurrently on those platforms.

For where the artifacts land, see [Automatic recordings](/docs/actions/record#automatic-recordings), the [`config`](/reference/schemas/config) schema, and [Reporters and artifacts](/docs/ci/reporters-and-artifacts).

## Verify it works

* An automatic recording saves per driver-based context, on a stable path in the per-run artifact tree.
* A headless run with no display skips the automatic recording. Run headed, or on Linux use the `ffmpeg` engine's Xvfb virtual display. See [Docker and headless](/docs/ci/docker-and-headless).
* On Windows and macOS, Doc Detective warns when a run records concurrently, because the recordings share the same physical display and overlap. See [Two concurrent recordings overlap on Windows or macOS](/docs/test-docs/record-video-guide#two-concurrent-recordings-overlap-on-windows-or-macos).

## What's next

* [Record video](/docs/test-docs/record-video-guide) to record a flow, stop it, and choose an engine.
* [Detect visual regressions with checkpoints](/docs/test-docs/video-visual-regression) to watch a recording for visual drift.
* [Narrate a recording with annotations](/docs/test-docs/narrate-recordings) that stay up across the flow.
* Follow the worked [recording example](/docs/test-docs/record-video) end to end.
* Look up automatic-recording fields in [Automatic recordings](/docs/actions/record#automatic-recordings) and the [`config`](/reference/schemas/config) schema.