[](https://github.com/yathomasi/cypress-parallel/actions/workflows/build.yml) [
Divides your test files into equal buckets and runs a single bucket. This is
ideal for parallizing Cypress tests in a CI environment, without relying on
external services, such as Cypress' Dashboard Service.
- Installation
- How it works
- Usage
- --node \
- --knapsack \
- --disable-knapsack-output
- --unweighed-strategy "estimate" | "distribute"
- How to handle knapsack.json
- CI configuration
- Gitlab CI
- Other providers
``
$ npm install @yathomasi/cypress-parallel
1. It will search through your project for test files
2. A knapsack containing file weights is read (defaults to knapsack.json)--spec
3. Tests are divided into N buckets
4. The Ith bucket is executed by passing to Cypress with said bucket
of files
5. The knapsack is overwritten with potentially new weights
N and I is determined either by a flag --node or by environment variables for
some CI providers.
The overwritten knapsack can then be comitted back into VCS. This will allow
the library to always divide your tests somewhat evenly among the nodes.
Below are all the configuration options and some extended explanation for some of them.
`
$ npx cypress-parallel --help
Usage: cypress-parallel [options]
Options:
-v, --version output the version number
--cypress-run-command
run' or 'yarn cypress run' depending on how invoked
--node
--knapsack
--read-knapsack
--write-knapsack
--disable-knapsack-output disables knapsack output (default: false)
--unweighed-strategy
(default: "estimate")
-h, --help display help for command
`
Unrecognized arguments are passed along to Cypress, so arguments such as -e /
--env can be used as shown below
`
$ npx cypress-parallel --env foo=bar
The utility will automatically pick up node configuration for some CI
providers. Otherwise you can specify node index and total node count using
--node, as shown below.
`
$ npx cypress-parallel --node 1:5
Specifies the location of the knapsack file. Defaults to knapsack.json.
Optionally specified the location of the knapsack file to read.
Optionally specified the location of the knapsack file to write.
Disables outputting knapsack data to the file system. This is always disabled
when you specify --reporter or --reporter-options to Cypress. If youcypress-multi-reporters
require custom options and still want to obtain the knapsack output, you need
to configure with @yathomasi/cypress-parallel/knapsack-reporter
yourself.
What strategy to utilize if encountering a test file that isn't contained in
the knapsack. The "estimate" strategy will estimate expected execution time
based off of file length (line numbers). The "distribute" strategy will merely
distribute unknown files evenly amongst the nodes.
Custom stragies can be implemented using [cusmiconfig][cusmiconfig], as shown below.
`js`
module.export = {
/* @type {import("@yathomasi/cypress-parallel").UnweighedStrategy} /
unweighedStrategy(weighedFiles, unweighedFiles, nodeCount) {
// Implement me.
},
};
[cusmiconfig]: https://github.com/davidtheclark/cosmiconfig
The knapsack contains every test file's weight and is instrumental for dividing
tests evenly among nodes. This file needs to be available during the run and it
should ideally be kept up-to-date. One way of handling this is to check it into
version control somewhat regularly. Another way of handling it is to make your
CI provider cache the data and re-surface it on subsequent runs. This last
approach requires you to combine the knapsack data for every node before
caching it though, which may or may not be so easy depending on your provider.
Below is an example of how to configure Gitlab CI to parallelize Cypress tests.
Contributions of similar examples for other providers are welcome.
This example illustrate two things, 1) running tests in parallel and 2)
combining knapsack data into a single, downloadable artifact. The latter is
completely optional and you need to decide for yourself how you want to handle
this.
`yaml
test:
stage: Test (1)
parallel: 5
artifacts:
when: always
paths:
- knapsack-$CI_NODE_INDEX.json
expire_in: 1 day
script:
- npx cypress-parallel --write-knapsack "knapsack-$CI_NODE_INDEX.json"
knapsack:
stage: Test (2)
script:
- cat knapsack-*.json | jq -sS add | tee knapsack.json
artifacts:
when: always
paths:
- knapsack.json
expire_in: 1 day
`
If your provider does not provide a keyword such as Gitlab's parallel, then you can always simply
just create N explicit jobs, similar to that shown below.
`yaml
test_1:
stage: Test
script:
- npx cypress-parallel --node 1:5
test_2:
stage: Test
script:
- npx cypress-parallel --node 2:5
test_3:
stage: Test
script:
- npx cypress-parallel --node 3:5
test_4:
stage: Test
script:
- npx cypress-parallel --node 4:5
test_5:
stage: Test
script:
- npx cypress-parallel --node 5:5
``