CI pipeline is green, and your team members are sitting in a code review, wondering: what do some of those tests actually affect? A passing suite indicates nothing about whether your validation logic, error handlers, or permission checks ever ran. This might be the reason why your team ships a feature and weeks later defects start showing in production. Using Cypress, a frontend test automation tool for regression testing, is a popular solution here. This guide walks through setting up Cypress code coverage the right way. It covers instrumenting your build, registering the plugin, merging parallel CI runs, and inspecting the reports.
This guide walks you through setting up Cypress code coverage the right way, so a passing pipeline actually means something 👇
Code coverage tracks which parts of your source code execute while your Cypress tests run. Picture it as a map showing exactly which routes your tests travel through the codebase, and which corners they never visit.
Here’s the key distinction: your Cypress report shows pass or fail. Coverage shows whether the test actually reached the logic that matters. A test can load a checkout page, click submit, and see a success message. It passes, but if it never triggered your discount calculation or payment validation, those sections stay untested behind a green checkmark.
Cypress can’t measure this alone. Your application first needs instrumentation, usually through Istanbul, which inserts counters around code blocks during the build. When Cypress interacts with your app, those counters record every hit. From there, the @cypress/code-coverage plugin collects the data and passes it to NYC for reporting.
This creates a three-part chain your setup depends on:
Skip the instrumentation step, and the rest of the chain has nothing to collect. That’s the single most common reason teams end up staring at an empty report.
Code coverage and UI Coverage answer different questions, and mixing them up leads to a false sense of confidence in either direction.
| Approach | What it measures | Instrumentation required | Best for |
|---|---|---|---|
| Code coverage | Executed statements, branches, functions, and lines | Yes, via Istanbul | Finding untested logic paths, conditionals, and error handlers |
| UI Coverage | Interactive elements and application states exercised by tests | No | Finding buttons, forms, and screens your test suite never touches |
Code coverage reveals application logic your tests never executed. UI Coverage reveals interface elements your tests never touched, buttons never clicked, form fields never filled, states never triggered. A test suite can reach 90% code coverage while entire sections of the UI stay untested, since a single code path often backs several different screens or interactions. The two metrics answer separate questions, and reading one as a stand-in for the other hides real gaps in either the logic or the interface.
Coverage exposes what your regression suite quietly ignores. Tests might exercise the happy path through account creation without ever hitting the check that blocks duplicate emails, or a pricing module might only get tested with standard discounts, leaving promo codes and bulk pricing edge cases completely untouched.
Once coverage data exists, it turns those blind spots into something your team can act on instead of something everyone just assumes is fine. Here’s where that visibility pays off in practice:
Code coverage is not typically measured with E2E tests. What Cypress is offering is a feature that provides a list of UI elements that were not interacted with by any tests. It can be valuable if you have an un-manageable quantity of tests that you don't understand very well and want to see what isn't being "covered."
Getting coverage working means coordinating your build tool, test framework, and reporting plugin, and the order matters more than it might seem. Miss a step, like forgetting to instrument your build before running tests, and you’ll end up debugging an empty report instead of reading a useful one.
Before starting, make sure Node.js and npm are installed, you have write access to your repo’s build config (Vite, Webpack, or CRA setup), and permission to edit cypress.config.js. Here’s the sequence:
npm install --save-dev @cypress/code-coverage from your project root. The plugin ships with NYC bundled in, so a separate NYC install isn’t needed. The instrumentation package depends on your build pipeline:
# Vite
npm install --save-dev vite-plugin-istanbul
# Babel or Webpack
npm install --save-dev babel-plugin-istanbulimport { defineConfig } from 'vite'
import istanbul from 'vite-plugin-istanbul'
export default defineConfig({
plugins: [
istanbul({
include: 'src/*',
exclude: ['node_modules', 'test/'],
extension: ['.js', '.jsx', '.ts', '.tsx'],
requireEnv: false,
}),
],
})Once this plugin runs, Cypress picks up coverage automatically from window.__coverage__ with no further wiring. For Webpack, use babel-plugin-istanbul in your Babel config instead. Create React App projects can pair react-app-rewired with Istanbul middleware. Whichever bundler your project uses, the test build needs coverage counters that never ship to production.
cypress.config.js (or .ts) and register the coverage task inside setupNodeEvents, then return config at the end. Skipping that return breaks the setup silently.
import { defineConfig } from 'cypress'
import registerCodeCoverageTasks from '@cypress/code-coverage/task'
export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
registerCodeCoverageTasks(on, config)
return config
},
},
component: {
setupNodeEvents(on, config) {
registerCodeCoverageTasks(on, config)
return config
},
},
})import '@cypress/code-coverage/support' to both cypress/support/e2e.ts and cypress/support/component.ts. Importing it only in e2e.ts wires up E2E coverage but leaves component test coverage uncollected..nycrc or .nycrc.json at your project root. Set "all": true so every source file gets included, even ones never loaded during tests, and add "exclude" patterns for node_modules, test files, and generated code. Without this, the reported percentage looks artificially low.npx cypress run from your terminal. Coverage data lands in .nyc_output/, and reports generate in the coverage/ directory. Open coverage/lcov-report/index.html in any browser for the interactive breakdown, color coded by how well each file is covered.Component testing mounts individual UI pieces, like a button or a form, without loading your full application. Instrumentation follows the same principle here, but the configuration needs a small adjustment since components mount through a different runner than E2E tests do.
First, confirm your bundler instruments component code during the dev server build. If vite-plugin-istanbul is already registered for E2E, it typically covers component tests too. For Webpack setups, make sure babel-plugin-istanbul applies to your component source files, not just your app’s entry point, since component tests often bypass the normal bootstrap.
Register the plugin the same way you did for E2E: require('@cypress/code-coverage/task')(on, config) inside your component config. Then import the support file in cypress/support/component.js.
One catch: components that mock their dependencies produce misleading numbers. If you mount a component and stub its API client, the real client code never shows up in the report. That’s expected. The fix is combining results, running component and E2E tests together and merging their outputs, which the next section covers.
Collecting code coverage with Cypress becomes far more useful once you’re looking at combined data instead of isolated component runs.
Testing gaps oftentimes intersect with requirements-related issues. aqua cloud, an AI-driven test and requirement management solution, connects test coverage directly to requirements and business logic. This way, your team sees which lines ran and whether every critical requirement actually has validation behind it. aqua’s AI Intelligence is grounded in your own project documentation through RAG, so instead of generic suggestions, it flags untested requirements and generates test cases that match your team’s actual terminology and workflows. You get real-time dashboards tracking requirements coverage, automated gap detection, and full traceability from business need to test execution. More than that, aqua has native integrations with Jira for bidirectional sync, Azure DevOps, Confluence, 12+ more tools, and REST API, so coverage data lives where your team already works.
Boost test management efficiency by 80%
Each worker should save its coverage JSON under a unique name rather than the default .nyc_output/ path, since parallel jobs writing to the same directory overwrite each other’s data. Once every worker finishes, download all the named artifacts into one folder, then merge and report from a clean output directory:
rm -rf .nyc_output
mkdir -p .nyc_output
npx nyc merge coverage-parts .nyc_output/out.json
npx nyc report
--temp-dir .nyc_output
--reporter=html
--reporter=lcov
--reporter=text-summaryThe –temp-dir flag tells the report step exactly which merged output to read, removing any ambiguity about the data source.
Most CI platforms, including GitHub Actions, GitLab CI, CircleCI, and Jenkins, support artifact collection. Configure each worker to save its .nyc_output/ directory as an artifact, and make sure each one writes to a uniquely named path so workers don’t overwrite each other. Once every worker finishes, a final reporting job downloads all the artifacts into a shared .nyc_output/ directory. From there:
nyc merge .nyc_output merged-coverage.json to combine the raw datanyc report --reporter=html --reporter=text --reporter=lcov to generate the unified reportThe same logic applies when combining component and E2E coverage. Run them as separate jobs, preserve both output directories, merge them in a third job, and you get one report reflecting both isolated component logic and full browser scenarios.
A Cypress coverage report breaks down into four metrics rather than a single percentage, and each one highlights a different kind of gap in your test suite. Reading them together gives a far more accurate picture than glancing at the overall number.
Before diving into the file-by-file breakdown, it helps to know what each metric actually measures:
Branch coverage usually reveals the most. A function can show full line coverage while one side of an important conditional never runs once.
The HTML report shows a color-coded file tree: green for strong coverage, yellow for partial, red for serious gaps. Click into any file and you’ll see annotated source code, with execution counts in the margin showing how many times each line ran. A line hit 247 times probably lives inside a loop, while a line hit once might be an edge-case handler nobody’s testing directly.
Pay attention to one setting in particular: by default, NYC only reports files that were actually loaded during tests. That default can inflate your percentage, since a feature nobody tested at all simply disappears from the calculation rather than counting against it. Set “all”: true alongside an explicit include pattern so every matching source file appears, even ones the tests never touched, at 0% coverage.
Cypress as a tool will help validate E2E user workflows but not necessarily the code coverage. There are other tools like SonarQube/Codecov which can help in evaluating the code coverage. We use different tools for different purpose. And you might not be able to find an all-in-one tool.
A coverage report only helps if something acts on it. NYC supports failing a build when coverage drops below a set threshold, so your pipeline enforces a minimum bar instead of just displaying a number nobody checks.
Run it directly from the command line:
npx nyc report
--check-coverage
--statements 80
--branches 75
--functions 80
--lines 80Or set it once in .nycrc.json so every run applies the same thresholds automatically:
{
"all": true,
"include": ["src/**/*.{js,jsx,ts,tsx}"],
"exclude": [
"**/*.test.*",
"**/*.spec.*",
"src/generated/**"
],
"reporter": ["text-summary", "html", "lcov"],
"check-coverage": true,
"statements": 80,
"branches": 75,
"functions": 80,
"lines": 80
}Branch coverage usually needs a slightly lower threshold than statements or lines, since conditional logic multiplies the number of paths a test suite has to hit. Setting branches too high too early tends to block merges over edge cases nobody’s reached yet, not real regressions.
Even a careful setup runs into snags along the way, and most of them trace back to a handful of recurring causes. Knowing what to check first saves a lot of time spent guessing.
Here are the issues that come up most often, and what to check first when they do:
NODE_ENV isn’t set to production, which disables dev-only plugins.sourcemap: true in your build config and confirm .map files generate alongside your test build.require('@cypress/code-coverage/task')(on, config) inside setupNodeEvents. Without it, Cypress can’t save or retrieve coverage data..nycrc for trailing commas or bad exclude patterns. Run npx nyc report manually to confirm your settings are actually being applied.Getting coverage running is only half the job. Building it into how your team works day to day, from PR reviews to sprint planning, is what turns raw numbers into something worth acting on.
The practices below cover the areas where teams tend to get the most value with the least ongoing effort:
Coverage reports give your team valuable insights into code. However, they don’t tell you whether your testing strategy covers what the business actually needs. aqua cloud, an AI-powered test and requirement management platform, addresses exactly that by mapping test execution back to requirements and user stories. This way, nothing critical slips through unnoticed. The AI Intelligence is trained specifically for QA and grounded in your project’s own documentation. It flags coverage gaps against your team’s actual specifications and generates test cases that match real project context instead of generic templates. Real-time dashboards show exactly which requirements still lack validation, and with 10+ native automation integrations, including Jenkins, JMeter, SoapUI, Ranorex, Database Oracle and MSSQL, PowerShell, UnixShell, and Capture. With all that, coverage data flows straight into the tools your team already runs.
Achieve 100% strategic test coverage with AI-powered requirement traceability
Setting up Cypress code coverage gives your team a clear picture of what’s actually being tested, instead of a binary pass or fail. It takes real setup work: instrumentation, plugin configuration, and careful merging across parallel runs. The payoff is a regression suite your team can trust, one that flags gaps in validation logic and error handling before they reach production.
No. Cypress needs the @cypress/code-coverage plugin and an instrumented application build. Configure Istanbul through Vite, Webpack, or Babel to insert coverage counters, then install the plugin to collect and report that data.
Yes. Save the .nyc_output/ directory from each CI worker as an artifact, download them into a shared directory, then run nyc merge followed by nyc report. Skip the merge and only one worker’s results show up.
Four: statements, branches, functions, and lines. Branch coverage tends to be the most useful for spotting untested logic, since it catches conditionals where only one path ever executes.
No. Coverage only shows that a line executed, not that a test verified its behavior. A scenario can trigger a function without asserting anything meaningful, so high coverage numbers still need real test design behind them.
Add an "exclude" array to your .nycrc file listing patterns like node_modules/**, **/*.test.js, and config files. Without exclusions, the reported percentage drops artificially since irrelevant files count against the total.
This usually points to a source map issue or a file your bundler never instrumented. Confirm sourcemap: true is set in your build config and that the file falls under your bundler’s Istanbul or Babel instrumentation rules.
