Skip to content

jest.md

Latest commit

 

History

History
100 lines (70 loc) · 5.31 KB

jest.md

File metadata and controls

100 lines (70 loc) · 5.31 KB

Using bktec with Jest

To integrate bktec with Jest, set the BUILDKITE_TEST_ENGINE_TEST_RUNNER environment variable to jest. Then, specify the BUILDKITE_TEST_ENGINE_RESULT_PATH to define where the JSON result should be stored. bktec will instruct Jest to output the JSON result to this path, which is necessary for bktec to read the test results for retries and verification purposes.

export BUILDKITE_TEST_ENGINE_TEST_RUNNER=jest
export BUILDKITE_TEST_ENGINE_RESULT_PATH=tmp/jest-result.json

Configure test command

By default, bktec runs Jest with the following command:

npx jest --runTestsByPath {{testExamples}} --json --testLocationInResults --outputFile {{resultPath}}

In this command, {{testExamples}} is replaced by bktec with the list of test files or tests to run, and {{resultPath}} is replaced with the value set in BUILDKITE_TEST_ENGINE_RESULT_PATH. You can customize this command using the BUILDKITE_TEST_ENGINE_TEST_CMD environment variable.

To customize the test command, set the following environment variable:

export BUILDKITE_TEST_ENGINE_TEST_CMD="yarn test {{testExamples}} --json --testLocationInResults --outputFile {{resultPath}}"

Important

Make sure to append --json --testLocationInResults --outputFile {{resultPath}} in your custom test command, as bktec requires this to read the test results for retries and verification purposes.

Filter test files

By default, bktec runs test files that match the **/{__tests__/**/*,*.spec,*.test}.{ts,js,tsx,jsx} pattern. You can customize this pattern using the BUILDKITE_TEST_ENGINE_TEST_FILE_PATTERN environment variable. For instance, to configure bktec to only run Jest test files inside the src/components directory, use:

export BUILDKITE_TEST_ENGINE_TEST_FILE_PATTERN=src/components/**/*.test.{ts,tsx}

Additionally, you can exclude specific files or directories that match a certain pattern using the BUILDKITE_TEST_ENGINE_TEST_FILE_EXCLUDE_PATTERN environment variable. For example, to exclude test files inside the src/utilities directory, use:

export BUILDKITE_TEST_ENGINE_TEST_FILE_EXCLUDE_PATTERN=src/utilities

You can also use both BUILDKITE_TEST_ENGINE_TEST_FILE_PATTERN and BUILDKITE_TEST_ENGINE_TEST_FILE_EXCLUDE_PATTERN simultaneously. For example, to run all Jest test files with spec.ts, except those in the src/components directory, use:

export BUILDKITE_TEST_ENGINE_TEST_FILE_PATTERN=**/*.spec.ts
export BUILDKITE_TEST_ENGINE_TEST_FILE_EXCLUDE_PATTERN=src/components

Tip

This option accepts the pattern syntax supported by the zzglob library.

Location prefix

If you have configured the Buildkite test collector with a location prefix, you should set the same prefix for bktec so that test file paths match those reported by the collector. You can set this using the --location-prefix flag or the BUILDKITE_TEST_ENGINE_LOCATION_PREFIX environment variable.

bktec run --location-prefix "my/prefix/"

Or using the environment variable:

export BUILDKITE_TEST_ENGINE_LOCATION_PREFIX=my/prefix/

Automatically retry failed tests

You can configure bktec to automatically retry failed tests using the BUILDKITE_TEST_ENGINE_RETRY_COUNT environment variable. When this variable is set to a number greater than 0, bktec will retry each failed test up to the specified number of times, using the following command:

npx jest {{testExamples}} --testNamePattern '{{testNamePattern}}' --json --testLocationInResults --outputFile {{resultPath}}

In this command:

  • {{testExamples}} is replaced by bktec with the specific test files containing failed tests
  • {{testNamePattern}} is replaced by bktec with the pattern matching the failed test names
  • {{resultPath}} is replaced with the value set in BUILDKITE_TEST_ENGINE_RESULT_PATH

You can customize this command using the BUILDKITE_TEST_ENGINE_RETRY_CMD environment variable.

Recommended retry configuration

To enable automatic retry and customize the retry command, set the following environment variables:

export BUILDKITE_TEST_ENGINE_RETRY_CMD="yarn test {{testExamples}} --testNamePattern '{{testNamePattern}}' --json --testLocationInResults --outputFile {{resultPath}}"
export BUILDKITE_TEST_ENGINE_RETRY_COUNT=2

Tip

Including {{testExamples}} tells Jest to only parse the files containing failed tests, rather than scanning all test files in your project. This significantly improves retry performance, especially in projects with many test files.

Alternative configuration (not recommended)

If you need to omit the {{testExamples}} placeholder for compatibility with rare edge cases (such as custom global setup that depends on discovering all test files), you can use:

export BUILDKITE_TEST_ENGINE_RETRY_CMD="yarn test --testNamePattern '{{testNamePattern}}' --json --testLocationInResults --outputFile {{resultPath}}"
export BUILDKITE_TEST_ENGINE_RETRY_COUNT=2

Note that this will cause Jest to parse all test files on every retry, which may slow down your retry process.

Important

Make sure to append --testNamePattern '{{testNamePattern}}' --json --testLocationInResults --outputFile {{resultPath}} in your custom retry command.