---
title: Set Up Test Parallelization
description: >-
  Select your CI provider, platform, and framework for a recommended Test
  Parallelization setup.
breadcrumbs: >-
  Docs > Test Optimization in Datadog > Test Parallelization > Set Up Test
  Parallelization
---

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

# Set Up 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 %}

## Overview{% #overview %}

Test Parallelization shortens CI test runs by splitting test files across CI nodes based on test durations from Test Optimization. This balances the workload so nodes finish at about the same time. With [Test Impact Analysis](https://docs.datadoghq.com/tests/test_impact_analysis.md), it also uses fewer CI nodes when fewer tests need to run.

This page uses the following terms:

- **CI node**: One execution environment, such as a GitHub Actions job.
- **Worker**: A test process started by `ddtest`. Each CI node runs one worker by default.
- **Plan**: The `.testoptimization/` directory that lists the selected test files, the parallelism, and which files go to each CI node.
Select your CI provider, platform, and test framework to see the recommended configuration for your suite.
## Prerequisites{% #prerequisites %}

- Confirm that your framework, runtime, and Datadog library meet the [Test Parallelization compatibility requirements](https://docs.datadoghq.com/tests/test_parallelization.md#compatibility).
- Set up [Test Optimization](https://docs.datadoghq.com/tests/setup.md) for the suite. Reuse its credentials, `DD_SITE`, `DD_SERVICE`, and instrumentation.
- Install Git and check out the repository.
- Use the same runtime, dependencies, configuration, environment, project directory, and source revision for planning and execution.

{% section displayed-if="Framework is not WebdriverIO" %}
This section only applies to users who meet the following criteria: Framework is not WebdriverIO

To skip unaffected tests, enable [Test Impact Analysis](https://docs.datadoghq.com/tests/test_impact_analysis.md) for the service.
{% /section %}

## Install ddtest{% #install-ddtest %}
Install `ddtest` v1.17.0 or later into `bin` in the planning and test environments. Use the same version in both; the CircleCI example transfers the binary from the planning job:
```
curl -fsSL https://github.com/DataDog/ddtest/releases/latest/download/install.sh | bash -s -- --dir bin
```

## Configure your CI jobs{% #configure-your-ci-jobs %}
`ddtest` reuses your existing framework configuration. Replace your existing test invocation with the configuration below. Keep services, fixtures, report uploads, and Test Optimization instrumentation. The examples assume that tests run from the repository root in a Bash shell.
{% section displayed-if="Platform is Ruby" %}
This section only applies to users who meet the following criteria: Platform is Ruby

Repeat your [Ruby Test Optimization setup](https://docs.datadoghq.com/tests/setup/ruby.md) in the planning job before `ddtest plan`, including the auto-instrumentation GitHub Action or CircleCI orb, if you use one. Test discovery needs the `datadog-ci` gem installed in the same Ruby and Bundler environment as the tests. Keep this setup in every test job too.
{% /section %}

{% section displayed-if="Platform is Python" %}
This section only applies to users who meet the following criteria: Platform is Python

Repeat your [Python Test Optimization setup](https://docs.datadoghq.com/tests/setup/python.md) in the planning job before `ddtest plan`, including the auto-instrumentation GitHub Action or CircleCI orb, if you use one. Full discovery needs `ddtrace` available in the environment used by pytest; `ddtest` enables its pytest plugin. Keep this setup in every test job too.
{% /section %}

{% section displayed-if="Platform is JavaScript" %}
This section only applies to users who meet the following criteria: Platform is JavaScript

JavaScript file discovery does not require auto-instrumentation, but planning needs a Datadog connection to retrieve settings, test durations, and Test Impact Analysis decisions. For Agentless mode, set `DD_API_KEY`, `DD_SITE`, and `DD_CIVISIBILITY_AGENTLESS_ENABLED=true` in every job that runs `ddtest`. For Agent-based setups, make the same Agent connection available to planning and test jobs.

Install the dependencies used by your test configuration and discovery hooks, including any Datadog SDK imports they contain. Keep your [JavaScript Test Optimization setup](https://docs.datadoghq.com/tests/setup/javascript.md) in every test job before `ddtest run`.
{% /section %}

{% section displayed-if="CI provider is Other - single node" %}
This section only applies to users who meet the following criteria: CI provider is Other - single node

Set `DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM` to the maximum number of local workers your CI node can support. See [parallelism tuning](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#choose-a-parallelism-budget).
{% /section %}

{% section displayed-if="not CI provider is Other - single node" %}
This section only applies to users who meet the following criteria: not CI provider is Other - single node

Set `DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM` to the maximum number of CI nodes in your budget. See [parallelism tuning](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#choose-a-parallelism-budget).
{% /section %}

{% section
   displayed-if="(CI provider is Github Actions) and (Platform is Ruby)" %}
This section only applies to users who meet the following criteria: (CI provider is Github Actions) and (Platform is Ruby)

Use `ruby/setup-ruby` with `bundler-cache: true` in both planning and test jobs to restore the same Ruby version and Bundler dependencies.
{% /section %}

{% section
   displayed-if="(CI provider is Github Actions) and (Platform is Python)" %}
This section only applies to users who meet the following criteria: (CI provider is Github Actions) and (Platform is Python)

Use `actions/setup-python` with `cache: pip` and your dependency file path in both jobs. Install dependencies after restoring the cache; a pip cache does not install packages.
{% /section %}

{% section
   displayed-if="(CI provider is Github Actions) and (Platform is JavaScript)" %}
This section only applies to users who meet the following criteria: (CI provider is Github Actions) and (Platform is JavaScript)

Use `actions/setup-node` with your Node.js version and package-manager cache in both jobs. For npm, set `cache: npm` and run `npm ci`; keep your existing installation command for pnpm or Yarn.
{% /section %}

{% section
   displayed-if="The selected value for CI provider is included in the given list: 'CircleCI, Other - multiple nodes, Other - single node'" %}
This section only applies to users who meet the following criteria: The selected value for CI provider is included in the given list: 'CircleCI, Other - multiple nodes, Other - single node'

Restore dependency caches and run your installation command before planning and execution. Key caches by runtime and dependency files.
{% /section %}
See [dependency caching](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#cache-project-dependencies) for cache examples.
{% section displayed-if="CI provider is Github Actions" %}
This section only applies to users who meet the following criteria: CI provider is Github Actions
Merge the workflow-level `env` settings and jobs into your workflow, keeping existing environment variables, job dependencies, and credentials. Keep credentials in GitHub secrets. Replace the setup comments with your runtime, dependency, instrumentation, and `ddtest` installation steps.
{% section
   displayed-if="The selected value for Platform is included in the given list: 'Ruby, Python'" %}
This section only applies to users who meet the following criteria: The selected value for Platform is included in the given list: 'Ruby, Python'

Set the `DD_API_KEY` repository secret and change `site` to your Datadog site. The action configures Test Optimization before planning and execution; retain any existing service and tracer settings.
{% /section %}

{% section
   displayed-if="The selected value for Platform is included in the given list: 'Ruby, Python'" %}
This section only applies to users who meet the following criteria: The selected value for Platform is included in the given list: 'Ruby, Python'

```
env:
  DD_TEST_OPTIMIZATION_RUNNER_PLATFORM: "rubypythonjavascript"
  DD_TEST_OPTIMIZATION_RUNNER_FRAMEWORK: "rspecminitestpytestjestvitestmochacucumbercypressplaywrightwebdriverio"
  DD_TEST_OPTIMIZATION_RUNNER_MIN_PARALLELISM: "1"
  DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM: "10"

jobs:
  dd_plan:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.plan.outputs.matrix }}
      has_tests: ${{ steps.plan.outputs.has_tests }}
    steps:
      - uses: actions/checkout@v4
      # Insert your runtime, dependencies, and ddtest install.
      - name: Configure Datadog Test Optimization
        uses: datadog/test-visibility-github-action@v3
        with:
          languages: "rubypython"
          api_key: ${{ secrets.DD_API_KEY }}
          site: datadoghq.com
      - id: plan
        name: Plan tests
        run: |
          rm -rf .testoptimization
          bin/ddtest plan          
      - uses: actions/upload-artifact@v4
        with:
          name: ddtest-plan
          path: .testoptimization/
          include-hidden-files: true
          if-no-files-found: error

  dd_test:
    needs: dd_plan
    if: ${{ needs.dd_plan.outputs.has_tests == 'true' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.dd_plan.outputs.matrix) }}
    steps:
      - uses: actions/checkout@v4
      # Insert matching runtime, dependencies, ddtest install, and required test services.
      - uses: actions/download-artifact@v4
        with:
          name: ddtest-plan
          path: .testoptimization/
      - name: Configure Datadog Test Optimization
        uses: datadog/test-visibility-github-action@v3
        with:
          languages: "rubypython"
          api_key: ${{ secrets.DD_API_KEY }}
          site: datadoghq.com
      - name: Run assigned tests
        run: |
          test -f .testoptimization/manifest.txt
          bin/ddtest run --ci-node ${{ matrix.ci_node_index }}          
      # Keep existing report and coverage upload steps.
```
{% /section %}

{% section displayed-if="Platform is JavaScript" %}
This section only applies to users who meet the following criteria: Platform is JavaScript

These examples use Agentless mode. Set the `DD_API_KEY` repository secret and change `DD_SITE` to your Datadog site.

```
env:
  DD_TEST_OPTIMIZATION_RUNNER_PLATFORM: "rubypythonjavascript"
  DD_TEST_OPTIMIZATION_RUNNER_FRAMEWORK: "rspecminitestpytestjestvitestmochacucumbercypressplaywrightwebdriverio"
  DD_TEST_OPTIMIZATION_RUNNER_MIN_PARALLELISM: "1"
  DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM: "10"

jobs:
  dd_plan:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.plan.outputs.matrix }}
      has_tests: ${{ steps.plan.outputs.has_tests }}
    steps:
      - uses: actions/checkout@v4
      # Insert your runtime, dependencies, and ddtest install.
      - id: plan
        name: Plan tests
        env:
          DD_API_KEY: ${{ secrets.DD_API_KEY }}
          DD_SITE: datadoghq.com
          DD_CIVISIBILITY_AGENTLESS_ENABLED: "true"
        run: |
          rm -rf .testoptimization
          bin/ddtest plan          
      - uses: actions/upload-artifact@v4
        with:
          name: ddtest-plan
          path: .testoptimization/
          include-hidden-files: true
          if-no-files-found: error

  dd_test:
    needs: dd_plan
    if: ${{ needs.dd_plan.outputs.has_tests == 'true' }}
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.dd_plan.outputs.matrix) }}
    steps:
      - uses: actions/checkout@v4
      # Insert matching runtime, dependencies, ddtest install, and required test services.
      # Keep your JavaScript Test Optimization instrumentation.
      - uses: actions/download-artifact@v4
        with:
          name: ddtest-plan
          path: .testoptimization/
      - name: Run assigned tests
        env:
          DD_API_KEY: ${{ secrets.DD_API_KEY }}
          DD_SITE: datadoghq.com
          DD_CIVISIBILITY_AGENTLESS_ENABLED: "true"
        run: |
          test -f .testoptimization/manifest.txt
          bin/ddtest run --ci-node ${{ matrix.ci_node_index }}          
      # Keep existing report and coverage upload steps.
```
{% /section %}

`ddtest plan` writes `matrix` and `has_tests` to `$GITHUB_OUTPUT`. The `if` condition on `dd_test` skips the test jobs when the plan has no tests to run. Each job downloads the same plan and runs its zero-based node index.

{% collapsible-section #suite-paths %}
#### Subdirectories and multiple suites

If your tests run from a subdirectory such as `backend/`:

- Set `working-directory: backend` on the shell steps that install `ddtest`, plan tests, and run tests.
- Set `path: backend/.testoptimization/` in both `actions/upload-artifact` and `actions/download-artifact`. These actions need their own paths, even when you set a default working directory for shell steps.

The upload step saves the plan as a GitHub Actions artifact named `ddtest-plan`. The download step uses the same `name: ddtest-plan` to retrieve it.

If one workflow creates several plans, give each plan a different name. For example, use `backend-plan` for backend tests and `frontend-plan` for frontend tests. Use the matching name in each plan's upload and download steps.

Use different plan names when testing with different Ruby or Python versions, too. Each test job must download the plan created for its environment.

For workflows with several suites, put each suite's `DD_TEST_OPTIMIZATION_RUNNER_*` settings under `env:` in its planning and test jobs. Avoid workflow-level settings that would apply to every suite.
{% /collapsible-section %}
{% /section %}

{% section displayed-if="CI provider is CircleCI" %}
This section only applies to users who meet the following criteria: CI provider is CircleCI
Enable [dynamic configuration](https://circleci.com/docs/guides/orchestrate/dynamic-config/) to pass the planned node count to a continuation workflow. Keep one setup workflow and continue immediately after planning. Extend an existing continuation if you have one; preserve its parameters, contexts, filters, and unrelated jobs. CircleCI allows one continuation per pipeline, within six hours of creation.
In `.circleci/config.yml`, retain your executor and setup steps. Use the same `environment` settings in both jobs and retain their existing variables. Keep credentials in CircleCI contexts or project settings. The `cimg/base` image below is a placeholder for the **existing test image** with the selected language runtime:

{% section
   displayed-if="The selected value for Platform is included in the given list: 'Ruby, Python'" %}
This section only applies to users who meet the following criteria: The selected value for Platform is included in the given list: 'Ruby, Python'

Set `DD_API_KEY` in a context available to both jobs or in the project settings, and change `site` to your Datadog site. Both configuration files declare the Test Optimization orb and call `autoinstrument` before `ddtest`. Retain any existing service and tracer settings.
{% /section %}

{% section
   displayed-if="The selected value for Platform is included in the given list: 'Ruby, Python'" %}
This section only applies to users who meet the following criteria: The selected value for Platform is included in the given list: 'Ruby, Python'

In the `.circleci/config.yml` file:

```
version: 2.1
setup: true

orbs:
  test-optimization-circleci-orb: datadog/test-optimization-circleci-orb@1
  continuation: circleci/continuation@2

jobs:
  dd_plan:
    docker:
      - image: cimg/base:stable # Replace with your existing test image.
    environment:
      DD_TEST_OPTIMIZATION_RUNNER_PLATFORM: "rubypythonjavascript"
      DD_TEST_OPTIMIZATION_RUNNER_FRAMEWORK: "rspecminitestpytestjestvitestmochacucumbercypressplaywrightwebdriverio"
      DD_TEST_OPTIMIZATION_RUNNER_MIN_PARALLELISM: "1"
      DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM: "10"
    steps:
      - checkout
      # Insert dependency caching, installation, and ddtest install.
      - test-optimization-circleci-orb/autoinstrument:
          languages: "rubypython"
          site: datadoghq.com
      - run:
          name: Plan tests
          command: |
            rm -rf .testoptimization
            bin/ddtest plan            
      - save_cache:
          key: ddtest-plan-v1-<< pipeline.id >>-tests
          paths:
            - .testoptimization
            - bin/ddtest
      - continuation/continue:
          configuration_path: .circleci/test-parallelization.yml
          parameters: .testoptimization/circleci/parameters.json

workflows:
  setup:
    jobs:
      - dd_plan # Keep the required contexts and filters.
```
{% /section %}

{% section displayed-if="Platform is JavaScript" %}
This section only applies to users who meet the following criteria: Platform is JavaScript

These examples use Agentless mode. Set `DD_API_KEY` in the project settings or a context available to both jobs, and change `DD_SITE` to your Datadog site.

In the `.circleci/config.yml` file:

```
version: 2.1
setup: true

orbs:
  continuation: circleci/continuation@2

jobs:
  dd_plan:
    docker:
      - image: cimg/base:stable # Replace with your existing test image.
    environment:
      DD_SITE: datadoghq.com
      DD_CIVISIBILITY_AGENTLESS_ENABLED: "true"
      DD_TEST_OPTIMIZATION_RUNNER_PLATFORM: "rubypythonjavascript"
      DD_TEST_OPTIMIZATION_RUNNER_FRAMEWORK: "rspecminitestpytestjestvitestmochacucumbercypressplaywrightwebdriverio"
      DD_TEST_OPTIMIZATION_RUNNER_MIN_PARALLELISM: "1"
      DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM: "10"
    steps:
      - checkout
      # Insert dependency caching, installation, and ddtest install.
      - run:
          name: Plan tests
          command: |
            rm -rf .testoptimization
            bin/ddtest plan            
      - save_cache:
          key: ddtest-plan-v1-<< pipeline.id >>-tests
          paths:
            - .testoptimization
            - bin/ddtest
      - continuation/continue:
          configuration_path: .circleci/test-parallelization.yml
          parameters: .testoptimization/circleci/parameters.json

workflows:
  setup:
    jobs:
      - dd_plan # Keep the required contexts and filters.
```
{% /section %}

In the continuation configuration:

{% section
   displayed-if="The selected value for Platform is included in the given list: 'Ruby, Python'" %}
This section only applies to users who meet the following criteria: The selected value for Platform is included in the given list: 'Ruby, Python'

In the `.circleci/test-parallelization.yml` file:

```
version: 2.1

parameters:
  parallelism:
    type: integer
    default: 1
  has_tests:
    type: boolean
    default: false

orbs:
  test-optimization-circleci-orb: datadog/test-optimization-circleci-orb@1

jobs:
  dd_test:
    parallelism: << pipeline.parameters.parallelism >>
    docker:
      - image: cimg/base:stable # Use the same test image as the planning job.
    environment:
      DD_TEST_OPTIMIZATION_RUNNER_PLATFORM: "rubypythonjavascript"
      DD_TEST_OPTIMIZATION_RUNNER_FRAMEWORK: "rspecminitestpytestjestvitestmochacucumbercypressplaywrightwebdriverio"
      DD_TEST_OPTIMIZATION_RUNNER_MIN_PARALLELISM: "1"
      DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM: "10"
    steps:
      - checkout
      # Insert matching dependency caching and installation.
      # Keep required test services and preparation.
      - restore_cache:
          keys:
            - ddtest-plan-v1-<< pipeline.id >>-tests
      - test-optimization-circleci-orb/autoinstrument:
          languages: "rubypython"
          site: datadoghq.com
      - run:
          name: Run assigned tests
          command: |
            test -f .testoptimization/manifest.txt
            test -f bin/ddtest
            chmod +x bin/ddtest
            bin/ddtest run --ci-node "$CIRCLE_NODE_INDEX"            
      # Keep existing report and coverage upload steps.

workflows:
  tests:
    when: << pipeline.parameters.has_tests >>
    jobs:
      - dd_test # Keep the required contexts, filters, and dependencies.
```
{% /section %}

{% section displayed-if="Platform is JavaScript" %}
This section only applies to users who meet the following criteria: Platform is JavaScript

In the `.circleci/test-parallelization.yml` file:

```
version: 2.1

parameters:
  parallelism:
    type: integer
    default: 1
  has_tests:
    type: boolean
    default: false

jobs:
  dd_test:
    parallelism: << pipeline.parameters.parallelism >>
    docker:
      - image: cimg/base:stable # Use the same test image as the planning job.
    environment:
      DD_SITE: datadoghq.com
      DD_CIVISIBILITY_AGENTLESS_ENABLED: "true"
      DD_TEST_OPTIMIZATION_RUNNER_PLATFORM: "rubypythonjavascript"
      DD_TEST_OPTIMIZATION_RUNNER_FRAMEWORK: "rspecminitestpytestjestvitestmochacucumbercypressplaywrightwebdriverio"
      DD_TEST_OPTIMIZATION_RUNNER_MIN_PARALLELISM: "1"
      DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM: "10"
    steps:
      - checkout
      # Insert matching dependency caching and installation.
      # Keep your JavaScript Test Optimization instrumentation.
      # Keep required test services and preparation.
      - restore_cache:
          keys:
            - ddtest-plan-v1-<< pipeline.id >>-tests
      - run:
          name: Run assigned tests
          command: |
            test -f .testoptimization/manifest.txt
            test -f bin/ddtest
            chmod +x bin/ddtest
            bin/ddtest run --ci-node "$CIRCLE_NODE_INDEX"            
      # Keep existing report and coverage upload steps.

workflows:
  tests:
    when: << pipeline.parameters.has_tests >>
    jobs:
      - dd_test # Keep the required contexts, filters, and dependencies.
```
{% /section %}

This cache transports the plan and binary across workflows in the **same pipeline**. Use the exact pipeline-specific key; do not add fallback keys or restore it in planning. Add suite and runtime identifiers to the key for multiple test environments. Reusable dependency caches are separate.

Start a new pipeline to repeat setup. Do not replan in each parallel container or combine this split with CircleCI's native test splitter.
{% /section %}

{% section
   displayed-if="The selected value for CI provider is included in the given list: 'Other - multiple nodes, Other - single node'" %}
This section only applies to users who meet the following criteria: The selected value for CI provider is included in the given list: 'Other - multiple nodes, Other - single node'

Set these variables in your CI provider's environment settings for the planning and test jobs. Keep credentials in its secret store.

| Variable                                      | Value                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DD_TEST_OPTIMIZATION_RUNNER_PLATFORM`        | {% section displayed-if="Platform is Ruby" %}
This section only applies to users who meet the following criteria: Platform is Ruby
ruby  {% /section %}

  {% section displayed-if="Platform is Python" %}
This section only applies to users who meet the following criteria: Platform is Python
python  {% /section %}

  {% section displayed-if="Platform is JavaScript" %}
This section only applies to users who meet the following criteria: Platform is JavaScript
javascript  {% /section %}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `DD_TEST_OPTIMIZATION_RUNNER_FRAMEWORK`       | {% section displayed-if="Framework is RSpec" %}
This section only applies to users who meet the following criteria: Framework is RSpec
rspec  {% /section %}

  {% section displayed-if="Framework is Minitest" %}
This section only applies to users who meet the following criteria: Framework is Minitest
minitest  {% /section %}

  {% section displayed-if="Framework is pytest" %}
This section only applies to users who meet the following criteria: Framework is pytest
pytest  {% /section %}

  {% section displayed-if="Framework is Jest" %}
This section only applies to users who meet the following criteria: Framework is Jest
jest  {% /section %}

  {% section displayed-if="Framework is Vitest" %}
This section only applies to users who meet the following criteria: Framework is Vitest
vitest  {% /section %}

  {% section displayed-if="Framework is Mocha" %}
This section only applies to users who meet the following criteria: Framework is Mocha
mocha  {% /section %}

  {% section displayed-if="Framework is Cucumber" %}
This section only applies to users who meet the following criteria: Framework is Cucumber
cucumber  {% /section %}

  {% section displayed-if="Framework is Cypress" %}
This section only applies to users who meet the following criteria: Framework is Cypress
cypress  {% /section %}

  {% section displayed-if="Framework is Playwright" %}
This section only applies to users who meet the following criteria: Framework is Playwright
playwright  {% /section %}

  {% section displayed-if="Framework is WebdriverIO" %}
This section only applies to users who meet the following criteria: Framework is WebdriverIO
webdriverio  {% /section %} |
| `DD_TEST_OPTIMIZATION_RUNNER_MIN_PARALLELISM` | 1                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `DD_TEST_OPTIMIZATION_RUNNER_MAX_PARALLELISM` | {% section displayed-if="CI provider is Other - single node" %}
This section only applies to users who meet the following criteria: CI provider is Other - single node
4  {% /section %}

  {% section displayed-if="CI provider is Other - multiple nodes" %}
This section only applies to users who meet the following criteria: CI provider is Other - multiple nodes
10  {% /section %}                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
{% /section %}

{% section displayed-if="CI provider is Other - multiple nodes" %}
This section only applies to users who meet the following criteria: CI provider is Other - multiple nodes
Generate one plan in a planning job:
```
rm -rf .testoptimization
bin/ddtest plan
cat .testoptimization/runner/parallel-runners.txt
```

Use the count in `.testoptimization/runner/parallel-runners.txt` to create jobs indexed `0` through `<COUNT> - 1`. Share the complete `.testoptimization/` directory, including hidden files, with each test job in the same pipeline.

In each test job, set `DDTEST_CI_NODE_INDEX` to that job's zero-based index and run its assignment:

```
test -f .testoptimization/manifest.txt
bin/ddtest run --ci-node "${DDTEST_CI_NODE_INDEX:?Set the zero-based node index for this job}"
```

Replace native test splitting with `ddtest` assignments. Keep plans separate from reusable dependency caches; each plan belongs to one suite and source revision.
{% /section %}

{% section displayed-if="CI provider is Other - single node" %}
This section only applies to users who meet the following criteria: CI provider is Other - single node
Replace the test command in your existing job with:
```
rm -rf .testoptimization
bin/ddtest run
```

`ddtest run` creates a plan and starts up to four local workers (the maximum parallelism set in the preceding table). Omit `--ci-node`; no separate planning job or artifact transfer is needed.

If the existing job is already sharded, preserve its suite boundary or consolidate it first. Running this command unchanged on every shard repeats the full suite.
{% /section %}

{% collapsible-section #configure-your-framework %}
### Custom test commands

Keep options such as tags, seeds, and formatters. To customize test file selection, use `DD_TEST_OPTIMIZATION_RUNNER_TESTS_LOCATION` to include files and `DD_TEST_OPTIMIZATION_RUNNER_TESTS_EXCLUDE_PATTERN` to exclude them. Both accept file patterns, such as `spec/requests/**/*_spec.rb`.

Keep your existing instrumentation and apply the same environment settings to planning and execution. See [Custom test commands](https://docs.datadoghq.com/tests/test_parallelization/configuration.md#custom-test-commands).

{% section displayed-if="Platform is Ruby" %}
This section only applies to users who meet the following criteria: Platform is Ruby

{% section displayed-if="Framework is RSpec" %}
This section only applies to users who meet the following criteria: Framework is RSpec

#### RSpec{% #rspec %}

`ddtest` uses the `bin/rspec` executable when present, otherwise `bundle exec rspec`.

Remove test file and directory paths from your custom command and `.rspec` so they do not run on multiple workers. Use the include/exclude settings above and keep other options.

For example, replace `bundle exec rspec spec/requests --tag smoke` with these CI environment settings:

```
DD_TEST_OPTIMIZATION_RUNNER_COMMAND: "bundle exec rspec --tag smoke"
DD_TEST_OPTIMIZATION_RUNNER_TESTS_LOCATION: "spec/requests/**/*_spec.rb"
```

Use the same settings for planning and execution.
{% /section %}

{% section displayed-if="Framework is Minitest" %}
This section only applies to users who meet the following criteria: Framework is Minitest

#### Minitest{% #minitest %}

For Rails, `ddtest` runs `bin/rails test` when `bin/rails` is executable, otherwise `bundle exec rails test`. Preserve any setup and options from custom Rake tasks, but use the Rails test command: a `rake test` override does not receive assigned files correctly.

For non-Rails projects, `ddtest` uses `bundle exec rake test`. Add `TEST_FILES` handling after the existing task configuration:

```
Rake::TestTask.new(:test) do |test|
  # Keep the task's existing configuration here.
  test.test_files = ENV["TEST_FILES"].split if ENV["TEST_FILES"]
end
```
{% /section %}
{% /section %}

{% section displayed-if="Platform is Python" %}
This section only applies to users who meet the following criteria: Platform is Python

#### Python (pytest){% #pytest %}

Activate your virtual environment before calling `ddtest`, which runs `python -m pytest` by default.

Keep existing `PYTEST_ADDOPTS`; `ddtest` adds `--ddtrace` to load the pytest plugin.

{% collapsible-section #pytest-custom-command %}
##### Custom launchers, configuration, or suite roots

For an existing command such as `uv run pytest -c config/pytest.ini -q tests/unit tests/integration`, add these settings to your CI environment, preserving any existing `PYTEST_ADDOPTS`:

```
DD_TEST_OPTIMIZATION_RUNNER_COMMAND: "uv run pytest"
PYTEST_ADDOPTS: "-c config/pytest.ini -q"
DD_TEST_OPTIMIZATION_RUNNER_TESTS_LOCATION: "{tests/unit,tests/integration}/**/test_*.py"
```

Adapt the quoted glob to your **files**, using braces for multiple roots. Keep file paths out of `PYTEST_ADDOPTS`; `ddtest` supplies each worker's files. Alternate configuration files and collection overrides may also need a matching glob. See [pytest discovery](https://docs.datadoghq.com/tests/test_parallelization/configuration.md#pytest-test-discovery).

Install `ddtrace` in the launcher's environment. For wrappers such as tox, allow Datadog and CI environment variables through.
{% /collapsible-section %}
{% /section %}

{% section displayed-if="Platform is JavaScript" %}
This section only applies to users who meet the following criteria: Platform is JavaScript

Keep your package manager, lockfile, and `NODE_OPTIONS` loaders. `ddtest` reuses existing Datadog instrumentation.

{% section displayed-if="Framework is Jest" %}
This section only applies to users who meet the following criteria: Framework is Jest

#### Jest{% #jest %}

Test Optimization supports `jest-circus` with the `node` or `jsdom` test environment.

Retain existing flags such as `--runInBand` in a [custom Jest command](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#jest).
{% /section %}

{% section displayed-if="Framework is Vitest" %}
This section only applies to users who meet the following criteria: Framework is Vitest

#### Vitest{% #vitest %}

Install Vitest and any configured coverage or environment packages in the project.

For a non-default configuration file, also set `DD_TEST_OPTIMIZATION_RUNNER_VITEST_CONFIG` to its path in your CI environment.

**Do not set `--command` or `DD_TEST_OPTIMIZATION_RUNNER_COMMAND`** for Vitest. Put projects, filters, reporters, output paths, and coverage options in [Vitest configuration](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#vitest).

Run from the package directory and run any package-script preparation before `ddtest`; it does not run npm life cycle scripts. Keep Vitest's setup and teardown.
{% /section %}

{% section displayed-if="Framework is Mocha" %}
This section only applies to users who meet the following criteria: Framework is Mocha

#### Mocha{% #mocha %}

Keep `.mocharc.*`, all suite paths, and shared `--file` and `--require` setup. `ddtest` uses the suite paths during discovery and runs only each worker's assigned test files. Shared setup runs in every worker. For command-line options, see [Mocha command overrides](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#mocha).
{% /section %}

{% section displayed-if="Framework is Cucumber" %}
This section only applies to users who meet the following criteria: Framework is Cucumber

#### Cucumber.js{% #cucumber %}

Preserve profiles, support code, paths, tags, and name filters in a [custom Cucumber command](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#cucumberjs). Use tag or name filters instead of scenario-line or rerun selections: `ddtest` assigns whole feature files. If a test script also runs preparation steps or other frameworks, run those separately.
{% /section %}

{% section displayed-if="Framework is Cypress" %}
This section only applies to users who meet the following criteria: Framework is Cypress

#### Cypress{% #cypress %}

Keep the Cypress [Test Optimization plugin and support-file instrumentation](https://docs.datadoghq.com/tests/setup/javascript.md?tab=cypress).

`ddtest` supplies `--spec`. Move any existing `--spec` selection to a file glob in your CI environment:

```
DD_TEST_OPTIMIZATION_RUNNER_COMMAND: 'pnpm exec cypress run --browser electron'
DD_TEST_OPTIMIZATION_RUNNER_TESTS_LOCATION: 'cypress/e2e/smoke-*.cy.js'
```

Start the application and wait for it to be ready in every test job. Install the required browser and [isolate resources](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#isolate-workers), including Xvfb displays, when workers share a node.
{% /section %}

{% section displayed-if="Framework is Playwright" %}
This section only applies to users who meet the following criteria: Framework is Playwright

#### Playwright{% #playwright %}

Remove native `--shard` options. Keep browser installation, project dependencies, and setup/teardown in Playwright configuration. Preserve selected projects and other flags in a [custom Playwright command](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#playwright).
{% /section %}

{% section displayed-if="Framework is WebdriverIO" %}
This section only applies to users who meet the following criteria: Framework is WebdriverIO

#### WebdriverIO{% #webdriverio %}

Use WebdriverIO with the local runner and the Mocha or Jasmine adapter.

Install `@wdio/cli` in the project. `ddtest` uses the local `wdio run` executable and detects `wdio.conf.*`. To select another configuration, set this environment variable:

```
DD_TEST_OPTIMIZATION_RUNNER_COMMAND: 'pnpm exec wdio run config/wdio.ci.conf.ts'
```

Keep browser capabilities, services, hooks, reporters, and application setup. `ddtest` preserves capability selections and disables native sharding.

Remote cloud grids and grouped specs such as `[['setup.js', 'case.js']]` are unsupported. Flatten groups only if the files can run independently.

Keep [WebdriverIO instrumentation](https://docs.datadoghq.com/tests/setup/javascript.md?tab=webdriverio) for test reporting; Test Impact Analysis skipping and per-test coverage are unsupported. [Isolate ports and report paths](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#isolate-workers) when workers share a node.
{% /section %}
{% /section %}

{% /collapsible-section %}

## Validate your setup{% #validate-your-setup %}
Inspect the planned files and parallelism:
```
cat .testoptimization/runner/parallel-runners.txt
cat .testoptimization/runner/test-files.txt
```

Check that:

- The plan covers the intended suite without unexpected omissions or duplicates. Test Impact Analysis can exclude skipped files.
- CI node and worker counts respect your capacity, and concurrent workers have [isolated resources](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#isolate-workers).
- Tests, failures, and skips appear in [Test Optimization Explorer](https://docs.datadoghq.com/tests/explorer.md), and test and coverage reports upload successfully.
Compare CI cost and duration with your previous setup, then [adjust the parallelism budget](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md#choose-a-parallelism-budget).
## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Test Parallelization settings reference](https://docs.datadoghq.com/tests/test_parallelization/configuration.md)
- [Tune parallelism, caching, and worker isolation](https://docs.datadoghq.com/tests/test_parallelization/best_practices.md)
- [Troubleshoot Test Parallelization](https://docs.datadoghq.com/tests/test_parallelization/troubleshooting.md)
