docs: add JavaScript Jest ddtest usage

Author: cbasitodx

README.md

@@ -14,17 +14,19 @@ Currently supported:
 - Ruby with RSpec or Minitest.
 - Python with pytest.
 - JavaScript with Jest.
+- JavaScript with Jest.
 
 ## Prerequisites
 
 Before using DDTest, you must have **Datadog Test Optimization** already set up and enabled with a Datadog Test Optimization library for your language and framework. DDTest relies on this integration to discover your tests and plan test execution accordingly.
 
+Minimum supported library and runtime requirements:
 Minimum supported library and runtime requirements:
 
 - Ruby requires the `datadog-ci` gem **1.31.0** or higher.
 - Python requires the `ddtrace` package **4.10.3** or higher and `pytest`.
-- JavaScript requires Node.js, Jest, and the `dd-trace` package with
-  `dd-trace/ci/init` available.
+- JavaScript requires the `dd-trace` package **6.0.0** or higher, Node.js, and
+  Jest.
 
 For instructions on setting up Test Optimization, see the [Datadog Test Optimization documentation](https://docs.datadoghq.com/tests/setup/).
 
@@ -79,6 +81,16 @@ ddtest plan \
   --max-parallelism 32
 ```
 
+For JavaScript/Jest:
+
+```bash
+ddtest plan \
+  --platform javascript \
+  --framework jest \
+  --min-parallelism 8 \
+  --max-parallelism 32
+```
+
 This prepares the plan and writes it to `.testoptimization/` folder for later reuse.
 Copy `.testoptimization/` to any CI job that runs `ddtest run` or reads DDTest's
 plan file lists. For the full file layout and formats, see
@@ -106,6 +118,12 @@ For JavaScript/Jest:
 ddtest run --platform javascript --framework jest
 ```
 
+For JavaScript/Jest:
+
+```bash
+ddtest run --platform javascript --framework jest
+```
+
 For CI-node mode, worker environment variables, custom commands, and
 parallelism details, see [Running DDTest](docs/running.md).
 
@@ -116,6 +134,9 @@ parallelism details, see [Running DDTest](docs/running.md).
 | `--platform` | Language/platform. Currently supported: `ruby`, `python`, `javascript`. |
 | `--framework` | Test framework. Currently supported: `rspec`, `minitest`, `pytest`, `jest`. |
 | `--command` | Override the default base command for supported framework modes. Currently used by RSpec and Minitest run/discovery, and Jest run/discovery. For pytest, use `PYTEST_ADDOPTS` for pytest flags. |
+| `--platform` | Language/platform. Currently supported: `ruby`, `python`, `javascript`. |
+| `--framework` | Test framework. Currently supported: `rspec`, `minitest`, `pytest`, `jest`. |
+| `--command` | Override the default base command for supported framework modes. Currently used by RSpec and Minitest run/discovery, and Jest run/discovery. For pytest, use `PYTEST_ADDOPTS` for pytest flags. |
 | `--min-parallelism` | Minimum CI node or worker count DDTest considers when planning. |
 | `--max-parallelism` | Maximum CI node or worker count DDTest considers when planning. |
 | `--target-time` | Target wall time DDTest tries to satisfy when selecting parallelism. |

docs/best_practices.md

@@ -3,9 +3,10 @@
 ## Optimize Planning Step
 
 When using ddtest, you need to add a planning step that performs test discovery
-(for example, RSpec dry-run, pytest collection, or Jest `--listTests`) before
-execution. This stage adds overhead: you can optimize it with the practices
-below.
+before execution. For Ruby and Python, this can involve full framework
+discovery such as RSpec dry-run or pytest collection. For Jest, DDTest uses
+Jest's `--listTests` command to discover test files. This planning stage adds
+overhead: you can optimize it with the practices below.
 
 ### Preinstall System Dependencies Via Docker
 
@@ -50,6 +51,15 @@ For GitHub Actions + npm:
     cache: npm
 ```
 
+For GitHub Actions + npm:
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: "22"
+    cache: npm
+```
+
 ### Disable Seeds/Fixtures During Discovery
 
 Discovery (planning) does not execute tests; you don't have to setup DB,
@@ -135,6 +145,8 @@ the cache when files under the current project's test root changed. For example,
 the default RSpec root is `spec/**`, the default Minitest root is `test/**`,
 pytest uses `testpaths` from pytest config when available, and Jest uses the
 project's Jest test matching unless `--tests-location` is set. With
+pytest uses `testpaths` from pytest config when available, and Jest uses the
+project's Jest test matching unless `--tests-location` is set. With
 `--tests-location custom/spec/**/*_spec.rb`, the root is `custom/**`.
 
 In monorepos, run DDTest from the project subdirectory whose tests you are
@@ -175,6 +187,29 @@ where DDTest runs.
 Jest support uses suite-level Test Impact Analysis. DDTest discovers and splits
 test files/suites, not individual Jest tests.
 
+## Jest Support
+
+DDTest runs Jest through the local `node_modules/.bin/jest` executable when it
+exists, or through `npx jest` otherwise. During planning it appends
+`--listTests`; during execution it appends `--runTestsByPath` and the selected
+test files.
+
+Use `--command` when your project runs Jest through a package manager or wrapper:
+
+```bash
+ddtest run --platform javascript --framework jest --command "pnpm jest --runInBand"
+```
+
+Do not include test files or a `--` separator in the command; DDTest appends the
+file list and Jest flags itself.
+
+DDTest prepends `-r dd-trace/ci/init` to `NODE_OPTIONS` for worker processes
+unless it is already present, so `dd-trace` must be resolvable from the project
+where DDTest runs.
+
+Jest support uses suite-level Test Impact Analysis. DDTest discovers and splits
+test files/suites, not individual Jest tests.
+
 ## Minitest Support In Non-Rails Projects
 
 We use `bundle exec rake test` command when we don't detect `rails` command to

docs/upgrade-1.0.md

@@ -6,12 +6,13 @@ Before upgrading to 1.0, update CI jobs and custom integrations to consume the
 
 ## Required Changes
 
+Minimum supported library and runtime requirements:
 Minimum supported library and runtime requirements:
 
 - Ruby requires the `datadog-ci` gem 1.31.0 or higher.
 - Python requires the `ddtrace` package 4.10.3 or higher and `pytest`.
-- JavaScript requires Node.js, Jest, and the `dd-trace` package with
-  `dd-trace/ci/init` available.
+- JavaScript requires the `dd-trace` package 6.0.0 or higher, Node.js, and
+  Jest.
 
 DDTest 1.0 writes plan files under `.testoptimization/runner/*`. If your
 scripts, CI jobs, or custom test runners read DDTest plan files directly, update
@@ -28,8 +29,7 @@ these paths:
 
 1. Verify the Datadog Test Optimization library version for your platform:
    `datadog-ci` 1.31.0 or higher for Ruby, or `ddtrace` 4.10.3 or higher for
-   Python. For JavaScript, verify that `dd-trace` is installed and that
-   `dd-trace/ci/init` is resolvable from the project root.
+   Python, or `dd-trace` 6.0.0 or higher for JavaScript.
 2. Remove references to legacy root plan paths from CI templates and custom scripts.
 3. Run `ddtest plan` in CI.
 4. Run one CI shard with `DD_TEST_OPTIMIZATION_RUNNER_CI_NODE=0 ddtest run`.