Environment variables

Most ddtest settings can be passed as a CLI flag or as an environment variable. CLI flags take precedence over environment variables.

DD_TEST_OPTIMIZATION_RUNNER_PLATFORM

Programming language.
CLI flag: --platform
Default: ruby
Supported values: ruby, python, javascript

DD_TEST_OPTIMIZATION_RUNNER_FRAMEWORK

Test framework.
CLI flag: --framework
Default: rspec
Supported values: rspec, minitest, pytest, jest

DD_TEST_OPTIMIZATION_RUNNER_COMMAND

Overrides the default test command for Ruby and JavaScript. ddtest appends selected test files and framework-specific flags to the command. For pytest, use PYTEST_ADDOPTS instead. For more information, see Custom test commands.
CLI flag: --command
Default: Empty
Example: bundle exec rspec --profile, pnpm jest --runInBand

DD_TEST_OPTIMIZATION_RUNNER_MIN_PARALLELISM

Minimum CI node or worker count ddtest considers when planning.
CLI flag: --min-parallelism
Default: Physical CPU count
Example: 1

DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM

Maximum CI node or worker count ddtest considers when planning.
CLI flag: --max-parallelism
Default: Physical CPU count
Example: 8

DD_TEST_OPTIMIZATION_RUNNER_CI_JOB_OVERHEAD

Estimated overhead of launching an additional CI node. The ddtest planner adds another CI node only if that node reduces wall-clock time by at least this value.
See Parallelism selection to learn more.
CLI flag: --ci-job-overhead
Default: 25s
Example: 25s, 45s, 1m, 1500ms, 0s

DD_TEST_OPTIMIZATION_RUNNER_TARGET_TIME

Target wall time for the selected split. ddtest first considers splits at or below this wall time. If no split can meet the target within the configured parallelism range, ddtest selects the split with the lowest expected wall time. See Parallelism selection to learn more.
CLI flag: --target-time
Default: 0s
Example: 10m, 300s, 1500ms, 0s

DD_TEST_OPTIMIZATION_RUNNER_CI_NODE

Runs only the files assigned to CI node N, where N is zero-indexed.
CLI flag: --ci-node
Default: -1
Example: 0

DD_TEST_OPTIMIZATION_RUNNER_CI_NODE_WORKERS

Number of workers to start on this CI node. Use a positive integer or ncpu to use all physical CPUs available.
CLI flag: --ci-node-workers
Default: 1
Example: 2, ncpu

DD_TEST_OPTIMIZATION_RUNNER_WORKER_ENV

Sets environment variables for each worker process. Use {{nodeIndex}} and {{workerIndex}} placeholders to give each worker a unique value. For more information, see Worker environment variables.
CLI flag: --worker-env
Default: Empty
Example: DB_NAME=testdb{{nodeIndex}}_{{workerIndex}};FIXTURE=fixture{{nodeIndex}}

DD_TEST_OPTIMIZATION_RUNNER_TESTS_LOCATION

Glob pattern used to discover test files. Defaults to spec/**/*_spec.rb for RSpec, test/**/*_test.rb for Minitest, pytest configuration (testpaths and python_files) or **/{test_*,*_test}.py for pytest, and Jest configuration or Jests’s default test matching.
CLI flag: --tests-location
Alias: KNAPSACK_PRO_TEST_FILE_PATTERN
Default: Framework default
Example: custom/spec/**/*_spec.rb, tests/**/*_test.py, packages/**/__tests__/**/*.test.ts

DD_TEST_OPTIMIZATION_RUNNER_TESTS_EXCLUDE_PATTERN

Glob pattern used to exclude test files from discovery.
CLI flag: --tests-exclude-pattern
Alias: KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN
Default: Empty
Example: spec/system/**/*_spec.rb

DD_TEST_OPTIMIZATION_RUNNER_TEST_DISCOVERY_CACHE

Path to a restored test discovery cache file. ddtest imports it before planning and refreshes the internal discovery cache after successful full discovery.
CLI flag: --test-discovery-cache
Default: Empty
Example: .ddtest-cache/tests-discovery.json

DD_TESTOPTIMIZATION_TIA_TEST_SKIPPING_MODE

Controls whether Test Impact Analysis skipping uses test-level or suite-level granularity for Ruby. Invalid values fall back to test.
CLI flag: --test-skipping-mode
Default: test
Supported values: test, suite

DD_TEST_OPTIMIZATION_RUNNER_FORCE_FULL_TEST_DISCOVERY

Forces full test discovery when the framework supports it, including in suite-level skipping mode.
CLI flag: --force-full-test-discovery
Default: false
Supported values: true, false

DD_TEST_OPTIMIZATION_RUNNER_STRICT_DISCOVERY

Fails planning when full test discovery errors out. If full discovery is canceled (for example, by a timeout), ddtest still falls back to fast test file discovery instead of failing.
CLI flag: --strict-discovery
Default: false
Example: true

DD_TEST_OPTIMIZATION_RUNNER_RUNTIME_TAGS

JSON string that overrides runtime tags used to fetch skippable tests. Use this when ddtest runs outside the CI environment used to calculate skippable tests.
CLI flag: --runtime-tags
Alias: DD_TEST_OPTIMIZATION_RUNTIME_TAGS
Default: Empty
Example: {"os.platform":"linux","os.version":"7.8.9","runtime.name":"ruby","runtime.version":"3.3.0"}

DD_TEST_OPTIMIZATION_RUNNER_REPORT_ENABLED

Controls whether ddtest prints human-readable reports after command execution. This setting is only available as an environment variable.
CLI flag: None
Default: true
Example: false

