From 71364b41e2f56baa4b879e940c09699d3fa297ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Antonio=20Fern=C3=A1ndez=20de=20Alba?= Date: Fri, 3 Jul 2026 11:47:57 +0200 Subject: [PATCH 1/4] Update JavaScript test optimization docs --- content/en/tests/setup/javascript.md | 124 ++++++--------------- content/en/tests/troubleshooting/_index.md | 4 +- 2 files changed, 36 insertions(+), 92 deletions(-) diff --git a/content/en/tests/setup/javascript.md b/content/en/tests/setup/javascript.md index a66b9424f6c..d55ef69b9c7 100644 --- a/content/en/tests/setup/javascript.md +++ b/content/en/tests/setup/javascript.md @@ -24,6 +24,23 @@ further_reading: ## Compatibility +### `dd-trace` v6 + +Supported test frameworks: + +| Test Framework | Version | Notes | +|---|---|---| +| Jest | >= 28.0.0 | Only `jsdom` (in the `jest-environment-jsdom` package) and `node` (in the `jest-environment-node` package) are supported as test environments. Custom environments like `@jest-runner/electron/environment` in `jest-electron-runner` are not supported.

Only [`jest-circus`][1] is supported as [`testRunner`][2].

[`test.concurrent`](#jests-testconcurrent) is not supported. | +| Mocha | >= 8.0.0 | +| Cucumber | >= 7.0.0 | +| Cypress | >= 12.0.0 | +| Playwright | >= 1.38.0 | +| Vitest | >= 1.6.0 | [`test.concurrent`](https://vitest.dev/api/#test-concurrent) is supported from `dd-trace>=6.1.0`. | + +`dd-trace` v6 requires Node.js >= 22. + +### `dd-trace` v5 + Supported test frameworks: | Test Framework | Version | Notes | @@ -33,7 +50,7 @@ Supported test frameworks: | Cucumber | >= 7.0.0 | | Cypress | >= 6.7.0 | | Playwright | >= 1.18.0 | -| Vitest | >= 1.16.0 | Supported from `dd-trace>=4.42.0` and `dd-trace>=5.18.0`. Only supported from Node.js>=18.19 or Node.js>=20.6 | +| Vitest | >= 1.6.0 | Supported from `dd-trace>=5.18.0`. [`test.concurrent`](https://vitest.dev/api/#test-concurrent) is supported from `dd-trace>=5.112.0`. | The instrumentation works at runtime, so any transpilers such as TypeScript, Webpack, or Babel are supported out-of-the-box. @@ -361,66 +378,6 @@ module.exports = defineConfig({ }) {{< /code-block >}} -### Cypress before version 10 - -These are the instructions if you're using a version older than `cypress@10`. See the [Cypress documentation][4] for more information about migrating to a newer version. - -1. Set [`pluginsFile`][5] to `"dd-trace/ci/cypress/plugin"`, for example, through [`cypress.json`][6]: -{{< code-block lang="json" filename="cypress.json" >}} -{ - "pluginsFile": "dd-trace/ci/cypress/plugin" -} -{{< /code-block >}} - -If you already defined a `pluginsFile`, initialize the instrumentation with: -{{< code-block lang="javascript" filename="cypress/plugins/index.js" >}} -module.exports = (on, config) => { - // your previous code is before this line - return require('dd-trace/ci/cypress/plugin')(on, config) -} -{{< /code-block >}} - -2. Add the following line to the **top level** of your [`supportFile`][7]: -{{< code-block lang="javascript" filename="cypress/support/index.js" >}} -// Your code can be before this line -// require('./commands') -require('dd-trace/ci/cypress/support') -// Your code can also be after this line -// Cypress.Commands.add('login', (email, pw) => {}) -{{< /code-block >}} - -#### Cypress `after:run` event -Datadog requires the [`after:run`][2] Cypress event to work, and Cypress does not allow multiple handlers for that event. If you defined handlers for `after:run` already, add the Datadog handler manually by importing `'dd-trace/ci/cypress/after-run'`: - -{{< code-block lang="javascript" filename="cypress/plugins/index.js" >}} -module.exports = (on, config) => { - // your previous code is before this line - require('dd-trace/ci/cypress/plugin')(on, config) - on('after:run', (details) => { - // other 'after:run' handlers - // important that this function call is returned - return require('dd-trace/ci/cypress/after-run')(details) - }) -} -{{< /code-block >}} - -#### Cypress `after:spec` event -Datadog requires the [`after:spec`][3] Cypress event to work, and Cypress does not allow multiple handlers for that event. If you defined handlers for `after:spec` already, add the Datadog handler manually by importing `'dd-trace/ci/cypress/after-spec'`: - -{{< code-block lang="javascript" filename="cypress/plugins/index.js" >}} -module.exports = (on, config) => { - // your previous code is before this line - require('dd-trace/ci/cypress/plugin')(on, config) - on('after:spec', (...args) => { - // other 'after:spec' handlers - // Important that this function call is returned - // Important that all the arguments are passed - return require('dd-trace/ci/cypress/after-run')(...args) - }) -} -{{< /code-block >}} - - Run your tests as you normally would, optionally specifying a name for your test session with `DD_TEST_SESSION_NAME`: {{< code-block lang="shell" >}} @@ -449,7 +406,7 @@ it('renders a hello world', () => { }) ``` -To create filters or `group by` fields for these tags, you must first create facets. For more information about adding tags, see the [Adding Tags][8] section of the Node.js custom instrumentation documentation. +To create filters or `group by` fields for these tags, you must first create facets. For more information about adding tags, see the [Adding Tags][4] section of the Node.js custom instrumentation documentation. ### Adding custom measures to tests @@ -467,24 +424,20 @@ it('renders a hello world', () => { }) ``` -For more information about custom measures, see the [Add Custom Measures Guide][9]. +For more information about custom measures, see the [Add Custom Measures Guide][5]. ### Cypress - RUM integration -If the browser application being tested is instrumented using [Browser Monitoring][10], the Cypress test results and their generated RUM browser sessions and session replays are automatically linked. For more information, see the [Instrumenting your browser tests with RUM guide][11]. +If the browser application being tested is instrumented using [Browser Monitoring][6], the Cypress test results and their generated RUM browser sessions and session replays are automatically linked. For more information, see the [Instrumenting your browser tests with RUM guide][7]. [1]: https://docs.cypress.io/guides/tooling/plugins-guide#Using-a-plugin [2]: https://docs.cypress.io/api/plugins/after-run-api [3]: https://docs.cypress.io/api/plugins/after-spec-api -[4]: https://docs.cypress.io/guides/references/migration-guide#Migrating-to-Cypress-100 -[5]: https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests#Plugins-file -[6]: https://docs.cypress.io/guides/references/configuration#cypress-json -[7]: https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests#Support-file -[8]: /tracing/trace_collection/custom_instrumentation/nodejs?tab=locally#adding-tags -[9]: /tests/guides/add_custom_measures/?tab=javascripttypescript -[10]: /real_user_monitoring/application_monitoring/browser/setup/ -[11]: /continuous_integration/guides/rum_integration/ +[4]: /tracing/trace_collection/custom_instrumentation/nodejs?tab=locally#adding-tags +[5]: /tests/guides/add_custom_measures/?tab=javascripttypescript +[6]: /real_user_monitoring/application_monitoring/browser/setup/ +[7]: /continuous_integration/guides/rum_integration/ {{% /tab %}} {{% tab "Vitest" %}} @@ -492,7 +445,7 @@ If the browser application being tested is instrumented using [Browser Monitorin Note: Vitest is ESM first, so its configuration is different from other test frameworks. -`vitest` and `dd-trace` require Node.js>=18.19 or Node.js>=20.6 to work. +Use a Node.js version supported by your `dd-trace` major version. `dd-trace` v5 requires Node.js >= 18.19 or >= 20.6 for Vitest instrumentation, and `dd-trace` v6 requires Node.js >= 22. Set the `NODE_OPTIONS` environment variable to `--import dd-trace/register.js -r dd-trace/ci/init`. Run your tests as you normally would, optionally specifying a name for your test session with `DD_TEST_SESSION_NAME`: @@ -604,7 +557,7 @@ The following is a list of the most important configuration settings that can be `test_session.name` : Use it to identify a group of tests, such as `integration-tests`, `unit-tests` or `smoke-tests`.
**Environment variable**: `DD_TEST_SESSION_NAME`
-**Default**: (CI job name + test command)
+**Default**: Framework invocation for `dd-trace` v6, such as `jest`, `mocha`, `playwright test`, or `cucumber-js`; CI job name and test command for `dd-trace` v5
**Example**: `unit-tests`, `integration-tests`, `smoke-tests` `service` @@ -754,9 +707,6 @@ If you want visibility into the browser process, consider using [RUM & Session R Cypress interactive mode (which you can enter by running `cypress open`) is not supported by Test Optimization because some cypress events, such as [`before:run`][11], are not fired. If you want to try it anyway, pass `experimentalInteractiveRunEvents: true` to the [cypress configuration file][12]. -### Jest's `--workerThreads` -Jest's [workerThreads][13] option is not supported. - ### Jest's `test.concurrent` Jest's [test.concurrent][14] is not supported. @@ -775,6 +725,8 @@ By default, Vitest's [`isolate`][21] option is `true`, so each test file runs in To lower overhead, set `isolate: false` in your Vitest config file, or pass `--no-isolate` to the test command. +To keep Vitest isolation enabled, set `DD_EXPERIMENTAL_TEST_OPT_VITEST_NO_WORKER_INIT=true` to lower worker startup overhead. This option is available in `dd-trace` versions `5.111.0` and later, and `6.0.0` and later. It applies to isolated Vitest worker-pool runs with Vitest `3.2.6` and later, and falls back to normal worker instrumentation for unsupported configurations. Because this mode does not initialize `dd-trace` in Vitest workers, features that require an active test span inside test code, such as custom test tags, custom spans, log correlation from test code, and Failed Test Replay, are not supported. + ## Best practices Follow these practices to take full advantage of the testing framework and Test Optimization. @@ -826,22 +778,13 @@ Use `DD_TEST_SESSION_NAME` to define the name of the test session and the relate - `ui-tests` - `backend-tests` -If `DD_TEST_SESSION_NAME` is not specified, the default value used is a combination of: +If `DD_TEST_SESSION_NAME` is not specified, the default value is: -- CI job name -- Command used to run the tests (such as `yarn test`) +- For `dd-trace` v6, the framework invocation, such as `jest`, `mocha`, `playwright test`, or `cucumber-js` +- For `dd-trace` v5, a combination of CI job name and the command used to run the tests, such as `yarn test` The test session name should be unique within a repository to help you distinguish different groups of tests. -#### When to use `DD_TEST_SESSION_NAME` - -There's a set of parameters that Datadog checks to establish correspondence between test sessions. The test command used to execute the tests is one of them. If the test command contains a string that changes for every execution, such as a temporary folder, Datadog considers the sessions to be unrelated to each other. For example: - -- `yarn test --temp-dir=/var/folders/t1/rs2htfh55mz9px2j4prmpg_c0000gq/T` -- `pnpm vitest --temp-dir=/var/folders/t1/rs2htfh55mz9px2j4prmpg_c0000gq/T` - -Datadog recommends using `DD_TEST_SESSION_NAME` if your test commands vary between executions. - ## Further reading {{< partial name="whats-next/whats-next.html" >}} @@ -858,7 +801,6 @@ Datadog recommends using `DD_TEST_SESSION_NAME` if your test commands vary betwe [10]: /continuous_integration/guides/rum_integration/ [11]: https://docs.cypress.io/api/plugins/before-run-api [12]: https://docs.cypress.io/guides/references/configuration#Configuration-File -[13]: https://jestjs.io/docs/configuration#workerthreads [14]: https://jestjs.io/docs/api#testconcurrentname-fn-timeout [15]: https://jestjs.io/docs/cli#--forceexit [16]: https://mochajs.org/running/cli/#--exit @@ -866,4 +808,4 @@ Datadog recommends using `DD_TEST_SESSION_NAME` if your test commands vary betwe [18]: https://jestjs.io/docs/api#testeachtablename-fn-timeout [19]: https://www.npmjs.com/package/mocha-each [20]: https://github.com/nodejs/import-in-the-middle -[21]: https://vitest.dev/config/isolate \ No newline at end of file +[21]: https://vitest.dev/config/isolate diff --git a/content/en/tests/troubleshooting/_index.md b/content/en/tests/troubleshooting/_index.md index 8b8aa9c5e26..4e058c03d18 100644 --- a/content/en/tests/troubleshooting/_index.md +++ b/content/en/tests/troubleshooting/_index.md @@ -181,6 +181,8 @@ By default, Vitest's [`isolate`][17] option is `true`, so each test file runs in To lower overhead, set `isolate: false` in your Vitest config file, or pass `--no-isolate` to the test command. +To keep Vitest isolation enabled, set `DD_EXPERIMENTAL_TEST_OPT_VITEST_NO_WORKER_INIT=true` to lower worker startup overhead. This option is available in `dd-trace` versions `5.111.0` and later, and `6.0.0` and later. It applies to isolated Vitest worker-pool runs with Vitest `3.2.6` and later, and falls back to normal worker instrumentation for unsupported configurations. Because this mode does not initialize `dd-trace` in Vitest workers, features that require an active test span inside test code, such as custom test tags, custom spans, log correlation from test code, and Failed Test Replay, are not supported. + ## Further reading {{< partial name="whats-next/whats-next.html" >}} @@ -202,4 +204,4 @@ To lower overhead, set `isolate: false` in your Vitest config file, or pass `--n [15]: /agent/configuration/network/ [16]: /tests/network/ [17]: https://vitest.dev/config/isolate -[18]: https://github.com/nodejs/import-in-the-middle \ No newline at end of file +[18]: https://github.com/nodejs/import-in-the-middle From 0c124a18d4a449751fe044aaf82c1a9aab6b27e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Antonio=20Fern=C3=A1ndez=20de=20Alba?= Date: Fri, 3 Jul 2026 11:58:51 +0200 Subject: [PATCH 2/4] Update Playwright custom tags docs --- content/en/tests/setup/javascript.md | 60 ++++++++-------------------- 1 file changed, 16 insertions(+), 44 deletions(-) diff --git a/content/en/tests/setup/javascript.md b/content/en/tests/setup/javascript.md index d55ef69b9c7..f531cee04b7 100644 --- a/content/en/tests/setup/javascript.md +++ b/content/en/tests/setup/javascript.md @@ -168,72 +168,44 @@ NODE_OPTIONS="-r dd-trace/ci/init" DD_TEST_SESSION_NAME=e2e-tests yarn test:e2e ### Adding custom tags to tests -You can add custom tags to your tests by using the [custom annotations API from Playwright][1]: +You can add custom tags to your tests by using the current active span: ```javascript test('user profile', async ({ page }) => { - test.info().annotations.push({ - type: 'DD_TAGS[test.memory.usage]', // DD_TAGS is mandatory and case sensitive - description: 'low', - }); - test.info().annotations.push({ - type: 'DD_TAGS[test.task.id]', - description: '41123', - }); + const testSpan = require('dd-trace').scope().active() + testSpan.setTag('team_owner', 'my_team') // ... -}); +}) test('landing page', async ({ page }) => { - test.info().annotations.push({ - type: 'DD_TAGS[test.cpu.usage]', - description: 'high', - }); + const testSpan = require('dd-trace').scope().active() + testSpan.setTag('test.cpu.usage', 'high') // ... -}); +}) ``` -The format of the annotations is the following, where `$TAG_NAME` and `$TAG_VALUE` are *strings* representing tag name and value respectively: - -```json -{ - "type": "DD_TAGS[$TAG_NAME]", - "description": "$TAG_VALUE" -} -``` +To create filters or `group by` fields for these tags, you must first create facets. For more information about adding tags, see the [Adding Tags][1] section of the Node.js custom instrumentation documentation. ### Adding custom measures to tests -Custom measures also use custom annotations: +Just like tags, you can add custom measures to your tests by using the current active span: ```javascript test('user profile', async ({ page }) => { - test.info().annotations.push({ - type: 'DD_TAGS[test.memory.allocations]', // DD_TAGS is mandatory and case sensitive - description: 16, // this is a number - }); -}); -``` - -The format of the annotations is the following, where `$TAG_NAME` is a *string* representing the tag name and `$TAG_VALUE` is a *number* representing the tag value: - -```json -{ - "type": "DD_TAGS[$TAG_NAME]", - "description": $TAG_VALUE -} + const testSpan = require('dd-trace').scope().active() + testSpan.setTag('memory_allocations', 16) + // ... +}) ``` -**Note**: `description` values in annotations are [typed as strings][2]. Numbers also work, but you may need to disable the typing error with `// @ts-expect-error`. -
- Important: The DD_TAGS prefix is mandatory and case sensitive. -
+For more information about custom measures, see the [Add Custom Measures Guide][2]. ### Playwright - RUM integration If the browser application being tested is instrumented using [Browser Monitoring][3], the Playwright test results and their generated RUM browser sessions and session replays are automatically linked. For more information, see the [Instrumenting your browser tests with RUM guide][4]. -[1]: https://playwright.dev/docs/test-annotations#custom-annotations -[2]: https://playwright.dev/docs/api/class-testinfo#test-info-annotations +[1]: /tracing/trace_collection/custom_instrumentation/nodejs?tab=locally#adding-tags +[2]: /tests/guides/add_custom_measures/?tab=javascripttypescript [3]: /real_user_monitoring/application_monitoring/browser/setup/ [4]: /continuous_integration/guides/rum_integration/ {{% /tab %}} From 14275fc1d009edc2fe5b5777c00a8c2ebeeadaf7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Antonio=20Fern=C3=A1ndez=20de=20Alba?= Date: Fri, 3 Jul 2026 13:28:36 +0200 Subject: [PATCH 3/4] Use tabs for tracer compatibility docs --- content/en/tests/setup/javascript.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/content/en/tests/setup/javascript.md b/content/en/tests/setup/javascript.md index f531cee04b7..9f4b7c1ca34 100644 --- a/content/en/tests/setup/javascript.md +++ b/content/en/tests/setup/javascript.md @@ -24,9 +24,8 @@ further_reading: ## Compatibility -### `dd-trace` v6 - -Supported test frameworks: +{{< tabs >}} +{{% tab "dd-trace v6" %}} | Test Framework | Version | Notes | |---|---|---| @@ -39,9 +38,8 @@ Supported test frameworks: `dd-trace` v6 requires Node.js >= 22. -### `dd-trace` v5 - -Supported test frameworks: +{{% /tab %}} +{{% tab "dd-trace v5" %}} | Test Framework | Version | Notes | |---|---|---| @@ -52,6 +50,9 @@ Supported test frameworks: | Playwright | >= 1.18.0 | | Vitest | >= 1.6.0 | Supported from `dd-trace>=5.18.0`. [`test.concurrent`](https://vitest.dev/api/#test-concurrent) is supported from `dd-trace>=5.112.0`. | +{{% /tab %}} +{{< /tabs >}} + The instrumentation works at runtime, so any transpilers such as TypeScript, Webpack, or Babel are supported out-of-the-box. ## Configuring reporting method From 07874b08e551be0dc6b118fd329a4566f8c871ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Juan=20Antonio=20Fern=C3=A1ndez=20de=20Alba?= Date: Fri, 3 Jul 2026 13:32:12 +0200 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- content/en/tests/setup/javascript.md | 13 ++++++++++--- content/en/tests/troubleshooting/_index.md | 9 ++++++++- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/content/en/tests/setup/javascript.md b/content/en/tests/setup/javascript.md index 9f4b7c1ca34..f3c57e386be 100644 --- a/content/en/tests/setup/javascript.md +++ b/content/en/tests/setup/javascript.md @@ -36,7 +36,7 @@ further_reading: | Playwright | >= 1.38.0 | | Vitest | >= 1.6.0 | [`test.concurrent`](https://vitest.dev/api/#test-concurrent) is supported from `dd-trace>=6.1.0`. | -`dd-trace` v6 requires Node.js >= 22. +`dd-trace` v6 requires Node.js 22 or later. {{% /tab %}} {{% tab "dd-trace v5" %}} @@ -530,7 +530,7 @@ The following is a list of the most important configuration settings that can be `test_session.name` : Use it to identify a group of tests, such as `integration-tests`, `unit-tests` or `smoke-tests`.
**Environment variable**: `DD_TEST_SESSION_NAME`
-**Default**: Framework invocation for `dd-trace` v6, such as `jest`, `mocha`, `playwright test`, or `cucumber-js`; CI job name and test command for `dd-trace` v5
+**Default**: For `dd-trace` v6, the framework invocation (`jest`, `mocha`, `playwright test`, or `cucumber-js`). For `dd-trace` v5, a combination of CI job name and test command.
**Example**: `unit-tests`, `integration-tests`, `smoke-tests` `service` @@ -698,7 +698,14 @@ By default, Vitest's [`isolate`][21] option is `true`, so each test file runs in To lower overhead, set `isolate: false` in your Vitest config file, or pass `--no-isolate` to the test command. -To keep Vitest isolation enabled, set `DD_EXPERIMENTAL_TEST_OPT_VITEST_NO_WORKER_INIT=true` to lower worker startup overhead. This option is available in `dd-trace` versions `5.111.0` and later, and `6.0.0` and later. It applies to isolated Vitest worker-pool runs with Vitest `3.2.6` and later, and falls back to normal worker instrumentation for unsupported configurations. Because this mode does not initialize `dd-trace` in Vitest workers, features that require an active test span inside test code, such as custom test tags, custom spans, log correlation from test code, and Failed Test Replay, are not supported. +To keep Vitest isolation enabled with lower worker startup overhead, set `DD_EXPERIMENTAL_TEST_OPT_VITEST_NO_WORKER_INIT=true`. This option is available in `dd-trace` `5.111.0` and later, and `6.0.0` and later. It applies to isolated Vitest worker-pool runs with Vitest `3.2.6` and later, and falls back to normal worker instrumentation for unsupported configurations. + +Because this mode does not initialize `dd-trace` in Vitest workers, the following features are not supported: + +- Custom test tags +- Custom spans +- Log correlation from test code +- Failed Test Replay ## Best practices diff --git a/content/en/tests/troubleshooting/_index.md b/content/en/tests/troubleshooting/_index.md index 4e058c03d18..a1c429348ba 100644 --- a/content/en/tests/troubleshooting/_index.md +++ b/content/en/tests/troubleshooting/_index.md @@ -181,7 +181,14 @@ By default, Vitest's [`isolate`][17] option is `true`, so each test file runs in To lower overhead, set `isolate: false` in your Vitest config file, or pass `--no-isolate` to the test command. -To keep Vitest isolation enabled, set `DD_EXPERIMENTAL_TEST_OPT_VITEST_NO_WORKER_INIT=true` to lower worker startup overhead. This option is available in `dd-trace` versions `5.111.0` and later, and `6.0.0` and later. It applies to isolated Vitest worker-pool runs with Vitest `3.2.6` and later, and falls back to normal worker instrumentation for unsupported configurations. Because this mode does not initialize `dd-trace` in Vitest workers, features that require an active test span inside test code, such as custom test tags, custom spans, log correlation from test code, and Failed Test Replay, are not supported. +To keep Vitest isolation enabled with lower worker startup overhead, set `DD_EXPERIMENTAL_TEST_OPT_VITEST_NO_WORKER_INIT=true`. This option is available in `dd-trace` `5.111.0` and later, and `6.0.0` and later. It applies to isolated Vitest worker-pool runs with Vitest `3.2.6` and later, and falls back to normal worker instrumentation for unsupported configurations. + +Because this mode does not initialize `dd-trace` in Vitest workers, the following features are not supported: + +- Custom test tags +- Custom spans +- Log correlation from test code +- Failed Test Replay ## Further reading