{"id":13044,"library":"cypress-fail-on-network-error","title":"Cypress Fail on Network Error","description":"cypress-fail-on-network-error is a Cypress plugin designed to automatically fail tests when network requests made during their execution encounter specified error conditions. This allows for proactive identification of backend issues, broken API endpoints, or unexpected HTTP status codes directly within the Cypress test suite. The current stable version is 1.0.5, with releases primarily focused on dependency updates (especially Cypress itself) and minor enhancements. It differentiates itself by offering fine-grained configuration to define which network errors (based on URL patterns, HTTP methods, and status codes or ranges) should trigger a test failure, and provides utilities to dynamically adjust this configuration during tests and wait for pending requests to resolve. This offers more control than relying solely on server-side logging or general test timeouts, providing immediate feedback on client-server interaction health.","status":"active","version":"1.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/nils-hoyer/cypress-fail-on-network-error","tags":["javascript","cypress","testing","network","request","response","error","typescript"],"install":[{"cmd":"npm install cypress-fail-on-network-error","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-fail-on-network-error","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-fail-on-network-error","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This is a Cypress plugin and requires Cypress to function.","package":"cypress","optional":false}],"imports":[{"note":"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.","wrong":"const failOnNetworkError = require('cypress-fail-on-network-error');","symbol":"failOnNetworkError","correct":"import failOnNetworkError from 'cypress-fail-on-network-error';"},{"note":"These are named type exports used for TypeScript type annotations when defining the plugin's configuration.","wrong":"import Config from 'cypress-fail-on-network-error';","symbol":"Config, Request","correct":"import { Config, Request } from 'cypress-fail-on-network-error';"},{"note":"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.","wrong":"import { getConfig, setConfig } from 'cypress-fail-on-network-error';","symbol":"getConfig, setConfig, waitForRequests","correct":"const { getConfig, setConfig, waitForRequests } = failOnNetworkError(initialConfig);"}],"quickstart":{"code":"npm install cypress-fail-on-network-error --save-dev\n\n// cypress/support/e2e.ts or e2e.js\nimport failOnNetworkError, { Config, Request } from 'cypress-fail-on-network-error';\n\nconst initialConfig: Config = {\n    requests: [\n        // Exclude specific URLs from causing failures\n        'http://example.com/api/healthcheck',\n        { url: 'http://example.com/api/ignored-error', method: 'GET', status: 404 },\n        // Define general conditions that should cause failure\n        { status: { from: 500, to: 599 } }, // All 5xx server errors\n        { url: /critical-api/, status: 400 } // Bad requests to critical-api\n    ]\n};\n\nconst pluginInstance = failOnNetworkError(initialConfig);\nconst { getConfig, setConfig, waitForRequests } = pluginInstance;\n\n// Optionally expose methods as Cypress commands for use in tests\nCypress.Commands.addAll({\n    getConfigRequests: () => {\n        return cy.wrap(getConfig().requests);\n    },\n    setConfigRequests: (requests: (string | Request)[]) => {\n        setConfig({ ...getConfig(), requests });\n    },\n    waitForAllNetworkRequests: (timeout?: number) => waitForRequests(timeout)\n});\n\n// cypress/e2e/my-test.cy.ts\ndescribe('Network Error Handling', () => {\n    it('should pass if no configured network errors occur', () => {\n        // Example: simulate a successful page load with no network issues\n        cy.intercept('GET', '/data', { statusCode: 200, body: { message: 'success' } }).as('getData');\n        cy.visit('http://localhost:3000');\n        cy.get('body').contains('Welcome');\n        cy.waitForAllNetworkRequests();\n    });\n\n    it('should fail a test if a configured network error happens', () => {\n        // This test would fail because a 500 error for /api/critical-data is configured to fail\n        cy.intercept('GET', '/api/critical-data', { statusCode: 500, body: { error: 'server fault' } }).as('criticalError');\n        cy.visit('http://localhost:3000/dashboard');\n        cy.wait('@criticalError');\n        // The plugin will automatically fail the test here due to the 500 status code.\n        // No explicit assertion needed for the failure condition.\n    });\n\n    it('should dynamically update config for a specific test', () => {\n        // Temporarily ignore a 404 error for this specific test\n        cy.setConfigRequests(['/api/missing-resource', ...initialConfig.requests]);\n        cy.intercept('GET', '/api/missing-resource', { statusCode: 404 }).as('missing');\n        cy.visit('http://localhost:3000/product/123');\n        cy.wait('@missing');\n        cy.waitForAllNetworkRequests();\n        // This test would now pass because the 404 to /api/missing-resource is explicitly ignored.\n    });\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Initialize the plugin once in `cypress/support/e2e.ts` with a base configuration. Use `cy.setConfigRequests()` in `beforeEach` or `it` blocks to modify the behavior for specific tests or test suites, always considering the default configuration is restored between tests.","message":"The plugin's configuration for network errors is applied globally across all tests once initialized. Be mindful when running tests that intentionally trigger errors or specific status codes. If you need different error handling for individual tests, use `setConfigRequests` within `beforeEach` or specific `it` blocks, remembering that the config resets between tests.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If you need to catch both network and console errors, consider installing `cypress-fail-on-console-error` alongside this plugin and configuring both in your Cypress setup.","message":"This plugin focuses on observing network requests. For errors logged to the browser's console (e.g., JavaScript runtime errors, console.error calls), you would need to use a separate plugin like `cypress-fail-on-console-error`. Combining both might be necessary for comprehensive error catching.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always keep Cypress and its related plugins updated. If issues arise after a Cypress upgrade, check the `cypress-fail-on-network-error` GitHub repository for compatibility notes or update to the latest version of the plugin.","message":"While not explicitly breaking the plugin's API, frequent updates to Cypress (as seen in release notes) mean users should ensure their `cypress-fail-on-network-error` version is compatible with their installed Cypress version to avoid unexpected behavior or integration issues.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Adjust the timeout for `waitForRequests(timeoutInMs)` if your application commonly has slower network activity. For critical requests, use `cy.wait('@alias')` for explicit waiting on specific intercepted requests.","message":"The `waitForRequests()` utility has a default timeout of 10000 ms. If your application or specific network requests are consistently slower than this, `waitForRequests()` will continue test execution without throwing an exception, potentially leading to race conditions where subsequent assertions run before all relevant requests have completed.","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":"Ensure 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.","cause":"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.","error":"TypeError: failOnNetworkError is not a function"},{"fix":"Verify 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.","cause":"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`).","error":"Cypress command 'setConfigRequests' (or similar) failed because it is not a function."},{"fix":"Carefully 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.","cause":"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.","error":"Test passes unexpectedly, despite observing network errors in dev tools."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}