Parallelism selection

ddtest plan estimates how long each runnable test file takes, then evaluates every parallelism value between --min-parallelism and --max-parallelism.

In CI-node mode, this value is the CI node count. On a single CI node, this value is the worker count.

Duration estimates come from Datadog test suite p50 timings when available and fall back to local discovery weights otherwise. Each candidate count is scored as expected slowest-worker time plus the node count multiplied by --ci-job-overhead.

When scores tie, ddtest prefers fewer CI nodes or workers, then lower expected wall time, then lower imbalance between workers.

ddtest uses the --ci-job-overhead setting to avoid always selecting the maximum number of CI nodes. With the default value of 25s, ddtest adds another CI node only when that node is expected to save at least 25 seconds of wall-clock time.

Increase --ci-job-overhead to use fewer CI nodes. Decrease it to prefer faster wall-clock time. Use duration values such as 25s, 1m, or 1500ms. Set 0s to always fan out test execution to --max-parallelism nodes.

Set --target-time to make ddtest first evaluate splits at or below that target. Use duration values such as 10m, 300s, or 1500ms. The default value, 0s, disables the target.

If no split can meet the target, ddtest logs a warning. It selects the split with the lowest expected wall time, ignoring CI job overhead.

Custom test commands

For Ruby frameworks and Jest, use --command to override the default test command:

bin/ddtest run --platform ruby --framework rspec --command "bin/integration-tests"

When using --command, do not include test files in the command. ddtest appends test files and framework-specific flags to the command.

Do not include the -- separator in --command. If the command contains --, ddtest emits a warning and removes the separator and everything after it.

For pytest, ddtest runs python -m pytest and appends selected test files. Use PYTEST_ADDOPTS to pass additional pytest flags. ddtest appends --ddtrace to PYTEST_ADDOPTS automatically so the ddtrace pytest plugin loads without changing your pytest config.

For Jest, ddtest prepends -r dd-trace/ci/init to NODE_OPTIONS for worker processes unless it is already present, so the dd-trace package must be installed in the project where ddtest runs.

Pytest test discovery

For pytest, ddtest discovers test files using this priority:

1. --tests-location when set.
2. Pytest configuration from pytest.ini, pyproject.toml, tox.ini, or setup.cfg, using testpaths and python_files.
3. The built-in pattern **/{test_*,*_test}.py.

Pytest does not have an equivalent to RSpec’s pattern flag, so ddtest resolves the pattern to explicit file paths before invoking python -m pytest.

Jest test discovery and instrumentation

For Jest, ddtest discovers test files with Jest’s own --listTests command. It uses this priority:

1. --command when set, with --listTests appended.
2. The local executable node_modules/.bin/jest when present.
3. npx jest.

Jest uses its own configuration and default test matching for --listTests. When --tests-location is set, ddtest filters the file list returned by Jest after discovery. It does not pass --tests-location as Jest’s --testMatch.

Jest support uses suite-level Test Impact Analysis. ddtest works with test files and suites, not individual Jest tests, and executes selected files with --runTestsByPath.

During execution, ddtest prepends -r dd-trace/ci/init to NODE_OPTIONS for worker processes unless NODE_OPTIONS already loads dd-trace/ci/init.

Worker environment variables

Use --worker-env to set environment variables for each worker. The value supports the {{nodeIndex}} and {{workerIndex}} placeholders.

{{nodeIndex}}

The CI node index from --ci-node or DD_TEST_OPTIMIZATION_RUNNER_CI_NODE. In single-node runs, the value is 0.

{{workerIndex}}

The worker process index within the current CI node, starting at 0.

The format is ENV=value. Separate multiple values with ;.

For example, assign each worker its own test database:

bin/ddtest run \
  --platform ruby \
  --framework rspec \
  --worker-env "DB_NAME=testdb{{nodeIndex}}_{{workerIndex}}"

ddtest automatically sets DD_TEST_SESSION_NAME for each worker to <DD_SERVICE>-node-<nodeIndex>-worker-<workerIndex> when the variable is not set. If you set DD_TEST_SESSION_NAME, ddtest preserves it and expands the same placeholders before starting each worker.

Stabilize runtime tags

Test Impact Analysis skippable tests are scoped by runtime tags such as OS, architecture, and Ruby version. If ddtest often reports that 0 tests are skipped, check whether runtime tags vary across CI runners. For example, AWS runners can report different os.version values across jobs.

To make matching stable, set fixed runtime tags in the environment used by both ddtest and worker processes:

export DD_TEST_OPTIMIZATION_RUNTIME_TAGS='{"os.architecture":"x86_64","os.platform":"linux","os.version":"6.8.0-aws","runtime.name":"ruby","runtime.version":"3.3.0"}'
ddtest run

ddtest also accepts the runner-specific DD_TEST_OPTIMIZATION_RUNNER_RUNTIME_TAGS environment variable and the --runtime-tags CLI flag.

Plan artifacts

ddtest plan writes a .testoptimization/ directory in the current working directory. Copy this directory from the planning job to every CI job that runs ddtest run or consumes ddtest plan file lists.

Most integrations should treat .testoptimization/ as a generated artifact. The stable files for external consumers are:

Files under .testoptimization/runner/cache/, .testoptimization/tests-discovery/, and .testoptimization/cache/http/*.json are implementation details. Use them only for troubleshooting.

Further reading

お役に立つドキュメント、リンクや記事:

Set up Test ParallelizationDOCUMENTATION Troubleshooting Test ParallelizationDOCUMENTATION Test Parallelization Best PracticesDOCUMENTATION