{"id":15309,"library":"cypress-circleci-reporter","title":"Cypress CircleCI Reporter","description":"cypress-circleci-reporter is a specialized test reporter for Cypress, designed to integrate seamlessly with CircleCI's test parallelization features. Based on `mocha-junit-reporter`, it generates JUnit XML reports and leverages test timing data to optimize test distribution across parallel CircleCI containers. This allows for faster feedback cycles in CI/CD pipelines. The current stable version is 0.5.0, with releases occurring intermittently but actively since 2020. Key differentiators include its focus on enhancing CircleCI's built-in parallelization, the ability to specify report output directories and filenames with hash-based uniqueness, and a `consoleOutput` option for real-time test status in the terminal. It requires Cypress 3.8.3 or newer and `mocha` as a peer dependency.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/ksocha/cypress-circleci-reporter","tags":["javascript","circleci","reporter","cypress","parallelization","testing","typescript"],"install":[{"cmd":"npm install cypress-circleci-reporter","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-circleci-reporter","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-circleci-reporter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required by the reporter for its underlying functionality.","package":"mocha","optional":false}],"imports":[{"note":"The reporter is primarily configured as a string literal in `cypress.config.js` or `cypress.json`.","wrong":"import { CypressCircleciReporter } from 'cypress-circleci-reporter';","symbol":"Reporter Configuration String","correct":"module.exports = defineConfig({\n  e2e: {\n    reporter: 'cypress-circleci-reporter',\n    reporterOptions: {\n      resultsDir: './test_results/cypress',\n      resultFileName: 'cypress-[hash].xml'\n    }\n  }\n});"},{"note":"When running Cypress via the command line, the reporter is specified using the `--reporter` flag. Reporter options are passed via `--reporter-options` as a comma-separated string.","wrong":"cypress run --reporter require('cypress-circleci-reporter')","symbol":"CLI Reporter Flag","correct":"cypress run --reporter cypress-circleci-reporter --reporter-options \"resultsDir=./results/cypress,resultFileName=report-[hash].xml\""},{"note":"For TypeScript projects, the `ReporterOptions` interface can be imported to type custom configuration objects.","wrong":"import ReporterOptions from 'cypress-circleci-reporter';","symbol":"ReporterOptions (TypeScript Type)","correct":"import { ReporterOptions } from 'cypress-circleci-reporter';"}],"quickstart":{"code":"import { defineConfig } from 'cypress';\n\nmodule.exports = defineConfig({\n  e2e: {\n    // Configure the reporter and its options\n    reporter: 'cypress-circleci-reporter',\n    reporterOptions: {\n      project: process.env.CYPRESS_PROJECT_NAME ?? undefined, // Optional: if you use Cypress' project parameter\n      resultsDir: './test_results/cypress', // Directory for JUnit XML reports\n      resultFileName: 'cypress-[hash].xml', // Filename for each report, [hash] is crucial for uniqueness\n      consoleOutput: true // Enable console output for test results\n    },\n    // Implement node event listeners if needed (e.g., for code coverage, though not direct reporter usage)\n    setupNodeEvents(on, config) {\n      // This is where you might include other Cypress plugins if necessary\n      // For cypress-circleci-reporter, primary setup is through the 'reporter' key above.\n      return config;\n    }\n  }\n});\n\n// In your package.json scripts:\n// \"scripts\": {\n//   \"cypress:ci\": \"yarn cypress run --spec \\\"$(circleci tests glob \\\"./cypress/e2e/**/*.cy.js\\\" | circleci tests split --split-by=timings | paste -sd \\\",\\\" -)\\\" --reporter cypress-circleci-reporter\"\n// }\n\n// Example CircleCI config snippet:\n// run_cypress_tests:\n//   parallelism: 3\n//   steps:\n//     - run:\n//         name: Run cypress tests\n//         command: |\n//           yarn cypress run --spec \"$(circleci tests glob \"./cypress/e2e/**/*.cy.js\" | circleci tests split --split-by=timings | paste -sd \",\" -)\" \\\n//             --reporter cypress-circleci-reporter \\\n//             --reporter-options \"resultsDir=./test_results/cypress,resultFileName=cypress-[hash].xml,consoleOutput=true\"\n//     - store_test_results:\n//         path: test_results\n//     - store_artifacts:\n//         path: test_results","lang":"typescript","description":"This quickstart demonstrates how to configure `cypress-circleci-reporter` within `cypress.config.ts` and shows a typical CircleCI `config.yml` setup for parallel test execution."},"warnings":[{"fix":"Ensure `mocha` is installed as a dev dependency: `npm install mocha --save-dev` or `yarn add mocha --dev`.","message":"Version 0.2.0 moved `mocha` from direct dependency to a peer dependency. This means `mocha` must now be explicitly installed in your project.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Always use `resultFileName: 'your-filename-[hash].xml'` (or similar) in your reporter options.","message":"The `resultFileName` reporter option MUST include the `[hash]` placeholder. This is crucial for generating unique report files when Cypress runs multiple spec files, especially in parallel environments, as each spec is processed separately. Without it, reports might overwrite each other.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Upgrade Cypress to version 3.8.3 or newer to ensure full compatibility.","message":"This reporter is designed for Cypress 3.8.3 or newer. Using older Cypress versions may lead to unexpected behavior or incompatibilities.","severity":"gotcha","affected_versions":"<3.8.3"},{"fix":"Refer to the CircleCI documentation and the reporter's README for correct `command` syntax in your `config.yml`.","message":"Effective test parallelization relies on CircleCI's `circleci tests glob` and `circleci tests split --split-by=timings` commands. Incorrect usage or omission of these commands will prevent the reporter from aiding in optimized test distribution.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Run `npm install mocha --save-dev` or `yarn add mocha --dev` to install the `mocha` test framework.","cause":"The `mocha` package is a peer dependency but was not installed in your project.","error":"Error: Cannot find module 'mocha'"},{"fix":"Verify the package name is correctly spelled in your `cypress.config.js` or CLI command, and ensure `npm install cypress-circleci-reporter` was run successfully.","cause":"The reporter package is either not installed, misspelled in the configuration, or Cypress cannot resolve its path.","error":"Error: Reporter \"cypress-circleci-reporter\" not found."},{"fix":"Modify your `reporterOptions` to include `resultFileName: 'my-report-[hash].xml'` (or similar) to ensure unique filenames.","cause":"The `resultFileName` option was provided without the mandatory `[hash]` string, which is required for generating unique report filenames.","error":"Invalid reporter option 'resultFileName': Must include '[hash]' placeholder."}],"ecosystem":"npm"}