Cypress CircleCI Reporter

Common errors

• Error: Cannot find module 'mocha'

  cause The `mocha` package is a peer dependency but was not installed in your project.
  fix Run `npm install mocha --save-dev` or `yarn add mocha --dev` to install the `mocha` test framework.

• Error: Reporter "cypress-circleci-reporter" not found.

  cause The reporter package is either not installed, misspelled in the configuration, or Cypress cannot resolve its path.
  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.

• Invalid reporter option 'resultFileName': Must include '[hash]' placeholder.

  cause The `resultFileName` option was provided without the mandatory `[hash]` string, which is required for generating unique report filenames.
  fix Modify your `reporterOptions` to include `resultFileName: 'my-report-[hash].xml'` (or similar) to ensure unique filenames.

Warnings

• breaking Version 0.2.0 moved `mocha` from direct dependency to a peer dependency. This means `mocha` must now be explicitly installed in your project.
  Fix: Ensure `mocha` is installed as a dev dependency: `npm install mocha --save-dev` or `yarn add mocha --dev`.
• gotcha 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.
  Fix: Always use `resultFileName: 'your-filename-[hash].xml'` (or similar) in your reporter options.
• gotcha This reporter is designed for Cypress 3.8.3 or newer. Using older Cypress versions may lead to unexpected behavior or incompatibilities.
  Fix: Upgrade Cypress to version 3.8.3 or newer to ensure full compatibility.
• gotcha 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.
  Fix: Refer to the CircleCI documentation and the reporter's README for correct `command` syntax in your `config.yml`.

Install

• npm install cypress-circleci-reporter npm
• yarn add cypress-circleci-reporter yarn
• pnpm add cypress-circleci-reporter pnpm

Imports

• Reporter Configuration String
  wrong:

  import { CypressCircleciReporter } from 'cypress-circleci-reporter';

  correct:

  module.exports = defineConfig({
    e2e: {
      reporter: 'cypress-circleci-reporter',
      reporterOptions: {
        resultsDir: './test_results/cypress',
        resultFileName: 'cypress-[hash].xml'
      }
    }
  });

  The reporter is primarily configured as a string literal in `cypress.config.js` or `cypress.json`.
• CLI Reporter Flag
  wrong:

  cypress run --reporter require('cypress-circleci-reporter')

  correct:

  cypress run --reporter cypress-circleci-reporter --reporter-options "resultsDir=./results/cypress,resultFileName=report-[hash].xml"

  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.
• ReporterOptions (TypeScript Type)
  wrong:

  import ReporterOptions from 'cypress-circleci-reporter';

  correct:

  import { ReporterOptions } from 'cypress-circleci-reporter';

  For TypeScript projects, the `ReporterOptions` interface can be imported to type custom configuration objects.

Quickstart

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.

import { defineConfig } from 'cypress';

module.exports = defineConfig({
  e2e: {
    // Configure the reporter and its options
    reporter: 'cypress-circleci-reporter',
    reporterOptions: {
      project: process.env.CYPRESS_PROJECT_NAME ?? undefined, // Optional: if you use Cypress' project parameter
      resultsDir: './test_results/cypress', // Directory for JUnit XML reports
      resultFileName: 'cypress-[hash].xml', // Filename for each report, [hash] is crucial for uniqueness
      consoleOutput: true // Enable console output for test results
    },
    // Implement node event listeners if needed (e.g., for code coverage, though not direct reporter usage)
    setupNodeEvents(on, config) {
      // This is where you might include other Cypress plugins if necessary
      // For cypress-circleci-reporter, primary setup is through the 'reporter' key above.
      return config;
    }
  }
});

// In your package.json scripts:
// "scripts": {
//   "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"
// }

// Example CircleCI config snippet:
// run_cypress_tests:
//   parallelism: 3
//   steps:
//     - run:
//         name: Run cypress tests
//         command: |
//           yarn cypress run --spec "$(circleci tests glob "./cypress/e2e/**/*.cy.js" | circleci tests split --split-by=timings | paste -sd "," -)" \
//             --reporter cypress-circleci-reporter \
//             --reporter-options "resultsDir=./test_results/cypress,resultFileName=cypress-[hash].xml,consoleOutput=true"
//     - store_test_results:
//         path: test_results
//     - store_artifacts:
//         path: test_results