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
Use long options instead of short (e.g., --updateSnapshot
instead of -u
).
You can pass all the supported Jest CLI options as command-line arguments:
npx knapsack-pro-jest --debug
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_COVERAGE_DIRECTORY
The directory where Jest should output its coverage files.
Default: undefined
Read more on Generate code coverage reports.
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 whenKNAPSACK_PRO_CI_NODE_BUILD_ID
changes (see what Knapsack Pro uses asciNodeBuildId
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/preemptibletrue
when your CI uses the sameKNAPSACK_PRO_CI_NODE_BUILD_ID
on retries (e.g., GitHub Actions, Travis, CodeShip)false
otherwise
KNAPSACK_PRO_LOG_LEVEL
Default: info
Available:
error
: critical errorswarn
: warnings (e.g. Fallback Mode has started)info
: Knapsack Pro API request response bodyverbose
debug
: Knapsack Pro API request headers and bodysilly
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 = "{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}";
glob(MY_GLOB, {}, function (err, files) {
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 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
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.
Knapsack Pro ignores patterns specified as Jest CLI arguments or Jest config files.
Run tests matching a pattern. It can be used in tandem with KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN
.
Default: "{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}"
Available: anything that node-glob accepts
Hint: you can debug in node
var glob = require("glob");
var MY_GLOB = "{**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)}";
glob(MY_GLOB, {}, function (err, files) {
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_JEST
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_JEST=MY_JEST_API_TOKEN \
KNAPSACK_PRO_TEST_FILE_PATTERN=="src/user/__tests__/**/*.js" \
npx knapsack-pro-jest
KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST=MY_OTHER_JEST_API_TOKEN \
KNAPSACK_PRO_TEST_FILE_PATTERN=="src/admin/__tests__/**/*.js" \
npx knapsack-pro-jest
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>"