DDTest

DDTest helps you scale CI workloads down when Datadog Test Optimization skips tests: it plans how to run the remaining test files across CI nodes or local workers in the most efficient way.

Use ddtest plan once to create a reusable .testoptimization/ plan, then use ddtest run in each CI job to run only the files assigned to that job.

DDTest can also write file lists for another runner, such as Knapsack Pro or parallel_tests.

Currently supported: Ruby with RSpec or Minitest.

Prerequisites

Before using DDTest, you must have Datadog Test Optimization already set up and enabled with a Datadog Test Optimization library for your language and framework. DDTest relies on this integration to discover your tests and plan test execution accordingly.

Minimum supported library versions:

• Ruby requires the datadog-ci gem 1.31.0 or higher.

For instructions on setting up Test Optimization, see the Datadog Test Optimization documentation.

Usage

DDTest ships as a CLI tool ddtest with two primary sub-commands: plan and run.

Use plan to create a reusable .testoptimization/ plan without running tests. Use run to execute that plan locally or in CI. If a plan is missing, run will generate it on the fly.

DDTest is meant to run in CI. Local runs are possible when you want to reuse CI's skippable tests on your machine; see Running locally with CI skippable tests. For planning-step performance tips and framework-specific setup notes, see Best practices.

Available commands

ddtest plan

Creates a reusable execution plan under .testoptimization/ without running tests. The plan contains the runnable test files, the selected CI node or worker count, and any per-node file lists needed by ddtest run or another runner.

Example:

ddtest plan \
  --platform ruby \
  --framework rspec \
  --min-parallelism 8 \
  --max-parallelism 32

This prepares the plan and writes it to .testoptimization/ folder for later reuse. Copy .testoptimization/ to any CI job that runs ddtest run or reads DDTest's plan file lists. For the full file layout and formats, see Plan file layout.

ddtest run

Runs tests using the framework you specify. If .testoptimization/ exists, DDTest uses its precomputed plan; otherwise it first runs plan and then executes.

ddtest run --platform ruby --framework rspec

For CI-node mode, worker environment variables, custom commands, and parallelism details, see Running DDTest.

Common settings

CLI flag	What it does
--platform	Language/platform. Currently supported: ruby.
--framework	Test framework. Currently supported: rspec, minitest.
--command	Override the default test command used by the framework.
--min-parallelism	Minimum CI node or worker count DDTest considers when planning.
--max-parallelism	Maximum CI node or worker count DDTest considers when planning.
--ci-node	Run only the files assigned to CI node N.

For all flags, environment variables, and defaults, see Settings.

Installation

This project uses GitHub Releases for distribution.

Use gh command line tool to download the latest release in GitHub actions:

- name: Download ddtest binary
  run: |
    mkdir -p bin
    gh release download --repo DataDog/ddtest --pattern "ddtest-linux-amd64" --dir bin
    mv bin/ddtest-linux-amd64 bin/ddtest
    chmod +x bin/ddtest
  env:
    GH_TOKEN: ${{ github.token }}

...or use curl:

mkdir -p bin
curl -fsSL https://github.com/DataDog/ddtest/releases/latest/download/ddtest-linux-amd64 -o bin/ddtest
chmod +x bin/ddtest

The list of available precompiled artifacts is on release page.

CI configuration examples

• GitHub Actions
• CircleCI

More documentation

• Running DDTest
• Settings
• Plan file layout
• Third party test runners
• GitHub Actions example
• CircleCI example
• Rails discovery optimization
• Running locally with CI skippable tests and runtime tags
• DDTest 1.0 upgrade guide