Reference

Command-line arguments

You can pass command-line arguments using the Rake argument syntax:

bundle exec rake "knapsack_pro:rspec[--tag focus --profile]"
# ==
bundle exec rake rspec --tag focus --profile

Or using the knapsack_pro binary:

knapsack_pro rspec "--tag focus --profile"
# ==
bundle exec rake rspec --tag focus --profile

KNAPSACK_PRO_BRANCH

Git branch under test.

You don't need to set it if either:

• Your CI is one of the supported CIs
• You are using KNAPSACK_PRO_REPOSITORY_ADAPTER=git and KNAPSACK_PRO_PROJECT_DIR

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_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
• You are using KNAPSACK_PRO_REPOSITORY_ADAPTER=git and KNAPSACK_PRO_PROJECT_DIR

KNAPSACK_PRO_FALLBACK_MODE_ENABLED

Enable/disable Fallback Mode.

Default: true

Available:

• false: Knapsack Pro will fail the build after KNAPSACK_PRO_MAX_REQUEST_RETRIES
• true: Knapsack Pro will switch to Fallback Mode after KNAPSACK_PRO_MAX_REQUEST_RETRIES

Related FAQs

• What happens when Knapsack Pro API is not available/not reachable temporarily?

KNAPSACK_PRO_FIXED_QUEUE_SPLIT (Queue Mode)

Dynamic or fixed tests split when retrying a CI build.

Default: false

Available:

• false: generate a new split when KNAPSACK_PRO_CI_NODE_BUILD_ID changes (see what Knapsack Pro uses as node_build_id for your CI provider)
• true: if the quadruplet (ci build id, branch name, commit hash, number of nodes) was already split in a previous build use the same split, otherwise generate a new split (when ci build id is missing, only the other three are checked)

Recommended:

• true when your CI allows retrying single CI nodes or if your CI nodes are spot instances/preemptible
• true when your CI uses the same KNAPSACK_PRO_CI_NODE_BUILD_ID on retries
• false otherwise

KNAPSACK_PRO_LOG_DIR

Default: stdout

Available: stdout | directory

When KNAPSACK_PRO_LOG_DIR=log, Knapsack Pro will write logs to the log directory and append the CI node index to the name. For example:

• log/knapsack_pro_node_0.log
• log/knapsack_pro_node_1.log

Related FAQs

• How to write knapsack_pro logs to a file?

KNAPSACK_PRO_LOG_LEVEL

Default: debug

Available: debug | info | warn | error | fatal

Recommended: debug when debugging issues, info to know what Knapsack Pro is doing

Related FAQs

• How can I change log level?

KNAPSACK_PRO_MAX_REQUEST_RETRIES

Max amount of request attempts to try before switching to Fallback Mode. Retries respect a linear back-off.

Default:

• 6 when KNAPSACK_PRO_FALLBACK_MODE_ENABLED=false
• 6 in Regular Mode
• 3 otherwise

Available: number

KNAPSACK_PRO_PROJECT_DIR

Absolute path to the project directory (containing .git/) on the CI node.

Required with KNAPSACK_PRO_REPOSITORY_ADAPTER=git.

Default: not set

Example: /home/ubuntu/my-app-repository

KNAPSACK_PRO_REPOSITORY_ADAPTER

Controls how Knapsack Pro sets KNAPSACK_PRO_BRANCH and KNAPSACK_PRO_COMMIT_HASH.

Default: not set

Available:

• not set: Knapsack Pro will take KNAPSACK_PRO_BRANCH and KNAPSACK_PRO_COMMIT_HASH from the CI environment (see supported CIs)
• git (requires KNAPSACK_PRO_PROJECT_DIR): Knapsack Pro will set KNAPSACK_PRO_BRANCH and KNAPSACK_PRO_COMMIT_HASH using git on your CI

KNAPSACK_PRO_RSPEC_SPLIT_BY_TEST_EXAMPLES (RSpec)

Parallelize test examples (instead of files) across CI nodes.

caution

