Missing or invalid plan artifacts

If ddtest run --ci-node <N> cannot find assigned test files, confirm that the .testoptimization/ directory from the planning job is available in the test job.

The test job must have access to:

• .testoptimization/manifest.txt
• .testoptimization/runner/parallel-runners.txt
• .testoptimization/runner/tests-split/runner-N

When using GitHub Actions, upload .testoptimization/ with include-hidden-files: true; otherwise, the artifact upload can omit the hidden directory.

Unexpected CI node or worker count

If ddtest selects more or fewer CI nodes than expected, review these settings:

• --min-parallelism: Minimum CI node or worker count considered by ddtest.
• --max-parallelism: Maximum CI node or worker count considered by ddtest.
• --ci-job-overhead: Estimated overhead for launching an additional CI node.
• --target-time: Target wall time for the selected split.

Increase --ci-job-overhead to prefer fewer CI nodes. Decrease it to prefer faster wall-clock time.

No skippable tests are applied

If Test Impact Analysis does not skip tests before Test Parallelization runs, check that:

• Test Impact Analysis is enabled for the test service.
• The git executable is present, and you run ddtest in a Git repository with a .git folder.
• The job that runs ddtest plan and the job that runs tests use the same DD_SERVICE value.
• ddtest plan runs on the same OS and language runtime as your tests.

For more information, see Test Impact Analysis troubleshooting.

Minitest does not run the selected files

For non-Rails Minitest projects, ddtest uses bundle exec rake test and passes the selected files in the TEST_FILES environment variable. Your Rake::TestTask must read TEST_FILES:

Rake::TestTask.new(:test) do |test|
  test.test_files = ENV["TEST_FILES"] ? ENV["TEST_FILES"].split : ["test/**/*.rb"]
end

Custom commands do not run the expected files

When using --command, do not include test files or the -- separator in the command. ddtest appends the selected test files itself.

Incorrect:

bin/ddtest run --command "bundle exec rspec -- spec/models/"

Correct:

bin/ddtest run --platform ruby --framework rspec --command "bundle exec rspec"

For Cucumber.js, Cypress, Mocha, Playwright, and Vitest, the command must invoke the selected framework directly. Package manager wrappers are supported. For example:

bin/ddtest run --platform javascript --framework playwright --command "pnpm exec playwright test --project chromium"

If a custom JavaScript command runs an unexpected selection, check the framework inputs that ddtest replaces:

• Cucumber.js positional paths and rerun files
• Cypress --spec
• Mocha configured spec inputs
• Playwright --shard and interactive UI options

Further reading

Additional helpful documentation, links, and articles:

Set up Test ParallelizationDOCUMENTATION Configure Test ParallelizationDOCUMENTATION Troubleshooting Test OptimizationDOCUMENTATION