Repository files navigation

Saves the code coverage collected during Cypress tests

npm install -D @cypress/code-coverage

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

Then add the code below to thesupportFile andsetupNodeEvents function.

// cypress/support/e2e.jsimport'@cypress/code-coverage/support'

// cypress.config.jsconst{ defineConfig}=require('cypress')module.exports=defineConfig({// setupNodeEvents can be defined in either// the e2e or component configuratione2e:{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 changed environment variablesreturnconfig},},})

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

{"plugins": ["istanbul"]}

Please see theTest 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 thewindow.__coverage__ object in the "Application under test iframe"

If you have instrumented your application's code and see thewindow.__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 thecoverage/lcov-report folder.

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

• ReadCypress Code Coverage: Instrumenting code guide
• WatchCode coverage webinar
• Watch videos inCypress Tips & Tricks that deal with code coverage

You need to instrument your web application. This means that when the test doescy.visit('localhost:3000') any code, theindex.html requests should be instrumented by YOU. See theTest Apps section for advice. Usually, you need to stickbabel-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. SeeInstrument unit tests section.

Thecoverage 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 hasnyc 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 enforceminimum 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: Coveragefor lines (100%) does not meet global threshold (101%)

Watch the videoHow to read code coverage report to see how to read the HTML coverage report.

If you test your application code directly fromspecs, 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 usingbabel-plugin-istanbul, for example.

Install the plugin

npm i -D babel-plugin-istanbul

Set your.babelrc file.

{"plugins": ["istanbul"]}

Put the following in thecypress/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'))returnconfig}

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 intest-apps/unit-tests-js.

If you cannot use.babelrc (maybe it is used by other tools?), try using the Browserify transformer included with this module in theuse-browserify-istanbul file.

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

Example intest-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 usenyc. If normally you runnode src/server, then to run the instrumented version, you can donyc --silent node src/server.
2. Add an endpoint that returns collected coverage. If you are using Express, you can do

constexpress=require('express')constapp=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 JSONonRequest=(response)=>response.sendJSON({coverage:global.__coverage__})}

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

