---
title: Configure Test Parallelization
description: >-
  Configure Test Parallelization environment variables, parallelism selection,
  worker settings, and plan artifacts.
breadcrumbs: >-
  Docs > Test Optimization in Datadog > Test Parallelization > Configure Test
  Parallelization
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Configure Test Parallelization

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

{% callout %}
# Important note for users on the following Datadog sites: app.datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, app.datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com

{% callout %}
##### Join the Preview!

Test Parallelization is in Preview. Complete the form to request access.

[Request Access](https://www.datadoghq.com/product-preview/test-parallelization/)
{% /callout %}

{% /callout %}

## Environment variables{% #environment-variables %}

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

{% dl %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_PLATFORM`
{% /dt %}

{% dd %}
Programming language. **CLI flag:** `--platform` **Default:** `ruby` **Supported values:** `ruby`, `python`, `javascript`
{% /dd %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_FRAMEWORK`
{% /dt %}

{% dd %}
Test framework. **CLI flag:** `--framework` **Default:** `rspec` **Supported values:** `rspec`, `minitest`, `pytest`, `jest`
{% /dd %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_COMMAND`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_MIN_PARALLELISM`
{% /dt %}

{% dd %}
Minimum CI node or worker count `ddtest` considers when planning. **CLI flag:** `--min-parallelism` **Default:** Physical CPU count **Example:** `1`
{% /dd %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM`
{% /dt %}

{% dd %}
Maximum CI node or worker count `ddtest` considers when planning. **CLI flag:** `--max-parallelism` **Default:** Physical CPU count **Example:** `8`
{% /dd %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_CI_JOB_OVERHEAD`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_TARGET_TIME`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_CI_NODE`
{% /dt %}

{% dd %}
Runs only the files assigned to CI node `N`, where `N` is zero-indexed. **CLI flag:** `--ci-node` **Default:** `-1` **Example:** `0`
{% /dd %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_CI_NODE_WORKERS`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_WORKER_ENV`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_TESTS_LOCATION`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_TESTS_EXCLUDE_PATTERN`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_TEST_DISCOVERY_CACHE`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TESTOPTIMIZATION_TIA_TEST_SKIPPING_MODE`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_FORCE_FULL_TEST_DISCOVERY`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_STRICT_DISCOVERY`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_RUNTIME_TAGS`
{% /dt %}

{% dd %}
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 %}

{% dt %}
`DD_TEST_OPTIMIZATION_RUNNER_REPORT_ENABLED`
{% /dt %}

{% dd %}
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`
{% /dd %}

{% /dl %}

## Parallelism selection{% #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{% #custom-test-commands %}

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

```bash
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{% #pytest-test-discovery %}

For pytest, `ddtest` discovers test files using this priority:

1. `--tests-location` when set.
1. Pytest configuration from `pytest.ini`, `pyproject.toml`, `tox.ini`, or `setup.cfg`, using `testpaths` and `python_files`.
1. 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{% #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.
1. The local executable `node_modules/.bin/jest` when present.
1. `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{% #worker-environment-variables %}

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

{% dl %}

{% dt %}
`{{nodeIndex}}`
{% /dt %}

{% dd %}
The CI node index from `--ci-node` or `DD_TEST_OPTIMIZATION_RUNNER_CI_NODE`. In single-node runs, the value is `0`.
{% /dd %}

{% dt %}
`{{workerIndex}}`
{% /dt %}

{% dd %}
The worker process index within the current CI node, starting at `0`.
{% /dd %}

{% /dl %}

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

For example, assign each worker its own test database:

```bash
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{% #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:

```bash
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{% #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:

| File                                                | Description                                                                                    |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `.testoptimization/manifest.txt`                    | Plan layout version.                                                                           |
| `.testoptimization/runner/test-files.txt`           | Newline-delimited list of test files to run. Each file contains at least one non-skipped test. |
| `.testoptimization/runner/parallel-runners.txt`     | Selected CI node count or worker count.                                                        |
| `.testoptimization/runner/skippable-percentage.txt` | Percentage of test time skipped by Test Impact Analysis.                                       |
| `.testoptimization/runner/tests-split/runner-N`     | Newline-delimited list of files assigned to index `N`.                                         |
| `.testoptimization/github/config`                   | GitHub Actions matrix output, written when `ddtest` detects GitHub Actions.                    |

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

## Further reading{% #further-reading %}

- [Set up Test Parallelization](https://docs.datadoghq.com/tests/test_parallelization/setup.md)
- [Troubleshooting Test Parallelization](https://docs.datadoghq.com/tests/test_parallelization/troubleshooting.md)
- [Test Parallelization Best Practices](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md)