---
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
---

# 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

{% 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` **Example:** `ruby`
{% /dd %}

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

{% dd %}
Test framework. **CLI flag:** `--framework` **Default:** `rspec` **Example:** `rspec`, `minitest`
{% /dd %}

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

{% dd %}
Overrides the default test command. `ddtest` appends selected test files and framework-specific flags to the command. For more information, see Custom test commands. **CLI flag:** `--command` **Default:** Empty **Example:** `bundle exec rspec --profile`
{% /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_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 and `test/**/*_test.rb` for Minitest. **CLI flag:** `--tests-location` **Default:** Framework default **Example:** `custom/spec/**/*_spec.rb`
{% /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` **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.

The optimal parallelism value is determined by the following criteria (in decreasing priority):

- The lowest expected wall-clock time
- The smallest imbalance between nodes or workers
- The smallest number of nodes or 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.

## Custom test commands{% #custom-test-commands %}

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.

## 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.

## 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)