Cypress Code Coverage is a comprehensive plugin that collects, aggregates, and reports code coverage data during Cypress end-to-end and unit testing. It seamlessly integrates with Istanbul.js instrumentation to provide detailed coverage reports in multiple formats, supporting complex testing scenarios across both frontend and backend applications.
npm install -D @cypress/code-coverage// Main plugin registration (Cypress config)
require('@cypress/code-coverage/task')(on, config)
// Support file registration (Cypress support)
require('@cypress/code-coverage/support')// cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({
e2e: {
setupNodeEvents(on, config) {
require('@cypress/code-coverage/task')(on, config)
return config
},
},
})
// cypress/support/e2e.js
import '@cypress/code-coverage/support'With middleware for backend coverage:
// Express.js server
const express = require('express')
const app = express()
require('@cypress/code-coverage/middleware/express')(app)
// Next.js API route (pages/api/coverage.js)
module.exports = require('@cypress/code-coverage/middleware/nextjs')Cypress Code Coverage operates through several integrated components:
Main plugin registration system for setting up coverage collection tasks in Cypress configuration. Handles coverage reset, data aggregation, and report generation.
/**
* Registers code coverage collection and reporting tasks
* @param on - Cypress plugin events handler
* @param config - Cypress configuration object
* @returns Modified config with coverage environment variables
*/
function registerCodeCoverageTasks(
on: Cypress.PluginEvents,
config: Cypress.PluginConfigOptions
): Cypress.PluginConfigOptions;Browser-side support system that automatically collects coverage data during test execution through lifecycle hooks and window coverage monitoring.
// Auto-executing coverage collection hooks
// Imported via: require('@cypress/code-coverage/support')
/**
* Sends collected code coverage object to the backend
* @param coverage - Coverage object to send
* @param pathname - Optional path identifier (defaults to '/')
*/
function sendCoverage(coverage: Coverage, pathname?: string): void;
/**
* Sends coverage data in batches to avoid payload size limits
* @param totalCoverage - Complete coverage object to batch
* @param batchSize - Number of files per batch
*/
function sendBatchCoverage(totalCoverage: Coverage, batchSize: number): void;Server-side middleware components for collecting backend coverage from instrumented applications running alongside Cypress tests.
/**
* Express.js middleware that adds /__coverage__ endpoint
* @param app - Express application instance
*/
function expressMiddleware(app: Express): void;
/**
* Hapi.js middleware that registers /__coverage__ route
* @param server - Hapi server instance
*/
function hapiMiddleware(server: Hapi.Server): void;
/**
* Next.js API route handler for coverage endpoint
* @param req - Next.js API request object
* @param res - Next.js API response object
*/
function nextjsHandler(req: NextApiRequest, res: NextApiResponse): void;Utility functions for processing, filtering, and transforming coverage data to prepare it for reporting and aggregation.
function filterFilesFromCoverage(
totalCoverage: Coverage,
config?: Cypress.Config,
env?: Cypress.Environment,
spec?: Cypress.Spec
): Coverage;
function combineNycOptions(...options: NycOptions[]): NycOptions;Node.js-side utilities for file system operations, configuration management, and path resolution during coverage processing.
/**
* Reads NYC configuration from all possible sources
* @param workingDirectory - Directory to search for config files
* @returns Combined NYC options object
*/
function readNycOptions(workingDirectory: string): NycOptions;
/**
* Converts relative paths to absolute paths in coverage data
* @param nycFilename - Path to NYC coverage file
*/
function resolveRelativePaths(nycFilename: string): void;
/**
* Validates that all coverage file paths exist
* @param nycFilename - Path to NYC coverage file
* @returns true if all paths are missing, false otherwise
*/
function checkAllPathsNotFound(nycFilename: string): boolean;
/**
* Attempts to locate missing source files using glob patterns
* @param nycFilename - Path to NYC coverage file
*/
function tryFindingLocalFiles(nycFilename: string): void;
/**
* Includes all files in coverage report, even uncovered ones
* @param nycFilename - Path to NYC coverage file
* @param nycOptions - NYC configuration options
*/
function includeAllFiles(nycFilename: string, nycOptions: NycOptions): void;
/**
* Displays NYC configuration and coverage file information
* @param nycFilename - Path to NYC coverage file
*/
function showNycInfo(nycFilename: string): void;Browser-safe utilities for coverage data filtering and configuration management in the Cypress environment.
/**
* Removes spec files and support files from coverage data
* @param totalCoverage - Coverage object to filter
* @param config - Cypress configuration object (optional)
* @param env - Cypress environment object (optional)
* @param spec - Current spec information (optional)
* @returns Filtered coverage object with only application files
*/
function filterFilesFromCoverage(
totalCoverage: Coverage,
config?: Cypress.Config,
env?: Cypress.Environment,
spec?: Cypress.Spec
): Coverage;
/**
* Gets batch size for coverage transmission
* @returns Parsed batch size or null if invalid
*/
function getSendCoverageBatchSize(): number | null;
/**
* Fixes source file paths in coverage objects
* @param coverage - Coverage object to modify in-place
*/
function fixSourcePaths(coverage: Coverage): void;Shared utilities for NYC configuration management and coverage data manipulation.
/**
* Combines multiple NYC configuration objects with precedence
* @param options - NYC configuration objects to merge
* @returns Merged configuration object
*/
function combineNycOptions(...options: NycOptions[]): NycOptions;
/**
* Creates placeholder coverage entry for uncovered files
* @param fullPath - Full path to the file
* @returns Placeholder coverage object
*/
function fileCoveragePlaceholder(fullPath: string): FileCoverage;
/**
* Removes placeholder entries from coverage object
* @param coverage - Coverage object to clean (modified in-place)
*/
function removePlaceholders(coverage: Coverage): void;
/**
* Default NYC configuration options
*/
const defaultNycOptions: NycOptions;interface Coverage {
[filepath: string]: FileCoverage;
}
interface FileCoverage {
path: string;
statementMap: { [key: string]: StatementMapping };
fnMap: { [key: string]: FunctionMapping };
branchMap: { [key: string]: BranchMapping };
s: { [key: string]: number };
f: { [key: string]: number };
b: { [key: string]: number[] };
hash?: string;
}
interface NycOptions {
'report-dir'?: string;
'temp-dir'?: string;
reporter?: string | string[];
extension?: string | string[];
exclude?: string | string[];
excludeAfterRemap?: boolean;
all?: boolean;
}
interface CypressTask {
resetCoverage(options: { isInteractive: boolean }): null;
combineCoverage(sentCoverage: string): null;
coverageReport(): Promise<string>;
}