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
andKNAPSACK_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
andKNAPSACK_PRO_PROJECT_DIR
KNAPSACK_PRO_FALLBACK_MODE_ENABLED
Enable/disable Fallback Mode.
Default: true
Available:
false
: Knapsack Pro will fail the build afterKNAPSACK_PRO_MAX_REQUEST_RETRIES
true
: Knapsack Pro will switch to Fallback Mode afterKNAPSACK_PRO_MAX_REQUEST_RETRIES
Related FAQs
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 whenKNAPSACK_PRO_CI_NODE_BUILD_ID
changes (see what Knapsack Pro uses asnode_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 (whenci 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/preemptibletrue
when your CI uses the sameKNAPSACK_PRO_CI_NODE_BUILD_ID
on retriesfalse
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
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
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
whenKNAPSACK_PRO_FALLBACK_MODE_ENABLED=false
6
in Regular Mode3
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
andKNAPSACK_PRO_COMMIT_HASH
from the CI environment (see supported CIs) git
(requiresKNAPSACK_PRO_PROJECT_DIR
): Knapsack Pro will setKNAPSACK_PRO_BRANCH
andKNAPSACK_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.
- 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
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
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"
You may need to make your test files require spec_helper
with:
require_relative 'spec_helper' # ✅ Good
require 'spec_helper' # ⛔️ Bad
Related FAQs
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
andKNAPSACK_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
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
KNAPSACK_PRO_TEST_FILE_PATTERN
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"