.NET Tests

CI Visibility is not available in the selected site () at this time.

Compatibility

Supported .NET versions:

  • .NET Framework 4.6.1 and above
  • .NET Core 2.1, 3.1, .NET 5, and .NET 6

Supported test frameworks:

  • xUnit 2.2 and above
  • NUnit 3.0 and above
  • MsTestV2 14 and above

Test suite level visibility compatibility

Test suite level visibility is supported from dd-trace-dotnet>=2.16.0.

Configuring reporting method

To report test results to Datadog, you need to configure the Datadog .NET library:

    If you are running tests on an on-premises CI provider, such as Jenkins or self-managed GitLab CI, install the Datadog Agent on each worker node by following the Agent installation instructions. This is the recommended option as test results are then automatically linked to the underlying host metrics.

    If the CI provider is using a container-based executor, set the DD_AGENT_HOST environment variable on all builds (which defaults to http://localhost:8126) to an endpoint that is accessible from within build containers, as using localhost inside the build references the container itself and not the underlying worker node where the Datadog Agent is running.

    If you are using a Kubernetes executor, Datadog recommends using the Datadog Admission Controller, which automatically sets the DD_AGENT_HOST environment variable in the build pods to communicate with the local Datadog Agent.

    Agentless mode is available in Datadog .NET library versions >= 2.5.1

    If you are using a cloud CI provider without access to the underlying worker nodes, such as GitHub Actions or CircleCI, configure the library to use the Agentless mode. For this, set the following environment variables:

    DD_CIVISIBILITY_AGENTLESS_ENABLED=true (Required)
    Enables or disables Agentless mode.
    Default: false
    DD_API_KEY (Required)
    The Datadog API key used to upload the test results.
    Default: (empty)

    Additionally, configure which Datadog site to which you want to send data.

    DD_SITE (Required)
    The Datadog site to upload results to.
    Default: datadoghq.com
    Selected site:

    Installing the .NET tracer CLI

    Install or update the dd-trace command using one of the following ways:

    Instrumenting tests

    To instrument your test suite, prefix your test command with dd-trace ci run, providing the name of the service or library under test as the --dd-service parameter, and the environment where tests are being run (for example, local when running tests on a developer workstation, or ci when running them on a CI provider) as the --dd-env parameter. For example:

      By using dotnet test

      dd-trace ci run --dd-service=my-dotnet-app --dd-env=ci -- dotnet test

      By using VSTest.Console.exe

      dd-trace ci run --dd-service=my-dotnet-app --dd-env=ci -- VSTest.Console.exe {test_assembly}.dll

      All tests are automatically instrumented.

      Configuration settings

      You can change the default configuration of the CLI by using command line arguments or environment variables. For a full list of configuration settings, run:

      dd-trace ci run --help

      The following list shows the default values for key configuration settings:

      --dd-service
      Name of the service or library under test.
      Environment variable: DD_SERVICE
      Default: The repository name
      Example: my-dotnet-app
      --dd-env
      Name of the environment where tests are being run.
      Environment variable: DD_ENV
      Default: none
      Examples: local, ci
      --agent-url
      Datadog Agent URL for trace collection in the form http://hostname:port.
      Environment variable: DD_TRACE_AGENT_URL
      Default: http://localhost:8126

      All other Datadog Tracer configuration options can also be used.

      Adding custom tags to tests

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

      // inside your test
var scope = Tracer.Instance.ActiveScope; // from Datadog.Trace;
if (scope != null) {
    scope.Span.SetTag("test_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 .NET custom instrumentation documentation.

      Collecting Git metadata

      Datadog uses Git information for visualizing your test results and grouping them by repository, branch, and commit. Git metadata is automatically collected by the test instrumentation from CI provider environment variables and the local .git folder in the project path, if available.

      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:

      DD_GIT_REPOSITORY_URL
      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
      DD_GIT_BRANCH
      Git branch being tested. Leave empty if providing tag information instead.
      Example: develop
      DD_GIT_TAG
      Git tag being tested (if applicable). Leave empty if providing branch information instead.
      Example: 1.0.1
      DD_GIT_COMMIT_SHA
      Full commit hash.
      Example: a18ebf361cc831f5535e58ec4fae04ffd98d8152
      DD_GIT_COMMIT_MESSAGE
      Commit message.
      Example: Set release number
      DD_GIT_COMMIT_AUTHOR_NAME
      Commit author name.
      Example: John Smith
      DD_GIT_COMMIT_AUTHOR_EMAIL
      Commit author email.
      Example: john@example.com
      DD_GIT_COMMIT_AUTHOR_DATE
      Commit author date in ISO 8601 format.
      Example: 2021-03-12T16:00:28Z
      DD_GIT_COMMIT_COMMITTER_NAME
      Commit committer name.
      Example: Jane Smith
      DD_GIT_COMMIT_COMMITTER_EMAIL
      Commit committer email.
      Example: jane@example.com
      DD_GIT_COMMIT_COMMITTER_DATE
      Commit committer date in ISO 8601 format.
      Example: 2021-03-12T16:00:28Z

      Custom instrumentation

      Note: Your custom instrumentation setup depends on the dd-trace version. To use the custom instrumentation, you must keep the package versions for dd-trace and Datadog.Trace NuGet packages in sync.

      To use the custom instrumentation in your .NET application:

      1. Execute dd-trace --version to get the version of the tool.
      2. Add the Datadog.Trace NuGet package with the same version to your application.
      3. In your application code, access the global tracer through the Datadog.Trace.Tracer.Instance property to create new spans.

      For more information about how to add spans and tags for custom instrumentation, see the .NET Custom Instrumentation documentation.

      Information collected

      When CI Visibility is enabled, the following data is collected from your project:

      • Test names and durations.
      • Predefined environment variables set by CI providers.
      • Git commit history including the hash, message, author information, and files changed (without file contents).
      • Information from the CODEOWNERS file.

      In addition to that, if Intelligent Test Runner is enabled, the following data is collected from your project:

      • Code coverage information, including file names and line numbers covered by each test.

      Further reading

      Additional helpful documentation, links, and articles:

      Forwarding Environment Variables for Tests in ContainersDOCUMENTATION more more Explore Test Results and PerformanceDOCUMENTATION more more Troubleshooting CIDOCUMENTATION more more