{"env": {"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 tourl as well:

{"env": {"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.

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

Default:

After:

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

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

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

You can specify a custom report folder by addingnyc object to thepackage.json file. For example, to save reports tocypress-coverage folder, use:

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

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

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

Tip: find list of reportershere

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 intopackage.json in the current folder, and this plugin will automatically use it.

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

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

Seetest-apps/ts-example,bahmutov/cra-ts-code-coverage-example orbahmutov/cypress-angular-coverage-example.

By default, the code coverage report includesonly 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 theinclude list in thepackage.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 yourpackage.json file.

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

See exampletest-app/all-files

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

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}

Often needed to skip a statement.

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

Or a particularswitch case

switch(foo){case1/* some code */:break/* istanbul ignore next */case2:// really difficult to hit from testssomeCode()}

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

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

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

Additionally, you can usenyc configuration andinclude and exclude options. You can include and exclude files usingminimatch patterns in the.nycrc file or the "nyc" object inside yourpackage.json file.

For example, if you want only to include files in theapp folder but exclude theapp/util.js file, you can set it in yourpackage.json.

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

Note: If you have theall: true NYC option set, this plugin will check the produced.nyc_output/out.json before generating the final report. If theout.json file does not have information for some files that should be there according to theinclude list, then an empty placeholder will be included. SeePR 208.

Another important option isexcludeAfterRemap. By default, it is false, which might let excluded files through. If you exclude the files, and the instrumenter does not respect thenyc.exclude setting, then addexcludeAfterRemap: true to tellnyc report to exclude files. Seetest-apps/exclude-files.

You can skip the client-side code coverage hooks by setting the environment variablecoverage tofalse.

# tell Cypress to set environment variable "coverage" to falsecypress run --env coverage=false# or pass the environment variableCYPRESS_COVERAGE=false cypress run

Or set it tofalse in thecypress.json file.

{"env": {"coverage":false  }}

SeeCypress environment variables andsupport.js. You can try running without code coverage in this project yourself

# run with code coveragenpm run dev# disable code coveragenpm run dev:no:coverage

• Read theCypress code coverage guide
• Read"Code Coverage by Parcel Bundler" blog post
• Read"Combined End-to-end and Unit Test Coverage"
• If you are using React, check out@cypress/instrument-cra
• Watch videos inCypress Tips & Tricks playlist

Full examples we use for testing in this repository:

• test-apps/backend only instruments the backend Node server and saves the coverage report
• test-apps/fullstack instruments and merges backend, e2e and unit test coverage into a single report
• test-apps/before-all-visit checks if code coverage works whency.visit is made once in thebefore hook
• test-apps/before-each-visit checks if code coverage correctly keeps track of code when doingcy.visit before each test
• test-apps/one-spec confirms that coverage is collected and filtered correctly if the user only executes a single Cypress test
• test-apps/ts-example uses Babel + Parcel to instrument and serve TypeScript file
• test-apps/use-webpack shows Webpack build with source maps and Babel
• test-apps/unit-tests-js runs just the unit tests and reports code coverage (JavaScript source code)
• test-apps/unit-tests-ts runs just the unit tests and reports code coverage (TypeScript source code)

Look up the list of examples under the GitHub topiccypress-code-coverage-example

• cypress-io/cypress-realworld-app is an easy to set up and run a real-world application with E2E, API, and unit tests that achieves 100% code-coverage for both front and back end code. Its CI pipeline also reports code-coverage reports across parallelized test runs toCodecov.
• cypress-io/cypress-example-todomvc-redux is a React / Redux application with 100% code coverage.
• cypress-io/cypress-example-conduit-app shows how to collect the coverage information from both back and frontend code and merge it into a single report. The E2E test step runs parallel in several CI containers, each saving just partial test coverage information. Then, a merge job runs, taking artifacts and combining coverage into the final report to be sent to an external coverage as a service app.
• bahmutov/code-coverage-webpack-dev-server shows how to collect code coverage from an application that uses webpack-dev-server.
• bahmutov/code-coverage-vue-example collects code coverage for Vue.js single file components.
• lluia/cypress-typescript-coverage-example shows coverage for React App that uses TypeScript. See discussion in issue#19.
• bahmutov/cypress-and-jest shows how to run Jest unit tests and Cypress unit tests, collecting code coverage from both test runners and then producing a merged report.
• bahmutov/cypress-angular-coverage-example forked fromskylock/cypress-angular-coverage-example shows Angular 8 + TypeScript application with instrumentation done usingistanbul-instrumenter-loader.
• bahmutov/testing-react shows how to get code coverage for a React application created usingCRA v3 without ejectingreact-scripts.
• bahmutov/cra-ts-code-coverage-example instruments TypeScript React application on the fly without ejectingreact-scripts by using@cypress/instrument-cra.
• bahmutov/next-and-cypress-example shows how to get backend and frontend coverage for aNext.js project. Usesmiddleware/nextjs.js.
• kylemh/next-ts-with-cypress-coverage This example project contains Next.js with TypeScript, instrumented coverage reporting, @testing-library/react, and instructions on how to type custom commands.
• akoidan/vue-webpack-typescript Pure webpack config with vue + typescript with codecov reports. This setup uses a babel-loader with a TS checker as a separate thread.
• bahmutov/code-coverage-subfolder-example shows how to instrument theapp folder usingnyc instrument as a separate step before running E2E tests
• bahmutov/docker-with-cypress-included-code-coverage-example runs tests inside pre-installed Cypress usingcypress/included:x.y.z Docker image and reports code coverage.
• bahmutov/app-in-docker-coverage-example shows an app running inside a Docker container, while Cypress runs on the local machine. Before generating the report, Cypress can stilldiscover the source files.
• bahmutov/gatsby-cypress-with-code-coverage shows code coverage using the official Gatsby "Hello World" starter.
• muratkeremozcan/angular-playground is an Angular TypeScript application with combined unit and E2E coverage.
• nefayran/cypress-react-vite React with Vite and Istanbul plugin for code coverage.

With the removal of theplugins directory in Cypress version 10+, you'll need to add all of your configuration into the configuration file (cypress.config.js by default).

// BEFORE// Register tasks in your `cypress/plugins/index.js` file.module.exports=(on,config)=>{require('@cypress/code-coverage/task')(on,config)// add other tasks to be registered here// IMPORTANT to return the config object// with the any changed environment variablesreturnconfig}

// AFTER// cypress.config.jsconst{ defineConfig}=require('cypress')module.exports=defineConfig({// setupNodeEvents can be defined in either// the e2e or component configuratione2e:{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 changed environment variablesreturnconfig},},})

Change the plugins filecypress/plugins/index.js

// BEFOREmodule.exports=(on,config)=>{on('task',require('@cypress/code-coverage/task'))}// AFTERmodule.exports=(on,config)=>{require('@cypress/code-coverage/task')(on,config)// IMPORTANT to return the config object// with the any changed environment variablesreturnconfig}

Tip: We includeplugins.js file you can point at from your code in simple cases. From yourcypress.json file:

{"pluginsFile":"node_modules/@cypress/code-coverage/plugins","supportFile":"node_modules/@cypress/code-coverage/support"}

This plugin uses thedebug module to output additional logging messages from itstask.js file. This can help with debugging errors while saving code coverage or reporting. To see these messages, run Cypress from the terminal with the environment variableDEBUG=code-coverage. Example using Unix syntax to set the variable:

$ DEBUG=code-coverage npm run dev...  code-coverage reset code coveragein interactive mode +0ms  code-coverage wrote coverage file /code-coverage/.nyc_output/out.json +28ms  code-coverage saving coverage report using the command:"nyc report --report-dir ./coverage --reporter=lcov --reporter=clover --reporter=json" +3ms

Deeply nested objects will sometimes have[object Object] values printed. You can print these nested objects by specifying a deeper depth by addingDEBUG_DEPTH= setting.

DEBUG_DEPTH=10 DEBUG=code-coverage npm run dev

Common issue:not instrumenting your application when running Cypress.

If the plugin worked before in version X but stopped after upgrading to version Y, please try thereleased versions between X and Y to see where the breaking change was.

If you decide to open an issue in this repository, please fill in all information theissue template asks for. The issues most likely to be resolved have debug logs, screenshots, and hopefully public repository links so we can try running the tests ourselves.

You can test changes locally by running tests and confirming that the code coverage has been calculated and saved.

npm run test:ci# now check generated coverage numbersnpx nyc report --check-coveragetrue --lines 80npx nyc report --check-coveragetrue --lines 100 --include cypress/about.jsnpx nyc report --check-coveragetrue --lines 100 --include cypress/unit.js

Tip: usecheck-code-coverage for stricter code coverage checks thannyc report --check-coverage allows.

You can validate links in Markdown files in this directory by executing (Linux + Mac only) script.

npm run check:markdown

This project is licensed under the terms of theMIT license.