cypress-utils

library3.0.0jsnpmunverified

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.

testing devops

npm install cypress-utils

github ↗package ↗

INSTALL

IMPORT

SIG · CYPRESS-UTILS

cypress-utils

testingjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

✓ ./node_modules/.bin/cypress-utils stress-test cypress/e2e/my-spec.cy.js --trialCount 10

✗ cypress-utils stress-test cypress/e2e/my-spec.cy.js

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`.

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

cypress-utils --version

Debug

Known issues

breakingThe 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`.

affects: >=3.0.0

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.

affects: >=3.0.0

breakingNode.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.

affects: >=2.0.1

breakingPrior 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.

affects: >=2.0.0

gotchaCypress 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.

affects: >=2.2.1

Errors

Common errors & fixes

Unknown option: --integrationFolder

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.

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.

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

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`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

cypressrequiredRequired peer dependency for running Cypress tests; allows consumers to control the Cypress version used by the utility.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/trentrand/cypress-utils ↗

packagehttps://www.npmjs.com/package/cypress-utils ↗