We support auto-instrumentation for the following CI providers:

If you are using auto-instrumentation for one of these providers, you can skip the rest of the setup steps below.

DD_CIVISIBILITY_AGENTLESS_ENABLED=true (requis)

Active ou désactive le mode sans Agent.
Valeur par défaut : false

DD_API_KEY (requis)

La clé d’API Datadog utilisée pour importer les résultats de test.
Valeur par défaut: (empty)

Configurez aussi le site Datadog vers lequel vous souhaitez envoyer des données.

DD_SITE (requis)

Le site Datadog vers lequel importer les résultats.
Valeur par défaut : datadoghq.com

SI vous exécutez des tests avec un fournisseur de CI sur site, comme Jenkins ou GitLab CI autogéré, installez l’Agent Datadog sur chaque nœud de worker en suivant les instructions d’installation de l’Agent. Cette méthode est recommandée, car elle vous permet d’associer automatiquement les résultats de test aux logs et aux métriques des hosts sous-jacents.

Si vous utilisez un exécuteur Kubernetes, Datadog vous conseille d’utiliser l’Operator Datadog. Celui-ci comprend le contrôleur d’admission Datadog, qui peut automatiquement injecter la bibliothèque du traceur dans les pods du build. Remarque : si vous utilisez l’Operator Datadog, il n’est pas nécessaire de télécharger et d’injecter la bibliothèque du traceur, car le contrôleur d’admission le fait à votre place. Vous pouvez donc ignorer l’étape correspondante ci-dessous. Vous devez toutefois vous assurer que vos pods définissent les variables d’environnement ou paramètres de ligne de commande nécessaires à l’activation de Test Visibility.

Si vous n’utilisez pas Kubernetes, ou si vous ne pouvez pas utiliser le contrôleur d’admission Datadog, et que le fournisseur de CI repose sur un exécuteur basé sur des conteneurs, définissez la variable d’environnement DD_TRACE_AGENT_URL (valeur par défaut : http://localhost:8126) dans le conteneur du build exécutant le traceur sur un endpoint accessible dans le conteneur. Remarque : lorsqu’elle est utilisée à l’intérieur du conteneur, la valeur localhost désigne le conteneur, et non le nœud de worker sous-jacent ou un conteneur dans lequel l’Agent pourrait s’exécuter.

DD_TRACE_AGENT_URL comprend le protocole et le port (par exemple, http://localhost:8126) et est prioritaire par rapport à DD_AGENT_HOST et DD_TRACE_AGENT_PORT. Ce paramètre est recommandé pour la configuration de l’URL de l’Agent Datadog pour CI Visibility.

Si vous ne parvenez pas à établir une connexion avec l’Agent Datadog, utilisez le mode sans agent. Remarque : avec cette méthode, les tests ne sont pas mis en corrélation avec les logs et les métriques d’infrastructure.

Set the NODE_OPTIONS environment variable to -r dd-trace/ci/init. Run your tests as you normally would, specifying the environment where the tests are run in the DD_ENV environment variable. For example, set DD_ENV to local when running tests on a developer workstation, or ci when running them on a CI provider:

NODE_OPTIONS="-r dd-trace/ci/init" DD_ENV=ci DD_SERVICE=my-javascript-app yarn test

Note: If you set a value for NODE_OPTIONS, make sure it does not overwrite -r dd-trace/ci/init. This can be done using the ${NODE_OPTIONS:-} clause:

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" jest"
  }
}

Adding custom tags to tests

You can add custom tags to your tests by using the current active span:

  it('sum function can sum', () => {
    const testSpan = require('dd-trace').scope().active()
    testSpan.setTag('team_owner', 'my_team')
    // test continues normally
    // ...
  })

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 section of the Node.js custom instrumentation documentation.

Adding custom measures to tests

Just like tags, you can add custom measures to your tests by using the current active span:

  it('sum function can sum', () => {
    const testSpan = require('dd-trace').scope().active()
    testSpan.setTag('memory_allocations', 16)
    // test continues normally
    // ...
  })

For more information about custom measures, see the Add Custom Measures Guide.

Mocha ECMAScript modules (ESM)

Mocha >=9.0.0 uses an ESM-first approach to load test files. Set NODE_OPTIONS to -r dd-trace/ci/init --import dd-trace/register.js to get full visibility into your tests. See dd-trace-js ESM support for more information.

Set the NODE_OPTIONS environment variable to -r dd-trace/ci/init. Run your tests as you normally would, specifying the environment where the tests are run in the DD_ENV environment variable. For example, set DD_ENV to local when running tests on a developer workstation, or ci when running them on a CI provider:

NODE_OPTIONS="-r dd-trace/ci/init" DD_ENV=ci DD_SERVICE=my-javascript-app yarn test

Note: If you set a value for NODE_OPTIONS, make sure it does not overwrite -r dd-trace/ci/init. This can be done using the ${NODE_OPTIONS:-} clause:

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" jest"
  }
}

Adding custom tags to tests

You can add custom tags to your tests by using the custom annotations API from Playwright:

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',
  });
  // ...
});

test('landing page', async ({ page }) => {
  test.info().annotations.push({
    type: 'DD_TAGS[test.cpu.usage]',
    description: 'high',
  });
  // ...
});

The format of the annotations is the following, where $TAG_NAME and $TAG_VALUE are strings representing tag name and value respectively:

{
  "type": "DD_TAGS[$TAG_NAME]",
  "description": "$TAG_VALUE"
}

Adding custom measures to tests

Custom measures also use custom annotations:

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:

{
  "type": "DD_TAGS[$TAG_NAME]",
  "description": $TAG_VALUE
}

