Cypress Merge Reporter

A Cypress plugin that generates beautiful dual HTML reports with detailed test execution data and an executive overview. Perfect for CI/CD pipelines and test result analysis.

Overview

Standard Cypress reporters provide basic output. With cypress-merge-reporter:

• Dual Reports: Get both a detailed report (all tests with steps) and an executive overview (summary + failures only)
• Memory Efficient: Streaming architecture handles thousands of tests without memory issues
• Rich Test Details: See test steps, screenshots, hook failures, and execution time
• Beautiful HTML Output: Modern, responsive reports with filtering and search capabilities
• Zero Configuration: Works out of the box with sensible defaults

Installation

Install the plugin as a development dependency:

npm install cypress-merge-reporter --save-dev

or using Yarn:

yarn add cypress-merge-reporter --dev

Integration

Step 1: Configure Cypress

Add the reporter to your cypress.config.js:

const { defineConfig } = require('cypress');
const { registerReporter } = require('cypress-merge-reporter');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // Register the reporter
      registerReporter(on, {
        outputDir: 'reports',                    // Optional: default is 'reports'
        detailedFileName: 'detailed-report.html', // Optional: default is 'detailed-report.html'
        overviewFileName: 'overview-report.html'  // Optional: default is 'overview-report.html'
      });

      return config;
    }
  }
});

Step 2: Add Support File

Import the support file in your cypress/support/e2e.js:

require('cypress-merge-reporter/support');

This enables command tracking for detailed test step reporting.

Step 3: Run Your Tests

Run Cypress tests as usual:

npx cypress run

After test execution completes, you'll find two HTML reports in the reports directory:

• detailed-report.html - Complete test execution details with all tests
• overview-report.html - Executive summary with failures only

Features

Detailed Report

The detailed report includes:

• Summary Statistics: Total tests, pass/fail counts, pass rate, execution time
• Test Files Overview: All spec files with their test counts and status
• Complete Test Listing: Every test with:
  • Test title and status (✅ passed, ❌ failed, ⏸ skipped)
  • Execution duration
  • Test steps (captured Cypress commands)
  • Error messages with stack traces
  • Screenshots (for failed tests)
  • Hook failure indicators
• Interactive Filters: Filter tests by status (all, passed, failed, skipped)
• Collapsible Details: Expand/collapse test steps and error details

Overview Report

The executive overview includes:

• High-Level Summary: Overall test status, pass rate, total counts
• Visual Progress Bar: Quick visual indication of test health
• Spec Files Grid: All test files with pass/fail counts
• Failures Section: Only failed tests with error details
• Compact Format: Perfect for quick status checks and CI/CD dashboards

Configuration Options

All options are optional. Here are the available configuration parameters:

registerReporter(on, {
  // Output directory for generated reports
  outputDir: 'reports',  // Default: 'reports'
  
  // Detailed report filename
  detailedFileName: 'detailed-report.html',  // Default: 'detailed-report.html'
  
  // Overview report filename
  overviewFileName: 'overview-report.html',  // Default: 'overview-report.html'
  
  // Memory threshold for large test suites (number of tests)
  maxTestsInMemory: 5000  // Default: 5000
});

Advanced Features

Hook Failure Detection

The reporter automatically detects and highlights hook failures (before, beforeEach, after, afterEach):

describe('User Profile', () => {
  beforeEach(() => {
    cy.visit('/profile');
    cy.get('.nonexistent').should('exist'); // Hook failure
  });

  it('should show username', () => {
    // This test will be marked as failed due to hook failure
    cy.get('.username').should('be.visible');
  });
});

Tests affected by hook failures are clearly marked with a ⚠️ indicator.

Screenshot Integration

Failed tests automatically include screenshots in the detailed report:

it('should display product price', () => {
  cy.visit('/product');
  cy.get('.price').should('contain', '$99.99'); // If this fails, screenshot is captured
});

The screenshot paths are automatically linked in the report for easy debugging.

Memory-Efficient Streaming

For large test suites (5000+ tests), the reporter uses a streaming architecture:

• Test data is written to temporary .jsonl files during execution
• Reports are generated by streaming data from disk
• Memory usage remains constant regardless of test suite size
• Temporary files are automatically cleaned up after report generation

Report Examples

Successful Test Run

When all tests pass:

• Overview shows ✅ status with green progress bar
• Detailed report lists all tests with ✅ indicators
• No failures section in overview

Failed Tests

When tests fail:

• Overview shows ❌ status with failure count
• Failed tests highlighted in red with error details
• Screenshots displayed inline (if available)
• Stack traces formatted for readability

Mixed Results

When some tests pass and others fail:

• Pass rate percentage clearly displayed
• Filters allow focusing on specific test status
• Spec files show individual pass/fail counts

Best Practices

Use in CI/CD Pipelines

Store reports as artifacts for easy access:

# GitHub Actions example
- name: Run Cypress Tests
  run: npx cypress run
  
- name: Upload Test Reports
  if: always()
  uses: actions/upload-artifact@v3
  with:
    name: cypress-reports
    path: reports/

Custom Report Locations

Organize reports by environment or test run:

const timestamp = new Date().toISOString().replace(/[:.]/g, '-');

registerReporter(on, {
  outputDir: `reports/${timestamp}`,
  detailedFileName: `detailed-${process.env.ENV}.html`,
  overviewFileName: `overview-${process.env.ENV}.html`
});

Large Test Suites

For suites with thousands of tests:

registerReporter(on, {
  maxTestsInMemory: 10000  // Increase threshold if needed
});

The reporter automatically switches to streaming mode when thresholds are exceeded.

Troubleshooting

Reports Not Generated

Problem: No HTML files in the reports directory.

Solution: Ensure setupNodeEvents is properly configured and the support file is imported.

Missing Test Steps

Problem: Test steps not showing in detailed report.

Solution: Import the support file in cypress/support/e2e.js:

require('cypress-merge-reporter/support');

Screenshots Not Showing

Problem: Failed tests don't show screenshots.

Solution: Ensure Cypress screenshot functionality is enabled (default behavior) and screenshots are being captured.

Memory Issues

Problem: Out of memory errors with very large test suites.

Solution: Reduce maxTestsInMemory threshold:

registerReporter(on, {
  maxTestsInMemory: 2000  // Lower threshold
});

How It Works

The reporter integrates with Cypress at two levels:

1. Command Tracking (via support file):

   • Intercepts Cypress commands during test execution
   • Stores command history using cy.task()
   • Limits storage to last 100 commands per test for memory efficiency

2. Report Generation (via after:run event):

   • Processes test results after execution completes
   • Streams data to temporary files for large suites
   • Generates both HTML reports with embedded CSS and JavaScript
   • Cleans up temporary files automatically

The streaming architecture ensures consistent memory usage regardless of test suite size.

Browser Compatibility

Generated HTML reports work in all modern browsers:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

No external dependencies required - all CSS and JavaScript is embedded in the HTML files.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Keywords

• cypress
• reporter
• testing
• html-report
• test-reporter
• cypress-plugin
• test-automation
• e2e-testing
• test-results
• cypress-reporter