Skip to main content

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

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

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

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.

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"

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

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"

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

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

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"

This site uses cookies. By staying here you accept them. See our Cookie Policy for details.
For more information on how to turn off the use of cookies, please see this.
To refuse the use of cookies, please leave the page (more details here).