Uploading JUnit test report files to Datadog

The selected Datadog site () is not supported.

Note: Datadog recommends the native instrumentation of tests over uploading JUnit XML files, as the native instrumentation provides more accurate time results, supports distributed traces on integration tests, and supports structured stack traces.

JUnit test report files are XML files that contain test execution information, such as test and suite names, pass or fail status, duration, and sometimes error logs. Although introduced by the JUnit testing framework, many other popular frameworks are able to output results using this format.

If your testing framework can generate JUnit XML test reports, you can use these as a lightweight alternative to instrumenting your tests natively using Datadog tracers. Test results imported from JUnit XML reports appear alongside test data reported by tracers.

Installing the Datadog CI CLI

Install the datadog-ci CLI globally using npm:

npm install -g @datadog/datadog-ci

Standalone binary (beta)

Note: The standalone binaries are in beta and their stability is not guaranteed.

If installing NodeJS in the CI is an issue, standalone binaries are provided with Datadog CI releases. Only linux-x64, darwin-x64 (MacOS) and win-x64 (Windows) are supported. To install, run the following from your terminal:

curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_linux-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci

Then run any command with datadog-ci:

datadog-ci version
curl -L --fail "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_darwin-x64" --output "/usr/local/bin/datadog-ci" && chmod +x /usr/local/bin/datadog-ci

Then run any command with datadog-ci:

datadog-ci version
Invoke-WebRequest -Uri "https://github.com/DataDog/datadog-ci/releases/latest/download/datadog-ci_win-x64.exe" -OutFile "datadog-ci.exe"

Then run any command with Start-Process -FilePath "datadog-ci.exe":

Start-Process -FilePath "./datadog-ci.exe" -ArgumentList version

Uploading test reports

To upload your JUnit XML test reports to Datadog, run the following command, specifying the name of the service or library that was tested using the --service parameter, and one or more file paths to either the XML report files directly or directories containing them:

datadog-ci junit upload --service <service_name> <path> [<path> ...]

Specify a valid Datadog API key in the DATADOG_API_KEY environment variable, and the environment where tests were run (for example, local when uploading results from a developer workstation, or ci when uploading them from a CI provider) in the DD_ENV environment variable. For example:

DD_ENV=ci DATADOG_API_KEY=<api_key> DATADOG_SITE= datadog-ci junit upload \
  --service my-api-service \
  unit-tests/junit-reports e2e-tests/single-report.xml

Note: Reports larger than 250 MiB may not be process completely resulting in missing tests or logs. For the best experience ensure that the reports are under 250 MiB.

Configuration settings

This is the full list of options available when using the datadog-ci junit upload command:

--service (Required)
Name of the service or library under test.
Environment variable: DD_SERVICE
Example: my-api-service
Environment where tests were run.
Environment variable: DD_ENV
Example: ci
Key-value pairs in the form key:value to be attached to all tests (the --tags parameter can be specified multiple times). When specifying tags using DD_TAGS, separate them using commas (for example, team:backend,priority:high).
Environment variable: DD_TAGS
Default: (none)
Example: team:backend
Note: Tags specified using --tags and with the DD_TAGS environment variable are merged. If the same key appears in both --tags and DD_TAGS, the value in the environment variable DD_TAGS takes precedence.
--logs (beta)
Enable forwarding content from the XML reports as Logs. The content inside <system-out>, <system-err>, and <failure> is collected as logs. Logs from elements inside a <testcase> are automatically connected to the test.
Default: false
Note: Logs are billed separately from CI Visibility.
The number of concurrent uploads to the API.
Default: 20
Runs the command without actually uploading the file to Datadog. All other checks are performed.
Default: false
Positional arguments
The file paths or directories in which the JUnit XML reports are located. If you pass a directory, the CLI looks for all .xml files in it.

The following environment variables are supported:

Datadog API key used to authenticate the requests.
Default: (none)

Additionally, configure the Datadog site to use the selected one ():

The Datadog site to upload results to.
Default: datadoghq.com
Selected site:

Collecting repository and commit metadata

