This product is not supported for your selected Datadog site. ().
이 페이지는 아직 영어로 제공되지 않습니다. 번역 작업 중입니다. 현재 번역 프로젝트에 대한 질문이나 피드백이 있으신 경우 언제든지 연락주시기 바랍니다.
Compatibility
Supported test frameworks:
Test Framework
Version
Notes
Jest
>= 24.8.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.
Jenkins 또는 자체 관리형 GitLab CI와 같은 온프레미스 CI 공급자에서 테스트를 실행하는 경우, 에이전트 설치 지침에 따라 각 작업자 노드에 Datadog 에이전트를 설치합니다.
자동으로 테스트 결과를 로그와 기본 호트스 메트릭과 연결할 수 있기 때문에 이 옵션을 추천합니다.
쿠버네티스 실행기를 사용하는 경우 Datadog에서는 Datadog 연산자를 사용할 것을 권고합니다.
연산자에는 Datadog 허용 제어기가 포함되어 있어 빌드 파드에 자동으로 추적기 라이브러리를 삽입합니다.
참고: Datadog 연산자를 사용할 경우 허용 제어기가 작업을 해주기 때문에 추적기 라이브러리를 다운로드 받고 삽입할 필요가 없습니다. 따라서 아래 해당 단계를 건너뛰어도 됩니다.
그러나 테스트 가시화 기능을 사용할 때 필요한 파드의 환경 변수나 명령줄 파라미터는 설정해야 합니다.
쿠버네티스를 사용하지 않거나 Datadog 허용 제어기를 사용할 수 없고 CI 공급자가 컨테이너 기반 실행기를 사용하는 경우, 추적기를 실행하는 빌드 컨테이너에서 환경 변수 DD_TRACE_AGENT_URL(기본값 http://localhost:8126)를 해당 컨테이너 내에서 액세스할 수 있는 엔드포인트로 설정합니다. 참고: 빌드 내에서 localhost를 사용하면 기본 작업자 노드나 에이전트를 실행하는 컨테이너를 참조하지 않고 컨테이너 자체를 참조합니다.
DD_TRACE_AGENT_URL 은 프로토콜과 포트(예: http://localhost:8126)를 포함하고 DD_AGENT_HOST과 DD_TRACE_AGENT_PORT보다 우선하며, CI Visibility를 위해 Datadog 에이전트의 URL을 설정하는 데 권장되는 설정 파라미터입니다.
Datdog 에이전트에 연결하는 데 아직 문제가 있다면 에이전트리스 모드를 사용해 보세요.
참고: 이 방법을 사용할 경우 테스트가 로그 및 인프라스트럭처 메트릭과 상관 관계를 수립하지 않습니다.
Set the NODE_OPTIONS environment variable to -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:
NODE_OPTIONS="-r dd-trace/ci/init"DD_TEST_SESSION_NAME=unit-tests 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:
You can add custom tags to your tests by using the current active span:
it('sum function can sum',()=>{consttestSpan=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',()=>{consttestSpan=require('dd-trace').scope().active()testSpan.setTag('memory_allocations',16)// test continues normally
// ...
})
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, optionally specifying a name for your test session with DD_TEST_SESSION_NAME:
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:
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:
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.
Important: The DD_TAGS prefix is mandatory and case sensitive.
Playwright - RUM integration
If the browser application being tested is instrumented using Browser Monitoring, 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.
Set the NODE_OPTIONS environment variable to -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:
You can add custom tags to your test by grabbing the current active span:
When('the function is called',function(){conststepSpan=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(){conststepSpan=require('dd-trace').scope().active()testSpan.setTag('memory_allocations',16)// test continues normally
// ...
})
Add the following line to the top level of your supportFile:
cypress/support/e2e.js
// 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:
cypress.config.js
const{defineConfig}=require('cypress')module.exports=defineConfig({e2e:{setupNodeEvents(on,config){// your previous code is before this line
returnrequire('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':
cypress.config.js
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
returnrequire('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':
cypress.config.js
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
returnrequire('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.
If you already defined a pluginsFile, initialize the instrumentation with:
cypress/plugins/index.js
module.exports=(on,config)=>{// your previous code is before this line
returnrequire('dd-trace/ci/cypress/plugin')(on,config)}
Add the following line to the top level of your supportFile:
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) => {})
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':
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
returnrequire('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':
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
returnrequire('dd-trace/ci/cypress/after-run')(...args)})}
Run your tests as you normally would, optionally specifying a name for your test session with DD_TEST_SESSION_NAME:
DD_TEST_SESSION_NAME=ui-tests yarn test:ui
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')})
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.
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.
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:
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:
Note: This does not work because NODE_OPTIONS are interpreted by every node process, including npm install. If you try to import dd-trace/ci/init before it’s installed, this step fails.
Make sure the NODE_OPTIONS environment variable is only set to the process running tests.
Specifically avoid defining NODE_OPTIONS in the global environment variables settings in your pipeline or job definition.
Using Yarn 2 or later
If you’re using yarn>=2 and a .pnp.cjs file, you might also get the same error:
Error: Cannot find module 'dd-trace/ci/init'
You can fix it by setting NODE_OPTIONS to the following:
NODE_OPTIONS="-r $(pwd)/.pnp.cjs -r dd-trace/ci/init" yarn test
Reporting code coverage
When tests are instrumented with Istanbul, the Datadog Tracer (v3.20.0 or later) reports it under the test.code_coverage.lines_pct tag for your test sessions.
You can see the evolution of the test coverage in the Coverage tab of a test session.
The following is a list of the most important configuration settings that can be used with the tracer.
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) Example: unit-tests, integration-tests, smoke-tests
service
Name of the service or library under test. Environment variable: DD_SERVICE Default: (test framework name) Example: my-ui
env
Name of the environment where tests are being run. Environment variable: DD_ENV Default: none Examples: local, ci
url
Datadog Agent URL for trace collection in the form http://hostname:port. Environment variable: DD_TRACE_AGENT_URL Default: http://localhost:8126
테스트 중인 Git 브랜치입니다. 대신 태그 정보를 제공하는 경우 비워 둡니다. 예시: develop
DD_GIT_TAG
테스트 중인 Git 태그입니다(해당되는 경우). 대신 브랜치 정보를 제공하는 경우 비워 둡니다. 예시: 1.0.1
DD_GIT_COMMIT_SHA
전체 커밋 해시입니다. 예시: a18ebf361cc831f5535e58ec4fae04ffd98d8152
DD_GIT_COMMIT_MESSAGE
커밋 메시지입니다. 예시: Set release number
DD_GIT_COMMIT_AUTHOR_NAME
커밋 작성자 이름입니다. 예시: John Smith
DD_GIT_COMMIT_AUTHOR_EMAIL
커밋 작성자 이메일입니다. 예시: john@example.com
DD_GIT_COMMIT_AUTHOR_DATE
ISO 8601 형식의 커밋 작성자 날짜입니다. 예시: 2021-03-12T16:00:28Z
DD_GIT_COMMIT_COMMITTER_NAME
커밋 커미터 이름입니다. 예시: Jane Smith
DD_GIT_COMMIT_COMMITTER_EMAIL
커밋 커미터 이메일입니다. 예시: jane@example.com
DD_GIT_COMMIT_COMMITTER_DATE
ISO 8601 형식의 커밋 커미터 날짜입니다. 예시: 2021-03-12T16:00:28Z
Manual testing API
Note: The manual testing API is available starting in dd-trace versions 5.23.0 and 4.47.0.
If you use Jest, Mocha, Cypress, Playwright, Cucumber, or Vitest, do not use the manual testing API, as Test Optimization automatically instruments them and sends the test results to Datadog. The manual testing API is incompatible with already supported testing frameworks.
Use the manual testing API only if you use an unsupported testing framework or have a different testing mechanism.
The manual testing API leverages the node:diagnostics_channel module from Node.js and is based on channels you can publish to:
const{channel}=require('node:diagnostics_channel')const{describe,test,beforeEach,afterEach,assert}=require('my-custom-test-framework')consttestStartCh=channel('dd-trace:ci:manual:test:start')consttestFinishCh=channel('dd-trace:ci:manual:test:finish')consttestSuite=__filenamedescribe('can run tests',()=>{beforeEach((testName)=>{testStartCh.publish({testName,testSuite})})afterEach((status,error)=>{testFinishCh.publish({status,error})})test('first test will pass',()=>{assert.equal(1,1)})})
Test start channel
Grab this channel by its ID dd-trace:ci:manual:test:start to publish that a test is starting. A good place to do this is a beforeEach hook or similar.
const{channel}=require('node:diagnostics_channel')consttestStartCh=channel('dd-trace:ci:manual:test:start')// ... code for your testing framework goes here
beforeEach(()=>{consttestDefinition={testName:'a-string-that-identifies-this-test',testSuite:'what-suite-this-test-is-from.js'}testStartCh.publish(testDefinition)})// code for your testing framework continues here ...
The payload to be published has attributes testName and testSuite, both strings, that identify the test that is about to start.
Test finish channel
Grab this channel by its ID dd-trace:ci:manual:test:finish to publish that a test is ending. A good place to do this is an afterEach hook or similar.
const{channel}=require('node:diagnostics_channel')consttestFinishCh=channel('dd-trace:ci:manual:test:finish')// ... code for your testing framework goes here
afterEach(()=>{consttestStatusPayload={status:'fail',error: newError('assertion error')}testStartCh.publish(testStatusPayload)})// code for your testing framework continues here ...
The payload to be published has attributes status and error:
status is a string that takes one of three values:
'pass' when a test passes.
'fail' when a test fails.
'skip' when a test has been skipped.
error is an Error object containing the reason why a test failed.
Add tags channel
Grab this channel by its ID dd-trace:ci:manual:test:addTags to publish that a test needs custom tags. This can be done within the test function:
const{channel}=require('node:diagnostics_channel')consttestAddTagsCh=channel('dd-trace:ci:manual:test:addTags')// ... code for your testing framework goes here
test('can sum',()=>{testAddTagsCh.publish({'test.owner':'my-team','number.assertions':3})constresult=sum(2,1)assert.equal(result,3)})// code for your testing framework continues here ...
The payload to be published is a dictionary <string, string|number> of tags or measures that are added to the test.
Run the tests
When the test start and end channels are in your code, run your testing framework like you normally do, including the following environment variables:
Browser tests executed with mocha, jest, cucumber, cypress, playwright, and vitest are instrumented by dd-trace-js, but visibility into the browser session itself is not provided by default (for example, network calls, user actions, page loads, and more.).
If you want visibility into the browser process, consider using RUM & Session Replay. When using Cypress or 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.
Cypress interactive mode
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, are not fired. If you want to try it anyway, pass experimentalInteractiveRunEvents: true to the cypress configuration file.
Jest’s –forceExit option may cause data loss. Datadog tries to send data immediately after your tests finish, but shutting down the process abruptly can cause some requests to fail. Use --forceExit with caution.
Mocha’s --exit
Mocha’s –exit option may cause data loss. Datadog tries to send data immediately after your tests finish, but shutting down the process abruptly can cause some requests to fail. Use --exit with caution.
Best practices
Follow these practices to take full advantage of the testing framework and Test Optimization.
Parameterized tests
Whenever possible, leverage the tools that testing frameworks provide for parameterized tests. For example, for jest:
constforEach=require('mocha-each');forEach([[1,2,3],[3,4,7]]).it('adds %i and %i then returns %i',(a,b,expected)=>{expect(a+b).to.equal(expected)});
When you use this approach, both the testing framework and Test Optimization can tell your tests apart.
Test session name DD_TEST_SESSION_NAME
Use DD_TEST_SESSION_NAME to define the name of the test session and the related group of tests. Examples of values for this tag would be:
unit-tests
integration-tests
smoke-tests
flaky-tests
ui-tests
backend-tests
If DD_TEST_SESSION_NAME is not specified, the default value used is a combination of:
CI job name
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