Skip to content

Record, replay and rerun

0.9.123

Experimental: This feature is not yet stable

  • Enable with: Add [experimental] with record = true to ~/.config/nextest/config.toml, or set NEXTEST_EXPERIMENTAL_RECORD=1 in the environment
  • Tracking issue: TBD

Nextest supports recording test runs to rerun failing tests and to replay them later. Recorded runs are stored locally in the system cache. By default, recordings are retained for up to 30 days, 100 runs, or 1 GB of compressed data per workspace; see Managing recorded runs for details.

Recordings can also be exported from CI as portable archives, and visualized as Perfetto traces. For a full list of what you can do with recordings, see Learn more below.

Recorded test runs capture:

  • Test statuses (pass, fail, etc) and durations.
  • Outputs for all tests, both failing and successful. (If --no-capture is passed in at the time the run is recorded, test output cannot be captured.)

Setting up run recording

Run recording can be enabled locally or in CI.

Enabling run recording locally

To enable recording in user configuration:

Enabling recording in ~/.config/nextest/config.toml
[experimental]
record = true

[record]
enabled = true

Now, all future cargo nextest run instances will automatically be recorded.

Enabling run recording in GitHub Actions

For GitHub Actions, the following recipe sets up recording, then uploads the resulting portable recording as a workflow artifact:

# Set up recording for the local nextest run.
- name: Create recording user config
  shell: bash
  run: |
    mkdir -p "$RUNNER_TEMP/nextest-config"
    printf '[experimental]\nrecord = true\n\n[record]\nenabled = true\n' \
      > "$RUNNER_TEMP/nextest-config/config.toml"
    cat "$RUNNER_TEMP/nextest-config/config.toml"

- name: Run tests
  shell: bash
  run: cargo nextest run --profile ci --user-config-file "$RUNNER_TEMP/nextest-config/config.toml"

- name: Create portable archive from recorded run
  # Run this step even if the test step fails.
  if: "!cancelled()"
  shell: bash
  run: |
    cargo nextest store export latest \
      --user-config-file "$RUNNER_TEMP/nextest-config/config.toml" \
      --archive-file "$RUNNER_TEMP/nextest-run-archive.zip"

- name: Upload portable recording
  # Run this step even if the test step fails.
  if: "!cancelled()"
  uses: actions/upload-artifact@v7.0.0
  with:
    path: ${{ runner.temp }}/nextest-run-archive.zip
    archive: false

Enabling run recording in other CI systems

Follow this general pattern:

#!/usr/bin/env bash

set -euo pipefail

# Create a user config which enables recording.
mkdir -p "$TMPDIR/nextest-config"
printf '[experimental]\nrecord = true\n\n[record]\nenabled = true\n' \
  > "$TMPDIR/nextest-config/config.toml"
cat "$TMPDIR/nextest-config/config.toml"

# Run tests with this user config file. Save the exit code so the
# recording is exported even if tests fail.
NEXTEST_EXIT=0
cargo nextest run --profile ci \
  --user-config-file "$TMPDIR/nextest-config/config.toml" \
  || NEXTEST_EXIT=$?

# Export the recording.
cargo nextest store export latest \
  --user-config-file "$TMPDIR/nextest-config/config.toml" \
  --archive-file "$TMPDIR/nextest-run-archive.zip"

# Post-process or upload $TMPDIR/nextest-run-archive.zip as supported
# by your CI system, then exit with the original test exit code.
exit "$NEXTEST_EXIT"

Learn more

Configuration options

Retention limits can be changed through user configuration. For a full list, see Record configuration.