{"id":16326,"library":"cypress-utils","title":"Cypress Utilities CLI","description":"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.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/trentrand/cypress-utils","tags":["javascript","cypress","command-line-tool","nodejs"],"install":[{"cmd":"npm install cypress-utils","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-utils","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for running Cypress tests; allows consumers to control the Cypress version used by the utility.","package":"cypress","optional":false}],"imports":[{"note":"The primary method for executing `cypress-utils` without a global installation, leveraging `npx` to run the package directly from npm.","symbol":"cypress-utils","correct":"npx cypress-utils run-parallel --threads 2"},{"note":"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.","wrong":"cypress-utils stress-test cypress/e2e/my-spec.cy.js","symbol":"cypress-utils","correct":"./node_modules/.bin/cypress-utils stress-test cypress/e2e/my-spec.cy.js --trialCount 10"},{"note":"Commonly integrated into `package.json` scripts for simplified execution within a project workflow, allowing `npm run test:parallel`.","symbol":"cypress-utils","correct":"{ \"scripts\": { \"test:parallel\": \"cypress-utils run-parallel --excludeSpecPattern *.hot-update.js\" } }"}],"quickstart":{"code":"{\n  \"name\": \"my-cypress-project\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Example project using cypress-utils\",\n  \"devDependencies\": {\n    \"cypress\": \"^10.0.0\",\n    \"cypress-utils\": \"^3.0.0\"\n  },\n  \"scripts\": {\n    \"test\": \"echo \\\"No script specified\\\" && exit 1\",\n    \"test:parallel\": \"cypress-utils run-parallel --threads 2\",\n    \"test:stress\": \"cypress-utils stress-test cypress/e2e/flaky-spec.cy.js --trialCount 5\"\n  }\n}\n\n// 1. Install cypress-utils and Cypress (if not already installed)\n// npm install --save-dev cypress cypress-utils\n\n// 2. Create an example Cypress spec file, e.g., cypress/e2e/flaky-spec.cy.js:\n// describe('Flaky Test', () => {\n//   it('should sometimes pass and sometimes fail', () => {\n//     const randomNumber = Math.random();\n//     if (randomNumber < 0.5) {\n//       cy.log('Test passed!');\n//       expect(true).to.be.true;\n//     } else {\n//       cy.log('Test failed intentionally!');\n//       expect(false).to.be.true;\n//     }\n//   });\n// });\n\n// 3. To run tests in parallel (as defined in package.json):\n// npm run test:parallel\n\n// 4. To stress-test a specific spec file (as defined in package.json):\n// npm run test:stress\n\n// You can also run commands directly with npx:\n// npx cypress-utils run-parallel cypress/e2e/another-spec.cy.js --threads 3\n// npx cypress-utils stress-test cypress/e2e/login.cy.js --trialCount 20 --threads 4","lang":"javascript","description":"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."},"warnings":[{"fix":"Update any CLI calls or scripts to use `--specPattern` instead of `--integrationFolder`.","message":"The command-line option `--integrationFolder` was renamed to `--specPattern` to align with Cypress v10+ changes.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure your project has Cypress v10.0.0 or higher installed. Refer to the Cypress migration guide for upgrading your Cypress setup.","message":"`cypress-utils` v3.0.0 and above requires Cypress v10 or newer as a peer dependency.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade your Node.js environment to version 11.0.0 or higher to ensure compatibility.","message":"Node.js version 11.0.0 or higher is required due to the use of `Array#flat` method.","severity":"breaking","affected_versions":">=2.0.1"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"},{"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.","message":"Cypress was moved from `dependencies` to `peerDependencies`, giving users more control over the Cypress version.","severity":"gotcha","affected_versions":">=2.2.1"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Replace `--integrationFolder` with `--specPattern` in your command-line arguments or `package.json` scripts.","cause":"Attempting to use the deprecated `--integrationFolder` option with `cypress-utils` v3.0.0 or newer.","error":"Unknown option: --integrationFolder"},{"fix":"Update your project's Cypress dependency to version 10.0.0 or higher (e.g., `npm install cypress@latest --save-dev`).","cause":"Running `cypress-utils` v3.0.0+ with an incompatible (older) version of Cypress installed in the project.","error":"Error: The cypress peer dependency is not satisfied. Expected >=10.0.0 but found X.Y.Z."},{"fix":"Upgrade your Node.js environment to version 11.0.0 or newer.","cause":"Executing `cypress-utils` v2.0.1 or newer on a Node.js runtime older than 11.0.0.","error":"TypeError: Array.prototype.flat requires Node.js v11.0.0 or higher."},{"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`.","cause":"Attempting to run `cypress-utils` directly after `npm install --save-dev cypress-utils` without using `npx` or referencing the local binary path.","error":"command not found: cypress-utils"}],"ecosystem":"npm"}