Cypress Utilities CLI

3.0.0 · active · verified Wed Apr 22

Cypress Utils is a command-line interface (CLI) tool designed to enhance the execution of Cypress tests by providing capabilities for parallelization and stress-testing. Its current stable version is 3.0.0, which introduced support for Cypress v10 and updated CLI options to mirror Cypress's own changes. The tool primarily aims to reduce local test run times by allowing multiple Cypress instances to run concurrently and helps identify flaky tests by executing them repeatedly under configurable conditions. It does not follow a fixed release cadence but typically updates to align with major Cypress version releases, ensuring compatibility. Key differentiators include its focus on simplifying parallel execution and stress testing directly from the command line, abstracting away the complexities of managing multiple Cypress processes manually.

Common errors

```
Unknown option: --integrationFolder
```
cause Attempting to use the deprecated `--integrationFolder` option with `cypress-utils` v3.0.0 or newer.

fix Replace `--integrationFolder` with `--specPattern` in your command-line arguments or `package.json` scripts.
```
Error: The cypress peer dependency is not satisfied. Expected >=10.0.0 but found X.Y.Z.
```
cause Running `cypress-utils` v3.0.0+ with an incompatible (older) version of Cypress installed in the project.

fix Update your project's Cypress dependency to version 10.0.0 or higher (e.g., `npm install cypress@latest --save-dev`).
```
TypeError: Array.prototype.flat requires Node.js v11.0.0 or higher.
```
cause Executing `cypress-utils` v2.0.1 or newer on a Node.js runtime older than 11.0.0.

fix Upgrade your Node.js environment to version 11.0.0 or newer.
```
command not found: cypress-utils
```
cause Attempting to run `cypress-utils` directly after `npm install --save-dev cypress-utils` without using `npx` or referencing the local binary path.

fix Use `npx cypress-utils ...` or define a script in your `package.json` (e.g., `"test:parallel": "cypress-utils run-parallel"`) and run it with `npm run test:parallel`.

Warnings

breaking The command-line option `--integrationFolder` was renamed to `--specPattern` to align with Cypress v10+ changes.
Fix: Update any CLI calls or scripts to use `--specPattern` instead of `--integrationFolder`.
breaking `cypress-utils` v3.0.0 and above requires Cypress v10 or newer as a peer dependency.
Fix: Ensure your project has Cypress v10.0.0 or higher installed. Refer to the Cypress migration guide for upgrading your Cypress setup.
breaking Node.js version 11.0.0 or higher is required due to the use of `Array#flat` method.
Fix: Upgrade your Node.js environment to version 11.0.0 or higher to ensure compatibility.
breaking Prior to v2.0.0, `cypress-utils` only supported older Cypress versions. Upgrading to v2.0.0 or higher requires Cypress v5 or v6 compatibility.
Fix: Before upgrading `cypress-utils` to v2.0.0 or higher, ensure your Cypress setup is compatible with Cypress v5 or v6, following the Cypress Migration Guide.
gotcha Cypress was moved from `dependencies` to `peerDependencies`, giving users more control over the Cypress version.
Fix: Cypress must now be explicitly installed as a development dependency in your project (e.g., `npm install --save-dev cypress`) if it wasn't already.

Install

npm install cypress-utils npm
yarn add cypress-utils yarn
pnpm add cypress-utils pnpm

Imports

cypress-utils
```
npx cypress-utils run-parallel --threads 2
```
The primary method for executing `cypress-utils` without a global installation, leveraging `npx` to run the package directly from npm.
cypress-utils
wrong:
```
cypress-utils stress-test cypress/e2e/my-spec.cy.js
```
correct:
```
./node_modules/.bin/cypress-utils stress-test cypress/e2e/my-spec.cy.js --trialCount 10
```
When `cypress-utils` is installed as a development dependency, it's accessible via the local `node_modules/.bin` directory. Direct execution without `npx` or a package script requires specifying this path or ensuring it's in the system PATH.
cypress-utils
```
{ "scripts": { "test:parallel": "cypress-utils run-parallel --excludeSpecPattern *.hot-update.js" } }
```
Commonly integrated into `package.json` scripts for simplified execution within a project workflow, allowing `npm run test:parallel`.

Quickstart

Demonstrates `cypress-utils` installation and its usage via `package.json` scripts for parallel execution and stress-testing of Cypress specs, including example spec and direct `npx` commands.

{
  "name": "my-cypress-project",
  "version": "1.0.0",
  "description": "Example project using cypress-utils",
  "devDependencies": {
    "cypress": "^10.0.0",
    "cypress-utils": "^3.0.0"
  },
  "scripts": {
    "test": "echo \"No script specified\" && exit 1",
    "test:parallel": "cypress-utils run-parallel --threads 2",
    "test:stress": "cypress-utils stress-test cypress/e2e/flaky-spec.cy.js --trialCount 5"
  }
}

// 1. Install cypress-utils and Cypress (if not already installed)
// npm install --save-dev cypress cypress-utils

// 2. Create an example Cypress spec file, e.g., cypress/e2e/flaky-spec.cy.js:
// describe('Flaky Test', () => {
//   it('should sometimes pass and sometimes fail', () => {
//     const randomNumber = Math.random();
//     if (randomNumber < 0.5) {
//       cy.log('Test passed!');
//       expect(true).to.be.true;
//     } else {
//       cy.log('Test failed intentionally!');
//       expect(false).to.be.true;
//     }
//   });
// });

// 3. To run tests in parallel (as defined in package.json):
// npm run test:parallel

// 4. To stress-test a specific spec file (as defined in package.json):
// npm run test:stress

// You can also run commands directly with npx:
// npx cypress-utils run-parallel cypress/e2e/another-spec.cy.js --threads 3
// npx cypress-utils stress-test cypress/e2e/login.cy.js --trialCount 20 --threads 4

view raw JSON →