Skip to main content

Vitest Reference

You can configure things in two ways:

  • Command-line arguments for the test runner
  • Environment variables for Knapsack Pro or Node

Unless specified otherwise, everything on this page is environment variables.

Command-line arguments​

You can pass all the supported Vitest CLI options as command-line arguments:

npx @knapsack-pro/vitest --coverage

KNAPSACK_PRO_BRANCH​

Git branch under test.

You don't need to set it if either:

  • Your CI is one of the supported CIs
  • Your CI has git installed so that Knapsack Pro can retrieve it

In some cases, particularly for pull request merge commits or if the CI provider checks out a specific git commit during the build process, Git might only expose HEAD instead of the actual branch name.

KNAPSACK_PRO_CI_NODE_BUILD_ID​

Unique ID that identifies a CI build. It must be the same for all the parallel CI nodes.

Default: Knapsack Pro will take it from the CI environment (see supported CIs)

If your CI is not supported, you may generate a build ID with KNAPSACK_PRO_CI_NODE_BUILD_ID=$(openssl rand -base64 32) and make it available to all parallel nodes.

KNAPSACK_PRO_CI_NODE_INDEX​

Index of current CI node (first should be 0, second should be 1, etc.).

Default: Knapsack Pro will take it from the CI environment (see supported CIs)

If your CI is not supported, you need to set it manually.

KNAPSACK_PRO_CI_NODE_RETRY_COUNT​

A retry count of the current CI node in case of a single node/job retry.

There is no need to set this for the following CI providers that are supported out of the box:

  • GitHub Actions
  • Buildkite

For other CI providers:

If you use KNAPSACK_PRO_FIXED_QUEUE_SPLIT=true, you need to set KNAPSACK_PRO_CI_NODE_RETRY_COUNT=1 when retrying a single node to disable Fallback Mode. Otherwise, the CI node would use a different (fallback) split and run a different subset of tests when the API cannot be reached.

Default: 0 (or an environment variable for supported CI providers)

Available:

  • 0: Fallback Mode is enabled
  • > 0: Fallback Mode is disabled and Knapsack Pro raises an error if the API cannot be reached

KNAPSACK_PRO_CI_NODE_TOTAL​

Total number of parallel CI nodes.

Default: Knapsack Pro will take it from the CI environment (see supported CIs)

If your CI is not supported, you need to set it manually.

KNAPSACK_PRO_COMMIT_HASH​

Hash of the commit under test.

You don't need to set it if either:

  • Your CI is one of the supported CIs
  • Your CI has git installed so that Knapsack Pro can retrieve it

KNAPSACK_PRO_ENDPOINT (Internal)​

Default: https://api.knapsackpro.com

KNAPSACK_PRO_FIXED_QUEUE_SPLIT​

Dynamic or fixed tests split when retrying a CI build.

Default: automagically set to the correct value for your CI provider

Available:

  • false: generate a new split when KNAPSACK_PRO_CI_NODE_BUILD_ID changes (see what Knapsack Pro uses as ciNodeBuildId for your CI provider)
  • true: if the triplet (branch name, commit hash, number of nodes) was already split in a previous build use the same split, otherwise generate a new split

Recommended:

  • true when your CI allows retrying single CI nodes (e.g., Buildkite, GitHub Actions) or if your CI nodes are spot instances/preemptible
  • true when your CI uses the same KNAPSACK_PRO_CI_NODE_BUILD_ID on retries (e.g., GitHub Actions, Travis, CodeShip)
  • false otherwise

KNAPSACK_PRO_LOG_LEVEL​

Default: info

Available:

  • error: critical errors
  • warn: warnings (e.g. Fallback Mode has started)
  • info: Knapsack Pro API request response body
  • verbose
  • debug: Knapsack Pro API request headers and body
  • silly

KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN​

Exclude tests matching a pattern (relative paths from the root directory). It can be used in tandem with KNAPSACK_PRO_TEST_FILE_PATTERN.

Default: if not specified, it falls back to Vitest exclude

Available: anything that node-glob accepts

Hint: you can debug in node

const { globSync } = require("glob");
const MY_GLOB = "**/*.{test,spec}.?(c|m)[jt]s?(x)";
const files = globSync(MY_GLOB);
console.log(files);

Examples:

KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="**/__tests__/admin/**/*.js"
# or
KNAPSACK_PRO_TEST_FILE_PATTERN="{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}" \
KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="**/__tests__/admin/**/*.js"

KNAPSACK_PRO_TEST_FILE_LIST_SOURCE_FILE​

File containing the list of relative paths from the root directory of tests to run. When KNAPSACK_PRO_TEST_FILE_LIST_SOURCE_FILE is set, both KNAPSACK_PRO_TEST_FILE_PATTERN and KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN are ignored.

Default: undefined

Example:

KNAPSACK_PRO_TEST_FILE_LIST_SOURCE_FILE=__tests__/fixtures/list.txt

# ✅ list.txt
__tests__/a.test.js
__tests__/b.test.js
__tests__/c.test.js

# ⛔️ list.txt
/home/user123/project/__tests__/a.test.js
/home/user123/project/__tests__/b.test.js
/home/user123/project/__tests__/c.test.js

KNAPSACK_PRO_TEST_FILE_PATTERN​

caution

Make sure to match individual files by adding the suffix (e.g., .js) so that Knapsack Pro can split by file and not by directory.

Run tests matching a pattern (relative paths from the root directory). It can be used in tandem with KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN.

Default: if not specified, it falls back to Vitest include

Available: anything that node-glob accepts

Hint: you can debug in node

const { globSync } = require("glob");
const MY_GLOB = "**/*.{test,spec}.?(c|m)[jt]s?(x)";
const files = globSync(MY_GLOB);
console.log(files);

Examples:

KNAPSACK_PRO_TEST_FILE_PATTERN="{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}"
# or
KNAPSACK_PRO_TEST_FILE_PATTERN="{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}" \
KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="**/__tests__/admin/**/*.js"

KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST​

API token required to run Knapsack Pro.

Each Knapsack Pro command defined on CI should use an individual API token.

Example:

KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_VITEST_API_TOKEN \
KNAPSACK_PRO_TEST_FILE_PATTERN="src/user/__tests__/**/*.js" \
  npx @knapsack-pro/vitest

KNAPSACK_PRO_TEST_SUITE_TOKEN_VITEST=MY_OTHER_VITEST_API_TOKEN \
KNAPSACK_PRO_TEST_FILE_PATTERN="src/admin/__tests__/**/*.js" \
  npx @knapsack-pro/vitest

KNAPSACK_PRO_USER_SEAT​

A user name that started the CI build. It is usually the same person that made the git commit.

You don't need to set it if:

  • Your CI is one of the supported CIs, and we can read the user seat for the given CI provider.

Examples:

KNAPSACK_PRO_USER_SEAT="John Doe <john.doe@example.com>"