Reporters | Cypress Documentation (2024)

Because Cypress is built on top of Mocha, that means any reporter built forMocha can be used with Cypress. Here is a list of built in Mocha reporters.

• Mocha's built-in reporters

By default, Cypress uses the spec reporter to output information to STDOUT.

We've also added the two most common 3rd party reporters for Mocha. These arebuilt into Cypress and you can use them without installing anything.

• teamcity
• junit

Finally, we support creating your own custom reporters or using any kind of 3rdparty reporter.

Custom reporter​

Installed locally​

You can loadcustom Mocha reportersthrough a relative or absolute path. These can be specified in your Cypressconfiguration file or via the command line.

For example, if you have the following directory structure:

> my-project
 > cypress
 > src
 > reporters
 - custom.js

You would specify the path to your custom reporter in either of the ways below.

Cypress configuration​

const { defineConfig } = require('cypress')

module.exports = defineConfig({
 reporter: 'reporters/custom.js',
})

Command Line​

cypress run --reporter reporters/custom.js

Installed via npm​

When using custom reporters via npm, specify the package name.

Cypress configuration​

const { defineConfig } = require('cypress')

module.exports = defineConfig({
 reporter: 'mochawesome',
})

Command line​

cypress run --reporter mochawesome

Reporter Options​

Some reporters accept options that customize their behavior. These can bespecified in your Cypress configuration or viacommand line options.

Reporter options differ depending on the reporter (and may not be supported atall). Refer to the documentation for the reporter you are using for details onwhich options are supported.

The below configuration will output the JUnit report to STDOUT and save itinto an XML file.

Cypress configuration​

const { defineConfig } = require('cypress')

module.exports = defineConfig({
 reporter: 'junit',
 reporterOptions: {
 mochaFile: 'results/my-test-output.xml',
 toConsole: true,
 },
})

Command line​

cypress run --reporter junit \
 --reporter-options "mochaFile=results/my-test-output.xml,toConsole=true"

Merging reports across spec files​

Each spec file is processed completely separately during each cypress runexecution. Thus each spec run overwrites the previous report file. To preserveunique reports for each specfile, use the [hash] in the mochaFile filename.

The following configuration will create separate XML files in the resultsfolder. You can then merge the reported output in a separate step using a 3rdparty tool. For example, for theMochawesome reporter, you can usethe mochawesome-merge tool.

Cypress configuration​

const { defineConfig } = require('cypress')

module.exports = defineConfig({
 reporter: 'junit',
 reporterOptions: {
 mochaFile: 'results/my-test-output-[hash].xml',
 },
})

Command line​

cypress run --reporter junit \
 --reporter-options "mochaFile=results/my-test-output-[hash].xml"

Multiple reporters​

Oftentimes we see users wanting the ability to use multiple reporters. Whenrunning in CI, you might want to generate a report for junit and perhaps ajson report. This is great, but by setting this reporter you won't receive anyadditional feedback while the tests are running!

The solution here is to use multiple reporters. You will have the benefit ofboth worlds.

We suggest using the npm module:

https://github.com/you54f/cypress-multi-reporters

We use multiple reporters for every single one of our internal projects.

The below examples were implemented in

https://github.com/cypress-io/cypress-example-circleci-orb

.

Examples​

Spec to STDOUT, save JUnit XML files​

We want to output a spec report to STDOUT, while saving a JUnit XML file foreach spec file.

We need to install additional dependencies:

• cypress-multi-reporters:enables multiple reporters
• mocha-junit-reporterthe actual junit reporter, as we cannot use the junit reporter that comeswith Cypress

npm install cypress-multi-reporters mocha-junit-reporter --save-dev

Specify your reporter and reporterOptions in your Cypress configuration or viathe command line.

Cypress configuration​

const { defineConfig } = require('cypress')

module.exports = defineConfig({
 reporter: 'cypress-multi-reporters',
 reporterOptions: {
 configFile: 'reporter-config.json',
 },
})

Command line​

cypress run --reporter cypress-multi-reporters \
 --reporter-options configFile=reporter-config.json

Then add the separate reporter-config.json file (defined in yourconfiguration) to enable spec and junit reporters and direct the junitreporter to save separate XML files.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
 reporterEnabled: 'spec, mocha-junit-reporter',
 mochaJunitReporterReporterOptions: {
 mochaFile: 'cypress/results/results-[hash].xml',
 },
})

We recommend deleting all files from the cypress/results folder before runningthis command, since each run will output new XML files. For example, you can addthe npm script commands below to your package.json then call npm run report.

{
 "scripts": {
 "delete:reports": "rm cypress/results/* || true",
 "prereport": "npm run delete:reports",
 "report": "cypress run --reporter cypress-multi-reporters --reporter-options configFile=reporter-config.json"
 }
}

In case you want to combine generated XML files into a single one,junit-report-merger can beadded. For example, to combine all files intocypress/results/combined-report.xml the combine:reports script can be added.

{
 "scripts": {
 "delete:reports": "rm cypress/results/* || true",
 "combine:reports": "jrm cypress/results/combined-report.xml \"cypress/results/*.xml\"",
 "prereport": "npm run delete:reports",
 "report": "cypress run --reporter cypress-multi-reporters --reporter-options configFile=reporter-config.json",
 "postreport": "npm run combine:reports"
 }
}

Spec to STDOUT, produce a combined Mochawesome JSON file​

This example is shown in the branch spec-and-single-mochawesome-json inhttps://github.com/cypress-io/cypress-example-circleci-orb.We want to output a "spec" report to STDOUT, save an individual MochawesomeJSON file per test file, and then combine all JSON reports into a single report.

We need to install some additional dependencies.

npm install mochawesome mochawesome-merge mochawesome-report-generator --save-dev

We need to configure the reporter in yourCypress configuration to skip the HTMLreport generation and save each individual JSON file in the cypress/resultsfolder.

Cypress configuration​

const { defineConfig } = require('cypress')

module.exports = defineConfig({
 reporter: 'mochawesome',
 reporterOptions: {
 reportDir: 'cypress/results',
 overwrite: false,
 html: false,
 json: true,
 },
})

Command line​

cypress run --reporter mochawesome \
 --reporter-options reportDir="cypress/results",overwrite=false,html=false,json=true

Our run will generate filescypress/results/mochawesome.json, cypress/results/mochawesome_001.json, ....Then we can combine them using themochawesome-merge utility.

npx mochawesome-merge "cypress/results/*.json" > mochawesome.json

We can now generate a combined HTML report from the mochawesome.json fileusing thehttps://github.com/adamgruber/mochawesome-report-generator:

npx marge mochawesome.json

It generates the beautiful standalone HTML report filemochawesome-report/mochawesome.html shown below. As you can see all testresults, timing information, and even test bodies are included.

For more information, seeIntegrating Mochawesome reporter with Cypress's

History​