Skip to navigation
Test your docsUI proceduresRecording

Record video automatically

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.

Before you begin

Make sure you have the following:

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, or let Doc Detective detect them from prose.

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
{
  "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:

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, the config schema, and 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.
  • 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.

What’s next