{"id":13038,"library":"cypress-fail-on-console-error","title":"Cypress Fail on Console Error","description":"cypress-fail-on-console-error is a Cypress plugin designed to automatically fail end-to-end or component tests when the application under test emits `console.error()` or other specified console messages (e.g., `warn`, `info`, `debug`, `trace`, `table`). This helps ensure application quality by preventing uncaught console output from silently passing in CI/CD pipelines. The current stable version is 5.1.3, with frequent minor releases primarily focused on dependency updates via Renovate bot, ensuring compatibility with the latest Cypress versions. Key differentiators include highly configurable message exclusion via strings or regular expressions, dynamic configuration changes within individual tests using `getConfig()` and `setConfig()`, and the ability to observe various console log levels beyond just errors. Unlike manual `cy.stub` approaches, this plugin provides a streamlined and declarative way to enforce console cleanliness across an entire test suite.","status":"active","version":"5.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/nils-hoyer/cypress-fail-on-console-error","tags":["javascript","cypress","testing","console","e2e","component","typescript"],"install":[{"cmd":"npm install cypress-fail-on-console-error","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-fail-on-console-error","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-fail-on-console-error","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This plugin is an extension for Cypress and is unusable without it. It integrates directly into Cypress's test runner and lifecycle.","package":"cypress","optional":false}],"imports":[{"note":"The package primarily uses ESM for modern Cypress setups. For CommonJS, you might need `require('cypress-fail-on-console-error').default;` or ensure your `cypress.config.js` is set up for ESM.","wrong":"const failOnConsoleError = require('cypress-fail-on-console-error');","symbol":"failOnConsoleError","correct":"import failOnConsoleError from 'cypress-fail-on-console-error';"},{"note":"This is a named export, typically used as a TypeScript type for the configuration object.","wrong":"import Config from 'cypress-fail-on-console-error';","symbol":"Config","correct":"import { Config } from 'cypress-fail-on-console-error';"},{"note":"This is a named export, used as a TypeScript type for individual console message definitions when dynamically updating the config.","symbol":"ConsoleMessage","correct":"import { ConsoleMessage } from 'cypress-fail-on-console-error';"}],"quickstart":{"code":"/* cypress/support/e2e.ts or cypress/support/component.ts */\nimport failOnConsoleError, { Config } from 'cypress-fail-on-console-error';\n\nconst initialConfig: Config = {\n  consoleMessages: [\n    'You are using the development build of React.',\n    /Ignored API call error/,\n    // Example: Exclude specific errors from a third-party library\n    /^TypeError: Cannot read properties of undefined \\(reading 'property'\\) from libX/,\n  ],\n  consoleTypes: ['error', 'warn'], // Fail on errors and warnings\n  debug: false,\n};\n\n// Initialize the plugin globally with initial configuration\nfailOnConsoleError(initialConfig);\n\n// Optionally, expose commands to dynamically change config within tests\nconst { getConfig, setConfig } = failOnConsoleError(initialConfig);\nCypress.Commands.add('getConsoleErrorConfig', () => cy.wrap(getConfig()));\nCypress.Commands.add('setConsoleErrorConfig', (newConfig: Partial<Config>) =>\n  cy.wrap(setConfig({ ...getConfig(), ...newConfig }))\n);\n\n/* cypress/e2e/example.cy.ts */\ninterface CustomCommands {\n  getConsoleErrorConfig: () => Cypress.Chainable<Config>;\n  setConsoleErrorConfig: (config: Partial<Config>) => Cypress.Chainable<void>;\n}\ndeclare global {\n  namespace Cypress {\n    interface Chainable extends CustomCommands {}\n  }\n}\n\ndescribe('Console Error Testing', () => {\n  it('should pass if no console errors occur', () => {\n    cy.visit('https://example.com');\n    // Test actions that should not produce console errors\n    cy.contains('Example Domain').should('be.visible');\n  });\n\n  it('should fail if an unhandled console error occurs', () => {\n    // Simulate an error on the page. This test is expected to fail.\n    cy.visit('http://localhost:3000', {\n      onBeforeLoad(win) {\n        cy.stub(win.console, 'error').callsFake((message) => {\n          // Log the error to Cypress command log but allow it to trigger the plugin\n          cy.log(`App Console Error: ${message}`);\n          // Do NOT call original `win.console.error` to avoid double logging or stack overflow\n        });\n      },\n    });\n\n    cy.window().then((win) => {\n      win.eval(`console.error('This is an intentional error for testing!');`);\n    });\n    // The test will fail due to the console.error() call unless it's configured to be ignored.\n  });\n\n  it('should ignore a specific console error message', () => {\n    cy.setConsoleErrorConfig({\n      consoleMessages: ['Expected error message to ignore'],\n    });\n    cy.visit('http://localhost:3000', {\n      onBeforeLoad(win) {\n        cy.stub(win.console, 'error').callsFake((message) => {\n          cy.log(`App Console Error (stubbed): ${message}`);\n        });\n      },\n    });\n    cy.window().then((win) => {\n      win.eval(`console.error('Expected error message to ignore');`);\n    });\n    // This test should pass because the error message is configured to be ignored.\n    cy.contains('Example Domain').should('be.visible');\n  });\n});","lang":"typescript","description":"This quickstart demonstrates how to install and configure `cypress-fail-on-console-error` in your Cypress project. It shows global initialization in `support/e2e.ts` with initial exclusions and how to dynamically adjust the configuration (e.g., ignoring specific messages) within individual test files using custom Cypress commands. It includes an example test that is expected to fail due to an unhandled console error and another that passes by ignoring a configured error."},"warnings":[{"fix":"Upgrade your Cypress installation to version 12.12.0 or higher. Review Cypress's own changelog for breaking changes between your current version and v12.12.0+ and adapt your tests accordingly. If you encounter issues, refer to the plugin's GitHub repository for specific migration guides if available.","message":"Version 5.0.0 of `cypress-fail-on-console-error` updated its dependency on Cypress to v12.12.0. While not explicitly detailed in the changelog excerpt, major version bumps in Cypress plugins often imply breaking changes or dropped support for older Cypress versions. Users upgrading from `cypress-fail-on-console-error` v4.x should ensure their Cypress installation is compatible with v12.12.0 or newer.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure all special characters in string-based regular expressions are correctly escaped (e.g., `.` becomes `\\.`). When using RegExp literals, characters like `.` do not need double escaping, but understand RegExp syntax. For example, to match `foo.bar`, use `/^foo\\.bar$/` or `new RegExp('^foo\\\\.bar$')`.","message":"Regular expressions used in the `consoleMessages` configuration parameter require proper escaping of special characters. Failing to escape characters like `.`, `+`, `*`, `?`, `^`, `$`, `(`, `)`, `[`, `]`, `{`, `}`, `|`, `\\` can lead to unexpected matching behavior or syntax errors in your regular expressions.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If a test requires a specific console error configuration, apply it at the start of that test or in a `beforeEach` hook. For global test-specific configurations, create custom Cypress commands that wrap `setConfig` and use them appropriately within your tests.","message":"The plugin's configuration, when dynamically set using `setConfig()`, is reset to its initial state between Cypress tests. If you set a specific configuration for a test, ensure that it is applied within that test's `beforeEach` or `it` block, or by exposing Cypress commands as shown in the quickstart to manage the configuration consistently.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Integrate `cypress-fail-on-network-error` alongside this plugin if you need to fail tests based on network request failures (e.g., 4xx or 5xx HTTP responses). This provides a more complete error detection strategy for your application.","message":"This plugin specifically observes `window.console` messages in the browser. It will not catch network-related errors (e.g., failed API requests with non-2xx status codes) unless they explicitly log to `console.error` within the application code. For comprehensive network error observation, consider using a separate plugin like `cypress-fail-on-network-error`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For CommonJS, use `const failOnConsoleError = require('cypress-fail-on-console-error').default;`. For modern Cypress projects, prefer ESM `import failOnConsoleError from 'cypress-fail-on-console-error';` in your `cypress/support/e2e.ts` or `cypress.config.ts`.","cause":"Attempting to use `require('cypress-fail-on-console-error')` directly in a CommonJS context without accessing the default export.","error":"TypeError: failOnConsoleError is not a function"},{"fix":"Review the `consoleMessages` and `consoleTypes` configuration in your `cypress/support/e2e.ts` (or equivalent). Ensure the specific error message is not in the exclusion list and that the console type (e.g., 'error') is included in `consoleTypes`. Enable `debug: true` in the plugin's configuration to see detailed matching logs in the Cypress runner.","cause":"The console error message or type might be excluded by the plugin's configuration (`consoleMessages` or `consoleTypes`).","error":"The test did not fail even though there was a console error."},{"fix":"Ensure `Cypress.Commands.add` calls for your custom commands are present in your `cypress/support/e2e.ts` (or `e2e.js`) file. If using TypeScript, also add the `declare global { namespace Cypress { interface Chainable extends CustomCommands {} } }` block with your custom command interfaces to prevent type errors.","cause":"The custom Cypress commands (`getConsoleErrorConfig`, `setConsoleErrorConfig`) were not added to `Cypress.Commands` in the support file, or their TypeScript declarations are missing.","error":"Cypress commands like `cy.setConsoleErrorConfig` are not defined."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}