How to Configure Cypress Reporters: Built-in, Custom, and CLI Options

Cypress leverages Mocha's reporting system through a server-side Reporter class that loads reporters by name, resolves custom modules from the project root, and accepts configuration via the reporter and reporterOptions fields in your config file or CLI flags.

The cypress-io/cypress repository implements test reporting through a flexible architecture defined in packages/server/lib/reporter.ts. Understanding how to configure Cypress reporters allows you to customize output formats for CI/CD pipelines, generate JUnit XML for test management tools, or integrate custom reporting solutions.

How the Reporter System Works

At the core of Cypress reporting is the Reporter class located in packages/server/lib/reporter.ts. When Cypress starts a run, it instantiates this class via the constructor at line 41, passing three critical pieces of information:

• reporterName: The name of the Mocha reporter to load (e.g., spec, dot, junit, teamcity, or custom reporters)
• reporterOptions: An object passed directly to the reporter's constructor
• projectRoot: The project folder used to resolve custom reporters

The static method Reporter.loadReporter (lines 55-78) handles the resolution logic, determining whether to load a built-in Mocha reporter, a Cypress-provided reporter, or a custom module from your project.

Configuration Fields

Cypress exposes reporter configuration through two primary fields in your configuration file:

• reporter: A string specifying the reporter name or path
• reporterOptions: An object containing reporter-specific settings

These fields are recognized in cypress.config.{js,ts,mjs,cjs} files and correspond to the schema documented in the Angular schematic at npm/cypress-schematic/README.md.

Reporter Resolution Logic

The loadReporter method implements a three-tier resolution strategy:

1. Built-in Mocha reporters: Standard reporters like spec (default) and dot
2. Cypress-provided reporters: Includes junit and teamcity packaged with Cypress
3. Custom reporters: Local files referenced by relative path (e.g., ./my-reporter.js) or npm packages installed in your project

Custom reporters resolve relative to the projectRoot directory, with automatic fallback to node_modules if the path is not found locally.

Configuration Methods

Config File Setup

Define your reporter in your Cypress configuration file:

// cypress.config.js
module.exports = {
  // Built-in dot reporter
  reporter: 'dot',
  
  // JUnit reporter with options
  // reporter: 'junit',
  // reporterOptions: {
  //   mochaFile: 'results/my-tests-[hash].xml',
  //   toConsole: true
  // },
  
  // Custom reporter
  // reporter: './my-custom-reporter.js',
  // reporterOptions: { foo: 'bar' }
}

CLI Configuration

Override config settings via command line flags:

# Use the built-in dot reporter

cypress run --reporter dot

# Pass JSON options to the reporter

cypress run \
  --reporter junit \
  --reporter-options '{"mochaFile":"reports/junit.xml","toConsole":true}'

# Use a custom npm package

cypress run --reporter my-mocha-reporter

Key Implementation Files

Understanding these source files helps debug reporter issues:

• packages/server/lib/reporter.ts: Core implementation that creates the Mocha runner, loads the requested reporter via loadReporter, and forwards events
• packages/types/src/reporter.ts: Type definitions for ReporterEventHandlers and ReporterResults
• system-tests/test/reporters_spec.ts: System tests verifying built-in reporter behavior

Summary

• The Reporter class in packages/server/lib/reporter.ts instantiates Mocha reporters using reporterName, reporterOptions, and projectRoot passed to its constructor at line 41
• The Reporter.loadReporter static method (lines 55-78) resolves built-in, Cypress-provided, and custom reporters relative to the project root
• Configure reporters via the reporter string and reporterOptions object in cypress.config.{js,ts,mjs,cjs} or using --reporter and --reporter-options CLI flags
• Built-in options include spec, dot, junit, and teamcity; custom reporters can be local files or npm packages resolved through node_modules

Frequently Asked Questions

How do I change the default reporter in Cypress?

Set the reporter field in your Cypress config file to the desired reporter name, such as dot or junit, or pass --reporter <name> when running cypress run. The default reporter is spec, which requires no configuration to activate.

What is the difference between reporter and reporterOptions?

The reporter field specifies which reporter to use as a string identifier, while reporterOptions is an object containing configuration specific to that reporter. For example, the junit reporter accepts mochaFile and toConsole options to control output destinations.

Can I use custom npm packages as Cypress reporters?

Yes. Install the package via npm, then reference it by name in the reporter field. According to the cypress-io/cypress source code, the loadReporter method in packages/server/lib/reporter.ts attempts to require the string as an npm module if it cannot resolve it as a built-in reporter or local file.

Where does Cypress look for custom reporter files?

Cypress resolves custom reporter paths relative to the projectRoot directory defined in the Reporter constructor. If you specify a relative path like ./my-reporter.js, Cypress looks in your project folder; otherwise, it attempts to load the string as a module from node_modules.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}