Datadog uses Git information for visualizing your test results and grouping them by repository and commit. Git metadata is collected by the Datadog CI CLI from CI provider environment variables and the local .git folder in the project path, if available. To read this directory, the git binary is required.

If you are running tests in non-supported CI providers or with no .git folder, you can set the Git information manually using environment variables. These environment variables take precedence over any auto-detected information. Set the following environment variables to provide Git information:

URL of the repository where the code is stored. Both HTTP and SSH URLs are supported.
Example: git@github.com:MyCompany/MyApp.git, https://github.com/MyCompany/MyApp.git
Git branch being tested. Leave empty if providing tag information instead.
Example: develop
Git tag being tested (if applicable). Leave empty if providing branch information instead.
Example: 1.0.1
Full commit hash.
Example: a18ebf361cc831f5535e58ec4fae04ffd98d8152
Commit message.
Example: Set release number
Commit author name.
Example: John Smith
Commit author email.
Example: john@example.com
Commit author date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z
Commit committer name.
Example: Jane Smith
Commit committer email.
Example: jane@example.com
Commit committer date in ISO 8601 format.
Example: 2021-03-12T16:00:28Z

Collecting environment configuration metadata

Datadog uses special dedicated tags to identify the configuration of the environment in which tests run, including the operating system, runtime, and device information, if applicable. When the same test for the same commit runs in more than one configuration (for example, on Windows and on Linux), the tags are used to differentiate the test in failure and flakiness detection.

You can specify these special tags using the --tags parameter when calling datadog-ci junit upload, or by setting the DD_TAGS environment variable.

All of these tags are optional, and only the ones you specify will be used to differentiate between environment configurations.

Used to execute groups of test suites separately.
Examples: ApplicationUITests, ModelTests
Name of the operating system.
Examples: windows, linux, darwin
Version of the operating system.
Examples: 10.15.4, 14.3.2, 95
Architecture of the operating system.
Examples: x64, x86, arm64
Name of the language interpreter or programming runtime.
Examples: .NET, .NET Core, OpenJDK Runtime Environment, Java(TM) SE Runtime Environment, CPython
Version of the runtime.
Examples: 5.0.0, 3.1.7
Name of the runtime vendor where applicable. For example, when using a Java runtime.
Examples: AdoptOpenJDK, Oracle Corporation
Architecture of the runtime.
Examples: x64, x86, arm64

For mobile apps (Swift, Android):

The model of the device being tested.
Examples: iPhone11,4, AppleTV5,3
The name of the device being tested.
Examples: iPhone 12 Pro Simulator, iPhone 13 (QA team)

Providing metadata through <property> elements

In addition to the --tags CLI parameter and the DD_TAGS environment variable, which apply custom tags globally to all tests included the uploaded XML report, you can provide additional tags to specific tests by including <property name="dd_tags[key]" value="value"> elements within the <testsuite> or <testcase> elements. If you add these tags to a <testcase> element, they are stored in its test span. If you add the tags to a <testsuite> element, they are stored in all of that suite’s test spans.

To be processed, the name attribute in the <property> element must have the format dd_tags[key], where key is the name of the custom tag to be added. Other properties are ignored.

Example: Adding tags to a <testcase> element

<?xml version="1.0" encoding="UTF-8"?>
  <testsuite tests="1" failures="0" time="0.030000" name="SomeTestSuiteClass">
    <testcase classname="SomeTestSuiteClass" name="test_something" time="0.010000">
        <property name="dd_tags[custom_tag]" value="some value"></property>
        <property name="dd_tags[runtime.name]" value="CPython"></property>

Example: Adding tags to a <testsuite> element

<?xml version="1.0" encoding="UTF-8"?>
  <testsuite tests="1" failures="0" time="0.030000" name="SomeTestSuiteClass">
      <property name="dd_tags[custom_tag]" value="some value"></property>
      <property name="dd_tags[runtime.name]" value="CPython"></property>
    <testcase classname="SomeTestSuiteClass" name="test_something" time="0.010000"></testcase>

Further reading