@knapsack-pro/jest
Advanced tools
Knapsack Pro Jest splits Jest tests across CI nodes and makes sure that tests will run in optimal time on each CI node.
@knapsack-pro/jest runs your tests with Jest test runner and does dynamic tests allocation across parallel CI nodes using KnapsackPro.com Queue Mode to provide the fastest CI build time (optimal test suite timing).
Learn about Knapsack Pro Queue Mode in the video how to run tests with dynamic test suite split and learn what CI problems can be solved thanks to it.
$ npm install --save-dev @knapsack-pro/jest
To get API token just sign up at KnapsackPro.com. Please add to your CI environment variables KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST. You can generate API token in user dashboard.
(optional) Do you want to use "retry single failed parallel CI node" feature for your CI? For instance some of CI providers like Travis CI, Buildkite or Codeship allows you to retry only one of failed parallel CI node instead of retrying the whole CI build with all parallel CI nodes. If you want to be able to retry only single failed parallel CI node then you need to tell Knapsack Pro API to remember the way how test files where allocated across parallel CI nodes by adding to your CI environment variables KNAPSACK_PRO_FIXED_QUEUE_SPLIT=true.
The default is KNAPSACK_PRO_FIXED_QUEUE_SPLIT=false which means when you want to retry the whole failed CI build then a new dynamic test suite split will happen across all retried parallel CI nodes thanks to Knapsack Pro Queue Mode. Some people may prefer to retry the whole failed CI build with test files allocated across parallel CI nodes in the same order as it happend for the failed CI build - in such case you should set KNAPSACK_PRO_FIXED_QUEUE_SPLIT=true.
(optional) @knapsack-pro/jest detects information about CI build from supported CI environment variables. When information like git branch name and git commit hash cannot be detect from CI environment variables then @knapsack-pro/jest will try to use git installed on CI machine to detect the infomation. If you don't have git installed then you should set the information using environment variables:
KNAPSACK_PRO_COMMIT_HASH - git commit hash (SHA1)
KNAPSACK_PRO_BRANCH - git branch name
KNAPSACK_PRO_CI_NODE_BUILD_ID - a unique ID for your CI build. All parallel CI nodes being part of single CI build must have the same node build ID. Example how to generate node build ID: KNAPSACK_PRO_CI_NODE_BUILD_ID=$(openssl rand - base64 32).
Please select your CI provider and follow instructions to run tests with @knapsack-pro/jest.
Example configuration for CircleCI 2.0 platform.
# ~/.circleci/config.yml
version: 2
jobs:
test:
docker:
- image: circleci/<language>:<version TAG>
parallelism: 2 # run 2 parallel CI nodes
steps:
- checkout
- run:
name: Run Jest tests with @knapsack-pro/jest using Knapsack Pro Queue Mode
command: $(npm bin)/knapsack-pro-jest
Please remember to add additional parallel containers for your project in CircleCI settings.
You can parallelize your CI build across virtual machines with travis matrix feature.
# .travis.yml
script:
- "$(npm bin)/knapsack-pro-jest"
env:
global:
- KNAPSACK_PRO_CI_NODE_TOTAL=2
# allows to be able to retry failed tests on one of parallel job (CI node)
- KNAPSACK_PRO_FIXED_QUEUE_SPLIT=true
matrix:
- KNAPSACK_PRO_CI_NODE_INDEX=0
- KNAPSACK_PRO_CI_NODE_INDEX=1
The configuration will generate matrix with 2 parallel jobs (2 parallel CI nodes):
# first CI node (first parallel job)
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0
# second CI node (second parallel job)
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=1
More info about global and matrix ENV configuration in travis docs.
The only thing you need to do is to configure the parallelism parameter (number of parallel agents) in your build step and run the below command in your build:
$(npm bin)/knapsack-pro-jest
If you want to use Buildkite retry single agent feature to retry just failed tests on particular agent (CI node) then you should set KNAPSACK_PRO_FIXED_QUEUE_SPLIT=true.
Other useful resources:
Here you can find article how to set up a new pipeline for your project in Buildkite and configure Knapsack Pro and 2 example repositories for Ruby/Rails projects:
Codeship does not provide parallel jobs environment variables so you will have to define KNAPSACK_PRO_CI_NODE_TOTAL and KNAPSACK_PRO_CI_NODE_INDEX for each parallel test pipeline. Below is an example for 2 parallel test pipelines.
Configure test pipelines (1/2 used)
# first CI node running in parallel
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 $(npm bin)/knapsack-pro-jest
Configure test pipelines (2/2 used)
# second CI node running in parallel
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=1 $(npm bin)/knapsack-pro-jest
Remember to add API token KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST to Environment page of your project settings in Codeship.
If you want to use Codeship retry single CI node feature to retry just failed tests on particular CI node then you should set KNAPSACK_PRO_FIXED_QUEUE_SPLIT=true.
You can parallelize your tests on Heroku CI by configuring app.json for your project.
You can set how many parallel dynos with tests you want to run with quantity value.
Use test key to run tests with @knapsack-pro/jest as shown in below example.
You need to specify also the environment variable KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST with API token for Knapsack Pro.
For any sensitive environment variables (like Knapsack Pro API token) that you do not want commited in your app.json manifest, you can add them to your pipeline’s Heroku CI settings.
# app.json
{
"environments": {
"test": {
"formation": {
"test": {
"quantity": 2
}
},
"addons": [
"heroku-postgresql"
],
"scripts": {
"test": "$(npm bin)/knapsack-pro-jest"
},
"env": {
"KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST": "example"
}
}
}
}
Note the Heroku CI Parallel Test Runs are in Beta and you may need to ask Heroku support to enable it for your project.
You can learn more about Heroku CI.
Solano CI does not provide parallel jobs environment variables so you will have to define KNAPSACK_PRO_CI_NODE_TOTAL and KNAPSACK_PRO_CI_NODE_INDEX for each parallel job running as part of the same CI build.
# Step for first CI node
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 $(npm bin)/knapsack-pro-jest
# Step for second CI node
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=1 $(npm bin)/knapsack-pro-jest
Please remember to set up API token KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST as global environment.
AppVeyor does not provide parallel jobs environment variables so you will have to define KNAPSACK_PRO_CI_NODE_TOTAL and KNAPSACK_PRO_CI_NODE_INDEX for each parallel job running as part of the same CI build.
# Step for first CI node
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 $(npm bin)/knapsack-pro-jest
# Step for second CI node
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=1 $(npm bin)/knapsack-pro-jest
Please remember to set up API token KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST as global environment.
Remember to add API token KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST to Secret Variables in Gitlab CI Settings -> CI/CD Pipelines -> Secret Variables.
>= 11.5test:
parallel: 2
script: $(npm bin)/knapsack-pro-jest
Here you can find info how to configure the GitLab parallel CI nodes.
< 11.5 (old GitLab CI)GitLab CI does not provide parallel jobs environment variables so you will have to define KNAPSACK_PRO_CI_NODE_TOTAL and KNAPSACK_PRO_CI_NODE_INDEX for each parallel job running as part of the same test stage. Below is relevant part of .gitlab-ci.yml configuration for 2 parallel jobs.
# .gitlab-ci.yml
stages:
- test
variables:
KNAPSACK_PRO_CI_NODE_TOTAL: 2
# first CI node running in parallel
test_ci_node_0:
stage: test
script:
- export KNAPSACK_PRO_CI_NODE_INDEX=0
- $(npm bin)/knapsack-pro-jest
# second CI node running in parallel
test_ci_node_1:
stage: test
script:
- export KNAPSACK_PRO_CI_NODE_INDEX=1
- $(npm bin)/knapsack-pro-jest
The only thing you need to do is set up @knapsack-pro/jest for as many parallel threads as you need. Here is an example:
# Thread 1
$(npm bin)/knapsack-pro-jest
# Thread 2
$(npm bin)/knapsack-pro-jest
Tests will be split across 2 parallel threads.
Please remember to set up API token KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST as global environment.
The only thing you need to do is to configure number of parallel CI nodes for your project by using matrix modification. See example for 2 parallel CI nodes.
# .cirrus.yml
task:
matrix:
name: CI node 0
name: CI node 1
test_script: $(npm bin)/knapsack-pro-jest
Please remember to set up API token KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST as global environment.
Here is Ruby example for .cirrus.yml configuration file that you may find useful.
In order to run parallel jobs with Jenkins you should use Jenkins Pipeline. You can learn basics about it in the article Parallelism and Distributed Builds with Jenkins.
Here is example Jenkinsfile working with Jenkins Pipeline.
timeout(time: 60, unit: 'MINUTES') {
node() {
stage('Checkout') {
checkout([/* checkout code from git */])
// determine git commit hash because we need to pass it to Knapsack Pro
COMMIT_HASH = sh(returnStdout: true, script: 'git rev-parse HEAD').trim()
stash 'source'
}
}
def num_nodes = 4; // define your total number of CI nodes (how many parallel jobs will be executed)
def nodes = [:]
for (int i = 0; i < num_nodes; i++) {
def index = i;
nodes["ci_node_${i}"] = {
node() {
stage('Setup') {
unstash 'source'
// other setup steps
}
def knapsack_options = """\
KNAPSACK_PRO_CI_NODE_TOTAL=${num_nodes}\
KNAPSACK_PRO_CI_NODE_INDEX=${index}\
KNAPSACK_PRO_COMMIT_HASH=${COMMIT_HASH}\
KNAPSACK_PRO_BRANCH=${env.BRANCH_NAME}\
KNAPSACK_PRO_CI_NODE_BUILD_ID=${env.BUILD_TAG}\
"""
// example how to run tests with Knapsack Pro
stage('Run tests') {
sh """${knapsack_options} $(npm bin)/knapsack-pro-jest"""
}
}
}
}
parallel nodes // run CI nodes in parallel
}
Remember to set environment variable KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST in Jenkins configuration with your API token.
You have to define KNAPSACK_PRO_CI_NODE_TOTAL and KNAPSACK_PRO_CI_NODE_INDEX for each parallel job running as part of the same CI build.
# Step for first CI node
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=0 $(npm bin)/knapsack-pro-jest
# Step for second CI node
KNAPSACK_PRO_CI_NODE_TOTAL=2 KNAPSACK_PRO_CI_NODE_INDEX=1 $(npm bin)/knapsack-pro-jest
Please remember to set up API token KNAPSACK_PRO_TEST_SUITE_TOKEN_JEST as global environment.
This project depends on @knapsack-pro/core. Please check the FAQ for @knapsack-pro/core to learn more about core features available to you.
You can set KNAPSACK_PRO_TEST_FILE_PATTERN={**/__tests__/**/*.js?(x),**/?(*.)(spec|test).js?(x)} and change pattern to match your directory with test files. You can use glob pattern.
Setup @knapsack-pro/core project.
Install dependencies:
$ npm install
In order to use local version of @knapsack-pro/core run:
$ npm link @knapsack-pro/core
Compile TypeScript code to lib directory by running:
$ npm start
Register @knapsack-pro/jest package globally in your local system. This way we will be able to develop other npm packages dependent on it:
$ npm link
Set up your IDE:
WebStorm / PhpStorm
Install the following plugins:
Go to File > Settings > Languages & Frameworks > JavaScript > Code Quality Tools > ESLint
Turn on Enable checkbox.
Go to File > Settings > Languages & Frameworks > TypeScript > TSLint
Turn on Enable checkbox.
Go to File > Settings > Tools > File Watchers
Click Import button and select watchers.xml file from the repository.
Visual Studio Code
Install the following plugins:
Go to File > Preferences > Settings > Extensions > Prettier - Code formatter
Turn on Prettier: Eslint Integration checkbox.
Turn on Prettier: Tslint Integration checkbox.
Go to File > Preferences > Settings > Text Editor > Formatting
Turn on Format On Save checkbox.
From now on every change in code base will be automatically formatted by Prettier. ESLint and TSLint errors will be also automatically fixed on every file save.
Write some code.
Sign in to npm registry with command:
$ npm adduser
Ensure you have the latest version of @knapsack-pro/core in package.json:
{
"dependencies": {
"@knapsack-pro/core": "^x.x.x"
}
}
Then run npm install. This way you will be able to test @knapsack-pro/core installed from npm registry instead of local one that was linked with npm link @knapsack-pro/core.
Now commit updated package.json and package-lock.json.
$ git commit -am "Update @knapsack-pro/core"
Before releasing a new version of package please update CHANGELOG.md with github_changelog_generator:
$ gem install github_changelog_generator
# generate CHANGELOG.md
$ github_changelog_generator KnapsackPro/knapsack-pro-jest
$ git commit -am "Update CHANGELOG.md"
$ git push origin master
If you have added new files to the repository and they should be part of the released npm package then please ensure they are included in files array in package.json.
If you have changed any headers in README.md please refresh table of contents with:
$ npm run doctoc
Compile project:
# ensure you use local version of @knapsack-pro/core
$ npm link @knapsack-pro/core
$ npm run build
In order to bump version of the package run below command. It will also create a version commit and tag for the release:
# bump patch version 0.0.x
$ npm version patch
# bump minor version 0.x.0
$ npm version minor
Push to git repository created commit and tag:
$ git push origin master --tags
Now when git tag is on Github you can update CHANGELOG.md again.
$ github_changelog_generator KnapsackPro/knapsack-pro-jest
$ git commit -am "Update CHANGELOG.md"
$ git push origin master
Now you can publish package to npm registry:
$ npm publish
If your feature requires code change in @knapsack-pro/core then please push the @knapsack-pro/core to GitHub first. Then you can push changes for @knapsack-pro/jest to ensure the CI will use the latest @knapsack-pro/core.
To test @knapsack-pro/jest against real test suite we use jest-example-test-suite project.
FAQs
Knapsack Pro Jest splits Jest tests across CI nodes and makes sure that tests will run in optimal time on each CI node.
The npm package @knapsack-pro/jest receives a total of 23,877 weekly downloads. As such, @knapsack-pro/jest popularity was classified as popular.
We found that @knapsack-pro/jest demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.