Note: description values in annotations are typed as strings. Numbers also work, but you may need to disable the typing error with // @ts-expect-error.

Set the NODE_OPTIONS environment variable to -r dd-trace/ci/init. Run your tests as you normally would, specifying the environment where the tests are run in the DD_ENV environment variable. For example, set DD_ENV to local when running tests on a developer workstation, or ci when running them on a CI provider:

NODE_OPTIONS="-r dd-trace/ci/init" DD_ENV=ci DD_SERVICE=my-javascript-app yarn test

Note: If you set a value for NODE_OPTIONS, make sure it does not overwrite -r dd-trace/ci/init. This can be done using the ${NODE_OPTIONS:-} clause:

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" jest"
  }
}

Adding custom tags to tests

You can add custom tags to your test by grabbing the current active span:

  When('the function is called', function () {
    const stepSpan = require('dd-trace').scope().active()
    testSpan.setTag('team_owner', 'my_team')
    // test continues normally
    // ...
  })

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 section of the Node.js custom instrumentation documentation.

Adding custom measures to tests

You may also add custom measures to your test by grabbing the current active span:

  When('the function is called', function () {
    const stepSpan = require('dd-trace').scope().active()
    testSpan.setTag('memory_allocations', 16)
    // test continues normally
    // ...
  })

For more information about custom measures, see the Add Custom Measures Guide.

Cypress version 10 or later

Use the Cypress API documentation to learn how to use plugins for cypress>=10.

In your cypress.config.js file, set the following:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents: require('dd-trace/ci/cypress/plugin'),
    supportFile: 'cypress/support/e2e.js'
  }
})

Add the following line to the top level of your supportFile:

// Your code can be before this line
// require('./commands')
require('dd-trace/ci/cypress/support')
// Also supported:
// import 'dd-trace/ci/cypress/support'
// Your code can also be after this line
// Cypress.Commands.add('login', (email, pw) => {})

If you’re using other Cypress plugins, your cypress.config.js file should contain the following:

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // your previous code is before this line
      require('dd-trace/ci/cypress/plugin')(on, config)
    }
  }
})

Cypress after:run event

Datadog requires the after:run 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':

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      require('dd-trace/ci/cypress/plugin')(on, config)
      // other plugins
      on('after:run', (details) => {
        // other 'after:run' handlers
        // important that this function call is returned
        return require('dd-trace/ci/cypress/after-run')(details)
      })
    }
  }
})

Cypress after:spec event

Datadog requires the after:spec 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':

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      require('dd-trace/ci/cypress/plugin')(on, config)
      // other plugins
      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-spec')(...args)
      })
    }
  }
})

Cypress before version 10

These are the instructions if you’re using a version older than cypress@10. See the Cypress documentation for more information about migrating to a newer version.

1. Set pluginsFile to "dd-trace/ci/cypress/plugin", for example, through cypress.json:

{
  "pluginsFile": "dd-trace/ci/cypress/plugin"
}

If you already defined a pluginsFile, initialize the instrumentation with:

module.exports = (on, config) => {
  // your previous code is before this line
  require('dd-trace/ci/cypress/plugin')(on, config)
}

2. Add the following line to the top level of your supportFile:

// 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) => {})

Cypress after:run event

Datadog requires the after:run 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':

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

Cypress after:spec event

Datadog requires the after:spec 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':

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

Run your tests as you normally do, specifying the environment where test are being run (for example, local when running tests on a developer workstation, or ci when running them on a CI provider) in the DD_ENV environment variable. For example:

DD_ENV=ci DD_SERVICE=my-ui-app npm test

Adding custom tags to tests

To add additional information to your tests, such as the team owner, use cy.task('dd:addTags', { yourTags: 'here' }) in your test or hooks.

For example:

beforeEach(() => {
  cy.task('dd:addTags', {
    'before.each': 'certain.information'
  })
})
it('renders a hello world', () => {
  cy.task('dd:addTags', {
    'team.owner': 'ui'
  })
  cy.get('.hello-world')
    .should('have.text', '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 section of the Node.js custom instrumentation documentation.

Adding custom measures to tests

To add custom measures to your tests, such as memory allocations, use cy.task('dd:addTags', { yourNumericalTags: 1 }) in your test or hooks.

For example:

it('renders a hello world', () => {
  cy.task('dd:addTags', {
    'memory_allocations': 16
  })
  cy.get('.hello-world')
    .should('have.text', 'Hello World')
})

For more information about custom measures, see the Add Custom Measures Guide.

Cypress - RUM integration

If the browser application being tested is instrumented using Browser Monitoring, 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.

vitest and dd-trace require Node.js>=18.19 or Node.js>=20.6 to work.

Set the NODE_OPTIONS environment variable to --import dd-trace/register.js -r dd-trace/ci/init. Run your tests as you normally would, specifying the environment where the tests are run in the DD_ENV environment variable. For example, set DD_ENV to local when running tests on a developer workstation, or ci when running them on a CI provider:

NODE_OPTIONS="--import dd-trace/register.js -r dd-trace/ci/init" DD_ENV=ci DD_SERVICE=my-javascript-app yarn test

Note: If you set a value for NODE_OPTIONS, make sure it does not overwrite --import dd-trace/register.js -r dd-trace/ci/init. This can be done using the ${NODE_OPTIONS:-} clause:

{
  "scripts": {
    "test": "NODE_OPTIONS=\"--max-old-space-size=12288 ${NODE_OPTIONS:-}\" vitest run"
  }
}

Adding custom tags or measures to tests

Not supported.