• Install Buildkite Test Engine Client (bktec) in your testing environment.

  Ensure you have curl and gpg installed first:

  apt update && apt install curl gpg -y

  Install the registry signing key:

  curl -fsSL "https://packages.buildkite.com/buildkite/test-engine-client-deb/gpgkey" | gpg --dearmor -o /etc/apt/keyrings/buildkite_test-engine-client-deb-archive-keyring.gpg

  Configure the registry:

  echo -e "deb [signed-by=/etc/apt/keyrings/buildkite_test-engine-client-deb-archive-keyring.gpg] https://packages.buildkite.com/buildkite/test-engine-client-deb/any/ any main\ndeb-src [signed-by=/etc/apt/keyrings/buildkite_test-engine-client-deb-archive-keyring.gpg] https://packages.buildkite.com/buildkite/test-engine-client-deb/any/ any main" > /etc/apt/sources.list.d/buildkite-buildkite-test-engine-client-deb.list

  Install the package:

  apt update && apt install bktec

  Configure the registry:

  echo -e "[test-engine-client-rpm]\nname=Test Engine Client - rpm\nbaseurl=https://packages.buildkite.com/buildkite/test-engine-client-rpm/rpm_any/rpm_any/\$basearch\nenabled=1\nrepo_gpgcheck=1\ngpgcheck=0\ngpgkey=https://packages.buildkite.com/buildkite/test-engine-client-rpm/gpgkey\npriority=1" > /etc/yum.repos.d/test-engine-client-rpm.repo

  Install the package:

  dnf install -y bktec

  bktec is packaged into the Buildkite Homebrew tap. To install, run:

  brew install buildkite/buildkite/bktec

  bktec is available as a Docker image. To install, run:

  docker pull buildkite/test-engine-client

  You can install bktec manually by downloading the relevant package:

  • bktec_darwin_amd64
  • bktec_darwin_arm64
  • bktec_linux_amd64
  • bktec_linux_arm64

• Ensure the following Buildkite environment variables are available in your testing environment.

                  
                    BUILDKITE_ORGANIZATION_SLUG
  
                    BUILDKITE_BUILD_ID
  
                    BUILDKITE_JOB_ID
  
                    BUILDKITE_STEP_ID
  
                    BUILDKITE_PARALLEL_JOB
  
                    BUILDKITE_PARALLEL_JOB_COUNT
                  
                

  Note that BUILDKITE_STEP_ID needs to be interpolated within your testing environment rather than on the pipeline upload, as this variable will have the value of the upload job if it is interpolated earlier.

• Additional environment variables are required for bktec.

                   
                     BUILDKITE_TEST_ENGINE_SUITE_SLUG=docs-1
  
                     BUILDKITE_TEST_ENGINE_API_ACCESS_TOKEN=[new API access token]
  
                     BUILDKITE_TEST_ENGINE_RESULT_PATH=tmp/test-results.json
  
                     BUILDKITE_TEST_ENGINE_TEST_RUNNER=[rspec|jest|cypress|playwright]
                   
                 

  For the BUILDKITE_TEST_ENGINE_API_ACCESS_TOKEN, create a new API access token.
  This API access token requires the read_suites, read_test_plan, and write_test_plan REST API scopes.
  Please follow any existing security practices your organization has for creating tokens for machine users. Learn more about Buildkite's best practices for managing secrets.

  For the BUILDKITE_TEST_ENGINE_TEST_RUNNER, specify the test runner you are using. Currently, the possible values for this are rspec, jest, cypress, and playwright.

• Update your pipeline to use Buildkite Test Engine Client (bktec).

                     
                       - name: "Run tests with bktec" 
  
                           command: bktec
  
                           parallelism: 10
  
                           env:
  
                             BUILDKITE_TEST_ENGINE_API_ACCESS_TOKEN: /your/secret/value
  
                             BUILDKITE_TEST_ENGINE_SUITE_SLUG: docs-1
  
                             BUILDKITE_TEST_ENGINE_RESULT_PATH: tmp/test-results.json
  
                             BUILDKITE_TEST_ENGINE_TEST_RUNNER: rspec|jest|cypress|playwright
                     
                  

Please see the bktec documentation ↗ for more detailed installation instructions and for troubleshooting.