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 Cypress CLI options as command-line arguments:

npx knapsack-pro-cypress --browser chrome

You can also pass options to Node with environment variables (e.g., --max_old_space_size).

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. It can be used in tandem with KNAPSACK_PRO_TEST_FILE_PATTERN.

Default: undefined

Available: anything that node-glob accepts

Hint: you can debug in node

var glob = require("glob");
var MY_GLOB = "cypress/e2e/admin/**/*.{js,jsx}";
glob(MY_GLOB, {}, function (err, files) {
  console.log(files);
});

Examples:

KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="cypress/e2e/admin/**/*.{js,jsx}"
# or
KNAPSACK_PRO_TEST_FILE_PATTERN="cypress/e2e/**/*.{js,jsx,coffee,cjsx}" \
KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="cypress/e2e/admin/**/*.{js,jsx}"

KNAPSACK_PRO_TEST_FILE_LIST_SOURCE_FILE

File containing the list of relative paths 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=cypress/fixtures/list.txt

# ✅ list.txt
cypress/e2e/a.spec.js
cypress/e2e/b.spec.js
cypress/e2e/c.spec.js

# ⛔️ list.txt
/home/user123/project/cypress/e2e/a.spec.js
/home/user123/project/cypress/e2e/b.spec.js
/home/user123/project/cypress/e2e/c.spec.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.

caution

Knapsack Pro ignores patterns specified as Cypress CLI arguments or Cypress config files.

caution

If you are using Cypress < v10 use "cypress/integration/**/*.{js,jsx,coffee,cjsx}".

Run tests matching a pattern. It can be used in tandem with KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN.

Default: "cypress/e2e/**/*.{js,jsx,coffee,cjsx}"

Available: anything that node-glob accepts

Hint: you can debug in node

var glob = require("glob");
var MY_GLOB = "cypress/e2e/**/*.{js,jsx,coffee,cjsx}";
glob(MY_GLOB, {}, function (err, files) {
  console.log(files);
});

Examples:

KNAPSACK_PRO_TEST_FILE_PATTERN="cypress/e2e/**/*.{js,jsx,coffee,cjsx}"
# or
KNAPSACK_PRO_TEST_FILE_PATTERN="cypress/e2e/**/*.{js,jsx,coffee,cjsx}" \
KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="cypress/e2e/admin/**/*.{js,jsx}"

KNAPSACK_PRO_TEST_SUITE_TOKEN_CYPRESS

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_CYPRESS=MY_CYPRESS_API_TOKEN \
KNAPSACK_PRO_TEST_FILE_PATTERN="cypress/e2e/user/**/*.{js,jsx,coffee,cjsx}" \
  npx knapsack-pro-cypress

KNAPSACK_PRO_TEST_SUITE_TOKEN_CYPRESS=MY_OTHER_CYPRESS_API_TOKEN \
KNAPSACK_PRO_TEST_FILE_PATTERN="cypress/e2e/admin/**/*.{js,jsx,coffee,cjsx}" \
  npx knapsack-pro-cypress

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>"