@cypress/code-coverage [![renovate-app badge][renovate-badge]][renovate-app]

Saves the code coverage collected during Cypress tests

Install

npm install -D @cypress/code-coverage

Note: This plugin assumes that cypress is a peer dependency already installed in your project.

Then add the code below to the supportFile and setupNodeEvents function.

// cypress/support/e2e.js
import '@cypress/code-coverage/support'

// cypress.config.js
const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      require('@cypress/code-coverage/task')(on, config)
      // include any other plugin code...

      // It's IMPORTANT to return the config object
      // with any changes
      return config
    },
  },
})

Instrument your application

This plugin DOES NOT instrument your code. You have to instrument it yourself using the Istanbul.js tool. Luckily, it is not difficult. For example, if you are already using Babel to transpile, you can add babel-plugin-istanbul to your .babelrc and instrument on the fly.

{
  "plugins": ["istanbul"]
}

Please see the Test Apps section below. You can find a linked project matching your situation to see how to instrument your application's source code before running end-to-end tests to get the code coverage.

If your application has been instrumented correctly, you should see additional counters and instructions in the application's JavaScript resources, as the image below shows.

You should see the window.__coverage__ object in the "Application under test iframe"

If you have instrumented your application's code and see the window.__coverage__ object, then this plugin will save the coverage into the .nyc_output folder and will generate reports after the tests finish (even in the interactive mode). Find the LCOV and HTML report in the coverage/lcov-report folder.

That should be it! You should see messages from this plugin in the Cypress Command Log.

More information

• Read Cypress Code Coverage: Instrumenting code guide
• Watch Code coverage webinar
• Watch videos in Cypress Tips & Tricks that deal with code coverage

App vs unit tests

You need to instrument your web application. This means that when the test does cy.visit('localhost:3000') any code, the index.html requests should be instrumented by YOU. See the Test Apps section for advice. Usually, you need to stick babel-plugin-istanbul into your pipeline somewhere.

If you are testing individual functions from your application code by importing them directly into Cypress spec files, this is called "unit tests" and Cypress can instrument this scenario for you. See Instrument unit tests section.

Reports

The coverage folder has results in several formats, and the coverage raw data is stored in the .nyc_output folder. You can see the coverage numbers yourself. This plugin has nyc as a dependency, so it should be available right away. Here are common examples:

# see just the coverage summary
$ npx nyc report --reporter=text-summary
# see just the coverage file by file
$ npx nyc report --reporter=text
# save the HTML report again
$ npx nyc report --reporter=lcov

It is helpful to enforce minimum coverage numbers. For example:

$ npx nyc report --check-coverage --lines 80
----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files |     100 |      100 |     100 |     100 |
 main.js  |     100 |      100 |     100 |     100 |
----------|---------|----------|---------|---------|-------------------

$ npx nyc report --check-coverage --lines 101
----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files |     100 |      100 |     100 |     100 |
 main.js  |     100 |      100 |     100 |     100 |
----------|---------|----------|---------|---------|-------------------
ERROR: Coverage for lines (100%) does not meet global threshold (101%)

Watch the video How to read code coverage report to see how to read the HTML coverage report.

Instrument unit tests

If you test your application code directly from specs, you might want to instrument them and combine unit test code coverage with any end-to-end code coverage (from iframe). You can easily instrument spec files using babel-plugin-istanbul, for example.

Install the plugin

npm i -D babel-plugin-istanbul

Set your .babelrc file.

{
  "plugins": ["istanbul"]
}

Put the following in the cypress/plugins/index.js file to use the .babelrc file.

module.exports = (on, config) => {
  require('@cypress/code-coverage/task')(on, config)
  on('file:preprocessor', require('@cypress/code-coverage/use-babelrc'))
  return config
}

The code coverage from spec files will be combined with end-to-end coverage.

Find examples of just the unit tests and JavaScript source files with collected code coverage in test-apps/unit-tests-js.

Instrument backend code

Example in test-apps/backend folder.

You can also instrument your server-side code and produce a combined coverage report that covers both the backend and frontend code.

1. Run the server code with instrumentation. The simplest way is to use nyc. If normally you run node src/server, then to run the instrumented version, you can do nyc --silent node src/server.
2. Add an endpoint that returns collected coverage. If you are using Express, you can do

const express = require('express')
const app = express()
require('@cypress/code-coverage/middleware/express')(app)

Tip: You can register the endpoint only if there is a global code coverage object, and you can exclude the middleware code from the coverage numbers

// https://github.com/gotwarlost/istanbul/blob/master/ignoring-code-for-coverage.md
/* istanbul ignore next */
if (global.__coverage__) {
  require('@cypress/code-coverage/middleware/express')(app)
}

If you use a Hapi server, define the endpoint yourself and return the object.

if (global.__coverage__) {
  require('@cypress/code-coverage/middleware/hapi')(server)
}

For any other server, define the endpoint yourself and return the coverage object:

