Registry /
testing / cypress-fail-on-network-error
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
failOnNetworkError
✓ import failOnNetworkError from 'cypress-fail-on-network-error';
✗ const failOnNetworkError = require('cypress-fail-on-network-error');
The primary default export is a function that initializes the plugin with a configuration and returns an object containing utility methods like `getConfig`, `setConfig`, and `waitForRequests`. This package is primarily ESM.
Config, Request
✓ import { Config, Request } from 'cypress-fail-on-network-error';
✗ import Config from 'cypress-fail-on-network-error';
These are named type exports used for TypeScript type annotations when defining the plugin's configuration.
getConfig, setConfig, waitForRequests
✓ const { getConfig, setConfig, waitForRequests } = failOnNetworkError(initialConfig);
✗ import { getConfig, setConfig } from 'cypress-fail-on-network-error';
These utility functions are methods of the object returned when the default `failOnNetworkError` function is called with a configuration, not direct named exports from the module root. They allow for dynamic interaction with the plugin's state during a test run.
This quickstart demonstrates how to install `cypress-fail-on-network-error`, configure it in Cypress's e2e support file with specific error conditions and exclusions, and how to use its methods (exposed as Cypress commands) to control network error detection within your tests, including dynamically updating the configuration and waiting for requests.
npm install cypress-fail-on-network-error --save-dev
// cypress/support/e2e.ts or e2e.js
import failOnNetworkError, { Config, Request } from 'cypress-fail-on-network-error';
const initialConfig: Config = {
requests: [
// Exclude specific URLs from causing failures
'http://example.com/api/healthcheck',
{ url: 'http://example.com/api/ignored-error', method: 'GET', status: 404 },
// Define general conditions that should cause failure
{ status: { from: 500, to: 599 } }, // All 5xx server errors
{ url: /critical-api/, status: 400 } // Bad requests to critical-api
]
};
const pluginInstance = failOnNetworkError(initialConfig);
const { getConfig, setConfig, waitForRequests } = pluginInstance;
// Optionally expose methods as Cypress commands for use in tests
Cypress.Commands.addAll({
getConfigRequests: () => {
return cy.wrap(getConfig().requests);
},
setConfigRequests: (requests: (string | Request)[]) => {
setConfig({ ...getConfig(), requests });
},
waitForAllNetworkRequests: (timeout?: number) => waitForRequests(timeout)
});
// cypress/e2e/my-test.cy.ts
describe('Network Error Handling', () => {
it('should pass if no configured network errors occur', () => {
// Example: simulate a successful page load with no network issues
cy.intercept('GET', '/data', { statusCode: 200, body: { message: 'success' } }).as('getData');
cy.visit('http://localhost:3000');
cy.get('body').contains('Welcome');
cy.waitForAllNetworkRequests();
});
it('should fail a test if a configured network error happens', () => {
// This test would fail because a 500 error for /api/critical-data is configured to fail
cy.intercept('GET', '/api/critical-data', { statusCode: 500, body: { error: 'server fault' } }).as('criticalError');
cy.visit('http://localhost:3000/dashboard');
cy.wait('@criticalError');
// The plugin will automatically fail the test here due to the 500 status code.
// No explicit assertion needed for the failure condition.
});
it('should dynamically update config for a specific test', () => {
// Temporarily ignore a 404 error for this specific test
cy.setConfigRequests(['/api/missing-resource', ...initialConfig.requests]);
cy.intercept('GET', '/api/missing-resource', { statusCode: 404 }).as('missing');
cy.visit('http://localhost:3000/product/123');
cy.wait('@missing');
cy.waitForAllNetworkRequests();
// This test would now pass because the 404 to /api/missing-resource is explicitly ignored.
});
});
Errors
Common errors & fixes
TypeError: failOnNetworkError is not a function
Attempting to import the plugin using CommonJS `require()` syntax in a project that is configured for ESM, or directly calling `require()` on a module that is primarily ESM.
fixEnsure you are using ESM `import failOnNetworkError from 'cypress-fail-on-network-error';` in your `cypress/support/e2e.js` (or `.ts`) file, and that your Cypress project's configuration (e.g., `cypress.config.js`) supports ESM.
Cypress command 'setConfigRequests' (or similar) failed because it is not a function.
The Cypress commands for `getConfigRequests`, `setConfigRequests`, or `waitForAllNetworkRequests` (or whatever custom names you chose) were not properly added to `Cypress.Commands.addAll` in your support file (`cypress/support/e2e.js` or `.ts`).
fixVerify that your `cypress/support/e2e.js` (or `.ts`) file correctly initializes the plugin and exposes its methods as Cypress commands using `Cypress.Commands.addAll`. Reload Cypress after making changes to the support file.
Test passes unexpectedly, despite observing network errors in dev tools.
The `requests` configuration in `failOnNetworkError` is either too broad (excluding too much) or too specific (not matching the actual error-inducing requests). URLs, methods, or status codes might not precisely align with the network calls being made by your application under test.
fixCarefully review your `requests` array configuration. Use browser developer tools or Cypress's `cy.intercept` to log and inspect the exact URLs, methods, and status codes of the network requests. Adjust your `requests` patterns (strings, RegExps) and conditions accordingly.
Audit
Dependencies
cypressrequiredThis is a Cypress plugin and requires Cypress to function.