Configuring Go with Buildkite Test Engine

To use Buildkite Test Engine with your Go language projects, either use the Tests Buildkite plugin to run go test through bktec, or use gotestsum to generate JUnit XML files and upload them to Buildkite Test Engine.

Recommended setup

The recommended way to set up a new test suite is to add the Tests Buildkite plugin to the step that runs your tests. It works with every runner that bktec supports, and the entire setup is configuration-only — you can get a test suite running through changes to pipeline.yml alone, with no modifications to your application code.

Use the language-specific test collector documented on this page when you want deeper framework integration — such as custom execution tags, span annotations, or richer per-framework data. Language-specific collectors still pair well with the Tests Buildkite plugin, but adding one requires changes to your application code.

Tests Buildkite plugin example for Go test

The following step uses the Tests Buildkite plugin to run gotestsum through bktec. The plugin downloads bktec, requests an OIDC token, ensures the test suite exists, and exports the environment variables that bktec expects, so the step's command only needs to invoke bktec run:

steps:
  - label: "Go test"
    command: bktec run
    plugins:
      - tests#v1.0.0:
          test-runner: gotest
          result-path: gotest-results.xml
    parallelism: 4

See the Tests Buildkite plugin page for the full plugin reference, including all supported options and dynamic parallelism with bktec plan.

Uploading JUnit XML with gotestsum

If you want to use the JUnit XML import path instead of the Tests Buildkite plugin:

  1. Install gotestsum:

    go install gotest.tools/gotestsum@latest

  2. Use gotestsum to run your tests and output JUnit XML, by replacing go test with gotestsum, for example:

    gotestsum --junitfile junit.xml ./...

  3. Upload the JUnit.xml to Buildkite:

    curl \
  -X POST \
  --fail-with-body \
  -H "Authorization: Token token=\"$BUILDKITE_ANALYTICS_TOKEN\"" \
  -F "data=@junit.xml" \
  -F "format=junit" \
  -F "run_env[CI]=buildkite" \
  -F "run_env[key]=$BUILDKITE_BUILD_ID" \
  -F "run_env[number]=$BUILDKITE_BUILD_NUMBER" \
  -F "run_env[job_id]=$BUILDKITE_JOB_ID" \
  -F "run_env[branch]=$BUILDKITE_BRANCH" \
  -F "run_env[commit_sha]=$BUILDKITE_COMMIT" \
  -F "run_env[message]=$BUILDKITE_MESSAGE" \
  -F "run_env[url]=$BUILDKITE_BUILD_URL" \
  https://analytics-api.buildkite.com/v1/uploads

See gotestsum for full documentation of its features and command-line flags.