if (global.__coverage__) {
  // add method "GET /__coverage__" and response with JSON
  onRequest = (response) => response.sendJSON({ coverage: global.__coverage__ })
}

1. Save the API coverage endpoint in the cypress.json file to let the plugin know where to call to receive the code coverage data from the server. Place it in expose.codeCoverage object:

{
  "expose": {
    "codeCoverage": {
      "url": "http://localhost:3000/__coverage__"
    }
  }
}

Or if you have multiple servers from which you are wanting to gather code coverage, you can pass an array to url as well:

{
  "expose": {
    "codeCoverage": {
      "url": ["http://localhost:3000/__coverage__", "http://localhost:3001/__coverage__"]
    }
  }
}

That should be enough - the code coverage from the server will be requested at the end of the test run and merged with the client-side code coverage, producing a combined report.

expectBackendCoverageOnly

If there is NO frontend code coverage, and you only want to collect backend code coverage using Cypress tests, set expectBackendCoverageOnly: true in the cypress.json file. Otherwise, Cypress complains that it cannot find the frontend code coverage.

Default:

After:

{
  "expose": {
    "codeCoverage": {
      "url": "http://localhost:3003/__coverage__",
      "expectBackendCoverageOnly": true
    }
  }
}

expectFrontendCoverageOnly

If there is ONLY frontend code coverage, set expectFrontendCoverageOnly: true in the cypress.json file. Otherwise, Cypress complains that it cannot find the frontend code coverage.

{
  "expose": {
    "codeCoverage": {
      "url": "http://localhost:3003/__coverage__",
      "expectFrontendCoverageOnly": true
    }
  }
}

Custom report folder

You can specify a custom report folder by adding nyc object to the package.json file. For example, to save reports to cypress-coverage folder, use:

{
  "nyc": {
    "report-dir": "cypress-coverage"
  }
}

Custom reporters

You can specify custom coverage reporter(s) to use. For example, to output text summary and save JSON report in the cypress-coverage folder set in your package.json folder:

{
  "nyc": {
    "report-dir": "cypress-coverage",
    "reporter": ["text", "json"]
  }
}

Tip: find list of reporters here

Custom NYC command

Sometimes, the NYC tool might be installed in a different folder, not the current or parent folder, or you might want to customize the report command. In that case, put the custom command into package.json in the current folder, and this plugin will automatically use it.

{
  "scripts": {
    "coverage:report": "call NYC report ..."
  }
}

TypeScript users

TypeScript source files should be automatically included in the report if they are instrumented.

See test-apps/ts-example, bahmutov/cra-ts-code-coverage-example or bahmutov/cypress-angular-coverage-example.

Include code

By default, the code coverage report includes only the instrumented files loaded by the application during the tests. If some modules are loaded dynamically or by the pages NOT visited during any tests, these files will not be in the report - because the plugin does not know about them. You can include all expected source files in the report using the include list in the package.json file. The files without counters will have 0 percent code coverage.

For example, to ensure the final report includes all JS files from the "src/pages" folder, set the "nyc" object in your package.json file.

{
  "nyc": {
    "all": true,
    "include": "src/pages/*.js"
  }
}

See example test-app/all-files

Exclude code

You can exclude parts of the code or entire files from the code coverage report. See Istanbul guide. Common cases:

Exclude the "else" branch

The "else" branch will never be hit when running code only during Cypress tests. Thus, we should exclude it from the branch coverage computation:

// expose "store" reference during tests
/* istanbul ignore else */
if (window.Cypress) {
  window.store = store
}

Exclude the next logical statement

Often needed to skip a statement.

/* istanbul ignore next */
if (global.__coverage__) {
  require('@cypress/code-coverage/middleware/express')(app)
}

Or a particular switch case

switch (foo) {
  case 1 /* some code */:
    break
  /* istanbul ignore next */
  case 2: // really difficult to hit from tests
    someCode()
}

Exclude files and folders

The code coverage plugin will automatically exclude any test/spec files you have defined in the testFiles (Cypress < v10) or specPattern (Cypress >= v10) configuration options. Additionally, you can set the exclude pattern glob in the code coverage configuration key to specify additional files to be excluded:

// cypress.config.js or cypress.json
expose: {
  codeCoverage: {
    exclude: ['cypress/**/*.*'],
  },
},

Cypress 10 and later users should set the exclude option to exclude any items from the cypress folder they don't want included in the coverage reports.

Additionally, you can use nyc configuration and include and exclude options. You can include and exclude files using minimatch patterns in the .nycrc file or the "nyc" object inside your package.json file.

For example, if you want only to include files in the app folder but exclude the app/util.js file, you can set it in your package.json.

{
  "nyc": {
    "include": ["app/**/*.js"],
    "exclude": ["app/util.js"]
  }
}

Note: If you have the all: true NYC option set, this plugin will check the produced .nyc_output/out.json before generating the final report. If the out.json file does not have information for some files that should be there according to the include list, then an empt