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

> Learn to configure Cypress reporters easily. Explore built-in, custom, and CLI options for comprehensive test reporting in your projects.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: how-to-guide
- Published: 2026-06-16

---

**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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/./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:

```javascript
// 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:

```bash

# 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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/packages/types/src/reporter.ts)**: Type definitions for `ReporterEventHandlers` and `ReporterResults`
- **[`system-tests/test/reporters_spec.ts`](https://github.com/cypress-io/cypress/blob/main/system-tests/test/reporters_spec.ts)**: System tests verifying built-in reporter behavior

## Summary

- The `Reporter` class in [`packages/server/lib/reporter.ts`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/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`](https://github.com/cypress-io/cypress/blob/main/./my-reporter.js), Cypress looks in your project folder; otherwise, it attempts to load the string as a module from `node_modules`.