---
title: Go Tests
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: Docs > Test Optimization in Datadog > Configure Test Optimization > Go Tests
---

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Go Tests

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

## Compatibility{% #compatibility %}

Supported test frameworks:

- `testing` package
- [Testify](https://github.com/stretchr/testify) suites

`ddtest instrument` requires a Go 1.25 or later toolchain and runs on Linux, macOS, and Windows. The `go.mod` file of your project can declare Go 1.21 or later. If your project depends on `github.com/DataDog/dd-trace-go/v2`, use v2.10.0 or later.

{% alert level="info" %}
If you use Bazel to run Go tests, use the Datadog [Bazel rules for Go tests](https://docs.datadoghq.com/tests/setup/bazel/go.md).
{% /alert %}

## Configuring reporting method{% #configuring-reporting-method %}

To report test results to Datadog, configure how `ddtest instrument` sends them:

{% tab title="CI Provider with Auto-Instrumentation Support" %}
We support auto-instrumentation for the following CI providers:

| CI Provider    | Auto-Instrumentation method                                                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub Actions | [Datadog Test Visibility Github Action](https://github.com/marketplace/actions/configure-datadog-test-visibility)                                     |
| Jenkins        | [UI-based configuration](https://docs.datadoghq.com/continuous_integration/pipelines/jenkins.md#enable-test-optimization) with Datadog Jenkins plugin |
| GitLab         | [Datadog Test Visibility GitLab Script](https://github.com/DataDog/test-visibility-gitlab-script)                                                     |
| CircleCI       | [Datadog Test Visibility CircleCI Orb](https://circleci.com/orbs/registry/orb/datadog/test-visibility-circleci-orb)                                   |

Auto-instrumentation runs on the CI executor and does not automatically apply to tests in a separate container. Before using it for containerized tests, see [Tests in Containers](https://docs.datadoghq.com/tests/containers.md#choose-an-instrumentation-method).

If the auto-instrumentation step configures the process that runs your tests, you can skip the rest of the setup steps below.
{% /tab %}

{% tab title="Cloud CI Provider" %}
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:

{% alert level="warning" %}
Set these variables before starting the test process. For parallel test runners, set them on the parent process so every worker inherits them.

`DD_CIVISIBILITY_AGENTLESS_ENABLED=true` selects Agentless mode. `DD_API_KEY` provides authentication but does not enable Agentless mode.
{% /alert %}

{% dl %}

{% dt %}
`DD_CIVISIBILITY_AGENTLESS_ENABLED=true` (Required for Agentless mode)
{% /dt %}

{% dd %}
Enables Agentless mode to send test results directly to Datadog. **Default**: `false`
{% /dd %}

{% dt %}
`DD_API_KEY` (Required for Agentless mode)
{% /dt %}

{% dd %}
The [Datadog API key](https://app.datadoghq.com/organization-settings/api-keys) used to authenticate test result uploads. **Default**: `(empty)`
{% /dd %}

{% /dl %}

If you use a Datadog site other than US1, set the following variable:

{% dl %}

{% dt %}
`DD_SITE` (Optional for Agentless mode)
{% /dt %}

{% dd %}
The [Datadog site](https://docs.datadoghq.com/getting_started/site.md) to upload results to. **Default**: `datadoghq.com` 
{% /dd %}

{% /dl %}

{% /tab %}

{% tab title="On-Premises CI Provider" %}
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](https://docs.datadoghq.com/agent.md). This is the recommended option as it allows you to automatically link test results to [logs](https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces.md) and [underlying host metrics](https://docs.datadoghq.com/infrastructure.md).

If you are using a Kubernetes executor, Datadog recommends using the [Datadog Operator](https://docs.datadoghq.com/containers/datadog_operator.md). The operator includes [Datadog Admission Controller](https://docs.datadoghq.com/agent/cluster_agent/admission_controller.md) which can automatically [inject the tracer library](https://docs.datadoghq.com/tracing/trace_collection/library_injection_local.md?tab=kubernetes) into the build pods. **Note:** If you use the Datadog Operator, there is no need to download and inject the tracer library since the Admission Controller can do this for you, so you can skip the corresponding step below. However, you still need to make sure that your pods set the environment variables or command-line parameters necessary to enable Test Visibility.

If you are not using Kubernetes or can't use the Datadog Admission Controller and the CI provider is using a container-based executor, set the `DD_TRACE_AGENT_URL` environment variable (which defaults to `http://localhost:8126`) in the build container running the tracer to an endpoint that is accessible from within that container. **Note:** Using `localhost` inside the build references the container itself and not the underlying worker node or any container where the Agent might be running in.

`DD_TRACE_AGENT_URL` includes the protocol and port (for example, `http://localhost:8126`) and takes precedence over `DD_AGENT_HOST` and `DD_TRACE_AGENT_PORT`, and is the recommended configuration parameter to configure the Datadog Agent's URL for CI Visibility.

If you still have issues connecting to the Datadog Agent, use the Agentless Mode. **Note:** When using this method, tests are not correlated with [logs](https://docs.datadoghq.com/tracing/other_telemetry/connect_logs_and_traces.md) and [infrastructure metrics](https://docs.datadoghq.com/infrastructure.md).
{% /tab %}

## Installing ddtest{% #installing-ddtest %}

`ddtest` is a Datadog command-line tool. Its `ddtest instrument` command adds Test Optimization to Go tests at compilation time, without adding dependencies to your project or changing your source code or `go.mod` file.

Install `ddtest` from its [latest release](https://github.com/DataDog/ddtest/releases/latest):

```bash
curl -fsSL https://github.com/DataDog/ddtest/releases/latest/download/install.sh | bash
```

In PowerShell, run:

```powershell
irm https://github.com/DataDog/ddtest/releases/latest/download/install.ps1 | iex
```

The install scripts place the executable in `~/.local/bin` and check it against the `SHA256SUMS` file of the release. Add this directory to your `PATH`. In GitHub Actions, the scripts add it for later steps.

To pin a release in CI, pass `--version`:

```bash
curl -fsSL https://github.com/DataDog/ddtest/releases/latest/download/install.sh | bash -s -- --version v1.14.0
```

## Instrumenting tests{% #instrumenting-tests %}

To configure `ddtest instrument`, set the following environment variables before starting the test process. For parallel test runners, set them on the parent process so every worker inherits them.

{% dl %}

{% dt %}
`DD_SERVICE` (Optional)
{% /dt %}

{% dd %}
Name of the service or library under test. **Default**: The repository name
{% /dd %}

{% dt %}
`DD_ENV` (Optional)
{% /dt %}

{% dd %}
Name of the environment where tests are being run. **Default**: `(empty)` **Examples**: `local`, `ci`
{% /dd %}

{% dt %}
`DD_CIVISIBILITY_AGENTLESS_ENABLED=true` (Required for Agentless mode)
{% /dt %}

{% dd %}
Enables Agentless mode to send test results directly to Datadog. **Default**: `false`
{% /dd %}

{% dt %}
`DD_API_KEY` (Required for Agentless mode)
{% /dt %}

{% dd %}
The Datadog API key used to authenticate test result uploads. This variable does not enable Agentless mode. **Default**: `(empty)`
{% /dd %}

{% dt %}
`DD_SITE` (Optional for Agentless mode)
{% /dt %}

{% dd %}
The [Datadog site](https://docs.datadoghq.com/getting_started/site.md) to upload test results to. Set this configuration when using a site other than US1. **Default**: `datadoghq.com`
{% /dd %}

{% dt %}
`DD_TRACE_AGENT_URL` (Only when using the Datadog Agent)
{% /dt %}

{% dd %}
The Datadog Agent URL for trace collection, in the form `http://hostname:port`. **Default**: `http://localhost:8126`
{% /dd %}

{% dt %}
`DD_TEST_SESSION_NAME` (Optional)
{% /dt %}

{% dd %}
Identifies a group of tests, such as `unit-tests`, `integration-tests`, or `smoke-tests`. **Default**: The CI job name and test command, or the test command if the CI job name is unavailable. **Example**: `unit-tests`, `integration-tests`, `smoke-tests`
{% /dd %}

{% /dl %}

Add `ddtest instrument` in front of your `go test` command, from the Go module that you want to test:

```bash
ddtest instrument go test -race ./...
```

The command keeps the output, exit status, and test cache of `go test`. A package whose result comes from the Go test cache does not report tests. To report every test on every run, add `-count=1`:

```bash
ddtest instrument go test -count=1 ./...
```

For more options, see the [`ddtest instrument` documentation](https://github.com/DataDog/ddtest/tree/main/ddto#readme).

### Test wrappers{% #test-wrappers %}

If you run tests with gotestsum, add `ddtest instrument` in front of the gotestsum command:

```bash
ddtest instrument gotestsum --format testname -- ./...
ddtest instrument go tool gotestsum -- ./...
```

For other commands that run `go test`, such as `make` or a script, use the `--go-shim` option:

```bash
ddtest instrument --go-shim make test
```

With `--go-shim`, only a `go` command found on `PATH` reports test results. A script that runs `$GOROOT/bin/go` by its full path, or that sets its own `PATH`, runs `go test` without Test Optimization.

### Migrating from Orchestrion{% #migrating-from-orchestrion %}

If you run tests with `orchestrion go test`, replace the command with `ddtest instrument go test`. If you only use Orchestrion for Test Optimization, you can also delete the `orchestrion.tool.go` file and remove the Orchestrion requirement from `go.mod`.

If you also use Orchestrion to trace the application under test, first upgrade `github.com/DataDog/dd-trace-go/v2` to v2.10.0 or later. Keep Orchestrion and add `ddtest instrument` in front of the command:

```bash
ddtest instrument orchestrion go test ./...
```

`ddtest instrument` reports the tests, and Orchestrion instruments the application. By default, `dd-trace-go` spans created during a test join the trace of the test and go to Test Optimization only. To also send them to APM, set `DD_CIVISIBILITY_APM_SPANS_ENABLED=true`.

## Known limitations{% #known-limitations %}

- A `go test` command that names test files directly, such as `go test foo_test.go`, runs without instrumentation and prints a warning.
- Tests of the Go standard library are not supported.

## Further reading{% #further-reading %}

Additional helpful documentation, links, and articles:

- [Forwarding Environment Variables for Tests in Containers](https://docs.datadoghq.com/continuous_integration/tests/containers.md)
- [Explore Test Results and Performance](https://docs.datadoghq.com/continuous_integration/tests.md)
- [Speed up your test jobs with Test Impact Analysis](https://docs.datadoghq.com/tests/test_impact_analysis/go.md)
- [Troubleshooting CI Visibility](https://docs.datadoghq.com/continuous_integration/troubleshooting.md)