• Requires RSpec >= 3.3.0
• Does not support run_all_when_everything_filtered
• Does not support --tag

KNAPSACK_PRO_RSPEC_SPLIT_BY_TEST_EXAMPLES=true

Make sure to read the details in Split by test examples.

Related FAQs

• How to split slow RSpec test files by test examples (by individual it)?

KNAPSACK_PRO_TEST_DIR (Cucumber)

Passed as-is to Cucumber's --require.

Default: features

Available: any folder or file relative to the root of your project

Example:

KNAPSACK_PRO_TEST_DIR="features/support/cucumber_config.rb"

Related FAQs

• How to require different Cucumber config files in isolation?

KNAPSACK_PRO_TEST_DIR (RSpec)

Passed as-is to RSpec's --default-path.

Default: rspec

Available: any folder relative to the root of your project that contains spec_helper.rb

Example:

KNAPSACK_PRO_TEST_DIR=spec KNAPSACK_PRO_TEST_FILE_PATTERN="{spec,engines/*/spec}/**/*_spec.rb"

caution

You may need to make your test files require spec_helper with:

require_relative 'spec_helper' # ✅ Good

require 'spec_helper' # ⛔️ Bad

Related FAQs

• How can I run tests from multiple directories?

KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN

Exclude tests matching a pattern. It can be used in tandem with KNAPSACK_PRO_TEST_FILE_PATTERN.

Default: nil

Available: anything that Dir.glob accepts

Hint: you can debug Dir.glob(MY_GLOB) in irb or rails console

Examples:

KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="spec/features/**{,/*/**}/*_spec.rb"

KNAPSACK_PRO_TEST_FILE_PATTERN="spec/controllers/**{,/*/**}/*_spec.rb" \
KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="spec/controllers/admin/**{,/*/**}/*_spec.rb"

Related FAQs

• How to exclude tests?
• Dir.glob pattern examples for KNAPSACK_PRO_TEST_FILE_PATTERN and KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN

KNAPSACK_PRO_TEST_FILE_LIST

Comma-separated list of tests to run. When KNAPSACK_PRO_TEST_FILE_LIST is set, both KNAPSACK_PRO_TEST_FILE_PATTERN and KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN are ignored.

Default: nil

Example:

KNAPSACK_PRO_TEST_FILE_LIST=spec/features/dashboard_spec.rb,spec/models/user.rb:10,spec/models/user.rb:29

Related FAQs

• How to run a specific list of test files or only some tests from test file?

KNAPSACK_PRO_TEST_FILE_LIST_SOURCE_FILE

File containing the list 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: nil

Example:

KNAPSACK_PRO_TEST_FILE_LIST_SOURCE_FILE=spec/fixtures/list.txt

# list.txt
./spec/test1_spec.rb
spec/test2_spec.rb[1]
./spec/test3_spec.rb[1:2:3:4]
./spec/test4_spec.rb:4
./spec/test4_spec.rb:5

Related FAQs

• How to run a specific list of test files or only some tests from test file?

KNAPSACK_PRO_TEST_FILE_PATTERN

caution

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

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

Default: all tests for the given test runner

Available: anything that Dir.glob accepts

Hint: you can debug Dir.glob(MY_GLOB) in irb or rails console

Examples:

KNAPSACK_PRO_TEST_FILE_PATTERN="spec/system/**/*_spec.rb"

KNAPSACK_PRO_TEST_DIR=spec KNAPSACK_PRO_TEST_FILE_PATTERN="{spec,engines/*/spec}/**/*_spec.rb"

KNAPSACK_PRO_TEST_FILE_PATTERN="spec/controllers/**{,/*/**}/*_spec.rb" \
KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN="spec/controllers/admin/**{,/*/**}/*_spec.rb"

Related FAQs

• How to run tests from a specific directory (only system tests or features specs)?
• How can I run tests from multiple directories?
• How to exclude tests?
• Dir.glob pattern examples for KNAPSACK_PRO_TEST_FILE_PATTERN and KNAPSACK_PRO_TEST_FILE_EXCLUDE_PATTERN