Plugin Registration

The plugin registration system sets up Cypress tasks for coverage collection, data aggregation, and report generation. This is the core backend component that handles all Node.js-side coverage operations.

Capabilities

Main Plugin Registration

Registers all coverage-related Cypress tasks and configures the environment for coverage collection.

/**
 * Main plugin registration function that sets up coverage 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;

Usage:

// cypress.config.js
module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      require('@cypress/code-coverage/task')(on, config)
      return config
    },
  },
})

Convenience Plugin Setup

Simplified plugin setup that automatically registers the main plugin.

/**
 * Convenience wrapper for automatic plugin registration
 * @param on - Cypress plugin events handler  
 * @param config - Cypress configuration object
 * @returns Modified config object
 */
function conveniencePlugin(
  on: Cypress.PluginEvents,
  config: Cypress.PluginConfigOptions
): Cypress.PluginConfigOptions;

Usage:

// Alternative setup approach
module.exports = (on, config) => {
  require('@cypress/code-coverage/plugins')(on, config)
  return config
}

Cypress Tasks

The plugin registers three core tasks that handle coverage operations:

Reset Coverage Task

Clears accumulated coverage information, with different behavior for interactive vs headless modes.

/**
 * Resets coverage data for new test runs
 * @param options - Configuration for reset behavior
 * @param options.isInteractive - Whether running in interactive mode
 * @returns null
 */
task['resetCoverage'](options: { isInteractive: boolean }): null;

• Interactive mode: Completely resets coverage map
• Headless mode: Assumes coverage was cleared before cypress run

Combine Coverage Task

Merges coverage data from individual tests with the accumulated coverage map.

/**
 * Combines coverage from single test with accumulated data
 * @param sentCoverage - Stringified coverage object from browser
 * @returns null
 */
task['combineCoverage'](sentCoverage: string): null;

Automatically:

• Parses JSON coverage data
• Fixes source file paths
• Merges with existing coverage map

Coverage Report Task

Generated final coverage reports using NYC and saves them to disk.

/**
 * Generates coverage reports in configured formats
 * @returns Promise resolving to report directory path
 */
task['coverageReport'](): Promise<string>;

Report generation process:

1. Saves current coverage map to .nyc_output/out.json
2. Validates source file paths exist
3. Runs custom npm script if available (coverage:report)
4. Generates NYC reports in configured formats
5. Returns path to report directory

Report formats supported:

• LCOV (HTML reports)
• JSON (machine-readable)
• Text (console output)
• Clover (XML format)

Configuration

The plugin reads configuration from multiple sources in order of precedence:

1. .nyc_output/ directory settings
2. package.json nyc field
3. .nycrc, .nycrc.json, .nycrc.yaml, .nycrc.yml files
4. nyc.config.js, nyc.config.cjs files

Default configuration:

{
  'report-dir': './coverage',
  'temp-dir': './.nyc_output',
  reporter: ['lcov', 'clover', 'json', 'json-summary'],
  extension: ['.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx'],
  excludeAfterRemap: false
}

Environment Variables

The plugin sets environment variables for coordination with browser-side hooks:

• config.env.codeCoverageTasksRegistered = true - Signals tasks are available

Error Handling

The plugin handles common error scenarios:

• Missing source files: Attempts to locate files using glob patterns
• Relative paths: Converts to absolute paths for proper reporting
• Missing NYC options: Uses sensible defaults
• Report generation failures: Provides detailed error messages with file paths