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 (必須)

Agentless モードを有効または無効にします。
デフォルト: false

DD_API_KEY (必須)

テスト結果のアップロードに使用される Datadog API キー。
デフォルト: (empty)

さらに、データを送信する Datadog サイトを構成します。

DD_SITE (必須)

結果をアップロードする Datadog サイト。
デフォルト: datadoghq.com

Jenkins や自己管理型の GitLab CI など、オンプレミスの CI プロバイダーでテストを実行している場合は、Agent のインストール手順に従って、各ワーカーノードに Datadog Agent をインストールします。 これは、テスト結果をログおよび基盤となるホストのメトリクスに自動的にリンクできるため、推奨されるオプションです。

Kubernetes エグゼキュータを使用している場合は、Datadog が Datadog Operator の使用を推奨しています。 この Operator には Datadog Admission Controller が含まれており、自動的にビルドポッドにトレーサーライブラリを注入 することができます。 注: Datadog Operator を使用する場合、Admission Controller がトレーサーライブラリのダウンロードと注入を行うため、以下のステップを省略することができます。 ただし、Test Visibility を有効にするために必要な環境変数またはコマンドラインパラメーターをポッドで設定する必要があります。

Kubernetes を使用していない、または Datadog Admission Controller を使用できない場合で、CI プロバイダーがコンテナベースのエクゼキュータを使用している場合、トレーサーを実行するビルドコンテナの DD_TRACE_AGENT_URL 環境変数 (デフォルトは http://localhost:8126) を、そのコンテナ内からアクセス可能なエンドポイントに設定します。注: ビルドコンテナ内で localhost を使用すると、コンテナ自体を参照し、基盤となるワーカーノードや Container Agent が動作しているコンテナを参照しません。

DD_TRACE_AGENT_URL は、プロトコルとポート (例えば、http://localhost:8126) を含み、DD_AGENT_HOST と DD_TRACE_AGENT_PORT よりも優先され、CI Visibility のために Datadog Agent の URL を構成するために推奨される構成パラメーターです。

それでも Datadog Agent への接続に問題がある場合は、Agentless Mode を使用してください。 注: この方法を使用する場合、テストはログやインフラストラクチャーメトリクスと相関しません。

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.