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.
npm install cypress-fail-on-console-errorVerified import paths — ran on the pinned version, not inferred.
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.
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.
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$')`.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.
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.
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`.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.
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.