@mknrt/cypress-console-spy NPM

@mknrt/cypress-console-spy

A Cypress plugin to monitor and handle console errors, warnings, and uncaught errors during tests. It offers configurable options, whitelisting, error statistics, and logging capabilities, with robust support for test-specific and suite-level configuration overrides.

Installation

Install the plugin via npm:

npm install @mknrt/cypress-console-spy

Older versions (<1.1.0) are deprecated; please update to the latest version.

Setup

Register the server part in cypress.config.js:

const { defineConfig } = require('cypress');
const { server } = require('cypress-console-spy');

module.exports = defineConfig({
    e2e: {
        setupNodeEvents(on, config) {
            server(on, config);
            return config;
        },
        env: {
            consoleDaemon: {
                failOnSpy: true,
                logToFile: true,
                methodsToTrack: ['error', 'warn'],
                throwOnWarning: false,
                whitelist: ['socket.io', /ThirdPartyScript/, 'known warning'],
                debug: false,
            },
        },
    },
});

Register the client part in cypress/support/e2e.js:

const { client } = require('cypress-console-spy');

client(Cypress, Cypress.env('consoleDaemon'));

Core Files

The plugin consists of two main files:

server.js: Manages server-side tasks, including logging console issues, saving them to files, sending notifications, and tracking error statistics. It defines Cypress tasks like logConsoleError, saveConsoleErrorToFile, notifyCriticalError, getErrorStats, resetErrorStats, and setDebugMode. It also handles events like before:run (to reset stats) and after:run (to display a summary of errors and warnings).
client.js: Handles client-side functionality by overriding Cypress's describe, it, it.only, and it.skip functions to wrap tests and suites. It sets up spies for specified console methods (e.g., error, warn), captures uncaught errors via a global error handler, filters issues based on a whitelist, checks for console issues after each test, and triggers server-side tasks for logging and notifications.

Configuration

The plugin supports the following options, configurable via Cypress.env('consoleDaemon'):

failOnSpy (boolean): Fails the test if console issues are detected (default: true). Can be overridden at the suite level with describe('name', { failOnSpy: false }, () => {...}) or test level with it('name', { failOnSpy: false }, () => {...}).
logToFile (boolean): Saves console issues to [testName].log in the cypress/logs/ directory (default: true).
methodsToTrack (array): Console methods to monitor (e.g., ['error', 'warn', 'log'], default: ['error']).
throwOnWarning (boolean): Treats warnings as critical, failing the test if failOnSpy is true (default: false).
whitelist (array): Strings or RegExp patterns to ignore when checking console issues (default: []).
debug (boolean): Enables detailed debug logging in the browser console (default: false).

Suite and Test-Specific Configuration

You can override failOnSpy for entire test suites or individual tests:

describe('Suite with ignored console errors', { failOnSpy: false }, () => {
    it('Test ignoring console errors', { failOnSpy: false }, () => {
        cy.visit('https://example.com');
        cy.window().then((win) => {
            win.console.error('Test error'); // Won't fail the test
        });
    });
});

Features

Console Monitoring: Tracks specified console methods (e.g., error, warn) during tests.
Uncaught Error Handling: Captures uncaught errors (e.g., Uncaught Error: ...) and processes them with logging and notification tasks.
Whitelisting: Ignores console messages matching specified strings or patterns.
Error Statistics: Collects and summarizes errors and warnings across test runs.
Logging: Saves issues to files in cypress/logs/ (created automatically if the directory doesn't exist).
Suite and Test Overrides: Supports failOnSpy overrides at both describe and it levels for flexible configuration.

Example Test

Here’s an example demonstrating console monitoring, whitelisting, and debug mode:

describe('Test Suite with Console Spy', { failOnSpy: false }, () => {
    it('Ignores console errors', { failOnSpy: false }, () => {
        // Enable debug mode for this test
        cy.task('setDebugMode', true);

        cy.visit('https://example.com');
        cy.window().then((win) => {
            win.console.error('Test error'); // Won't fail due to failOnSpy: false
            win.console.warn('known warning'); // Ignored due to whitelist
            throw new Error('Uncaught test error'); // Captured and logged
        });

        // Check error statistics
        cy.task('getErrorStats').then((stats) => {
            console.log('Error Stats:', stats);
        });
    });
});

Expected Behavior:

Test error is logged but doesn’t fail the test.
known warning is ignored due to the whitelist.
Uncaught test error is captured, logged, and saved to a file (if logToFile: true).
Debug logs appear in the browser console if debug: true.

Debug Logging

To troubleshoot issues, set debug: true in the plugin configuration or via cy.task('setDebugMode', true). Debug logs will appear in the browser console, including:

Configuration merging details (e.g., Merged config: { default, describe, test, result }).
Spy creation and collection (e.g., Spy created for console.error, Collected 1 calls for error).
Error checking and filtering (e.g., All collected issues: [...], Filtered issues: [...]).
Failure evaluation (e.g., Evaluating failure: filteredIssues.length=1, failOnSpy=false).

Example Debug Log:

Overriding describe with config: { failOnSpy: false }
Overriding it.only with config: { failOnSpy: false }
Merged config: { default: { failOnSpy: true, ... }, describe: { failOnSpy: false }, test: { failOnSpy: false }, result: { failOnSpy: false, ... } }
Spy created for console.error
Collected 1 calls for error
All collected issues: [{ type: "error", message: ["TEST ERROR"] }]
Filtered issues: [["TEST ERROR"]]
Evaluating failure: filteredIssues.length=1, failOnSpy=false
No failure thrown due to failOnSpy=false or no issues

Logs are saved to cypress/logs/[testName].log if logToFile: true.

Tasks

The plugin provides the following Cypress tasks:

logConsoleError: Logs console issues to the terminal.
saveConsoleErrorToFile: Saves issues to [testName].log in cypress/logs/.
notifyCriticalError: Logs critical error notifications to the terminal.
getErrorStats: Returns error and warning statistics.
resetErrorStats: Resets statistics.
setDebugMode: Toggles debug logging.

Changelog

Latest Version

Fixed failOnSpy: false not being respected in it.only tests.
Added support for describe block configuration overrides.
Eliminated duplicate checkConsoleErrors calls for consistent behavior.
Simplified configuration merging in client.js.
Updated readme.md with new features, debug logging details, and clearer examples.