{"id":13043,"library":"cypress-network-idle","title":"Cypress Network Idle","description":"cypress-network-idle is a Cypress plugin that extends the `cy` command set, enabling testers to wait for a specified period of network inactivity before test execution continues. Currently at stable version 2.0.1, the library sees active development with frequent patch releases and occasional minor updates (e.g., v1.15.0 in Jan 2025, v2.0.0 in March 2026). Its core differentiator lies in its flexibility: it allows specifying HTTP methods, URL patterns (using `cy.intercept` compatible patterns), and the duration of the idle period. Unlike simple `cy.wait()`, this plugin ensures that all network activity matching the criteria has ceased for a continuous duration. It also supports 'preparing' the network listener before an action (like `cy.visit`) and offers options to fail tests if matching network calls result in 4xx or 5xx status codes, providing robust error handling for network-dependent tests.","status":"active","version":"2.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/bahmutov/cypress-network-idle","tags":["javascript","cypress-plugin","network","typescript"],"install":[{"cmd":"npm install cypress-network-idle","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-network-idle","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-network-idle","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, required to provide the `cy` commands it augments.","package":"cypress","optional":false}],"imports":[{"note":"This plugin augments the global Cypress `cy` object. You import the package for its side effects to register the commands, not for named exports. This is the correct way to add custom commands to Cypress. Since v2.0.0, the import path `cypress-network-idle/src/support` is deprecated and replaced by this direct import.","wrong":"import { waitForNetworkIdle } from 'cypress-network-idle'","symbol":"Cypress Commands (Global)","correct":"import 'cypress-network-idle'"},{"note":"This command becomes available on the `cy` object after importing the plugin. It waits for the network to be idle for the specified duration (e.g., 2000ms). It can take arguments for method, pattern, and options.","symbol":"cy.waitForNetworkIdle","correct":"cy.waitForNetworkIdle(2000)"},{"note":"This command initiates network listening for later use with `cy.waitForNetworkIdle('@alias', duration)`. Useful when network calls are triggered by an action like `cy.visit` that happens before you want to wait.","symbol":"cy.waitForNetworkIdlePrepare","correct":"cy.waitForNetworkIdlePrepare({ method: 'GET', pattern: '*', alias: 'calls' })"}],"quickstart":{"code":"import 'cypress-network-idle'\n\ndescribe('Network Idle Testing', () => {\n  it('waits for the network to be idle after page load', () => {\n    // First, prepare to listen for all GET requests and assign an alias\n    cy.waitForNetworkIdlePrepare({\n      method: 'GET',\n      pattern: '*', // Catch all GET requests\n      alias: 'allGetCalls',\n      log: false // Disable verbose logging for this preparation step\n    })\n\n    // Visit the page, which will trigger network requests\n    cy.visit('https://example.cypress.io/commands/network-requests')\n\n    // After visiting, wait for the aliased network calls to be idle for 1 second\n    // The default timeout for this command will be Cypress.config('responseTimeout') or 3 times the idle wait duration, whichever is larger.\n    cy.waitForNetworkIdle('@allGetCalls', 1000, {\n      timeout: 30000, // Explicitly set a max wait time for the idle period (e.g., 30 seconds)\n      failOnStatusCode: true // Fail the test if any intercepted request returns a 4xx/5xx status\n    })\n\n    cy.log('Network was idle for 1 second, proceeding with test.')\n    cy.contains('.network-btn', 'Get Comment').click()\n\n    // Wait for a POST request to a specific endpoint to be idle after interaction\n    cy.waitForNetworkIdle('POST', '/comments/*', 500, {\n      timeout: 10000 // Shorter timeout for a specific interaction\n    })\n    cy.get('.network-comment').should('contain', 'Laudantium')\n  })\n})","lang":"typescript","description":"Demonstrates how to use `cy.waitForNetworkIdlePrepare` before a `cy.visit` and then `cy.waitForNetworkIdle` to ensure network quiescence before proceeding. Also shows waiting for specific POST requests after user interaction and configuring timeouts and error handling."},"warnings":[{"fix":"Update your `cypress/support/e2e.js` (or equivalent) file from `import 'cypress-network-idle/src/support'` to simply `import 'cypress-network-idle'`.","message":"The import path for the plugin changed in v2.0.0. Previously, users would import from a specific support file (`cypress-network-idle/src/support`). This path is now deprecated.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Configure both the idle duration and the `timeout` option thoughtfully, ensuring the `timeout` is long enough for intermittent network activity to eventually settle, but not excessively long to cause slow tests. `cy.waitForNetworkIdle(IDLE_TIME, { timeout: TOTAL_WAIT_TIME })`","message":"Understanding the difference between the `idle` duration and the `timeout` option is crucial. The idle duration (e.g., `2000` in `cy.waitForNetworkIdle(2000)`) is the continuous period of inactivity required. The `timeout` option (e.g., `{ timeout: 60000 }`) is the maximum total time Cypress will wait for that idle period to occur. If the network never becomes idle for the specified duration within the overall timeout, the command will fail.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add `failOn4xx: true` or `failOn5xx: true` (or `failOnStatusCode: true` for both) to the options object for `cy.waitForNetworkIdle` or `cy.waitForNetworkIdlePrepare`. Example: `cy.waitForNetworkIdle('GET', '/api', 1000, { failOnStatusCode: true })`.","message":"By default, network calls returning 4xx or 5xx status codes do not cause `cypress-network-idle` to fail the test. If your application's expected behavior is that network errors should fail the test, you must explicitly enable this option.","severity":"gotcha","affected_versions":">=1.12.0"},{"fix":"Ensure you are using a recent version of Cypress (v10+ is recommended for `cy.intercept` stability) and that your `cy.intercept` patterns correctly match the network calls you intend to monitor. The plugin automatically intercepts all requests when not given specific patterns.","message":"The plugin relies on Cypress's `cy.intercept` functionality. If `cy.intercept` is not properly set up or if requests are not being intercepted (e.g., due to an older Cypress version or misconfiguration), the plugin may not accurately track network activity.","severity":"gotcha","affected_versions":"<12.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `import 'cypress-network-idle'` to your `cypress/support/e2e.js` (or `index.js` for older Cypress) file, or directly into your spec file if only needed in specific tests.","cause":"The cypress-network-idle plugin has not been imported into your Cypress support file or spec file.","error":"cy.waitForNetworkIdle is not a function"},{"fix":"Increase the `timeout` option in your `cy.waitForNetworkIdle` command, or review your application's network behavior to understand why it's not achieving quiescence. Example: `cy.waitForNetworkIdle(1000, { timeout: 45000 })`.","cause":"The network did not remain idle for the specified `idle` duration within the overall `timeout` period. This often indicates continuous background requests or a `timeout` value that is too short.","error":"CypressError: `cy.waitForNetworkIdle` timed out waiting for the network to be idle. Expected to be idle for X ms within Y ms."},{"fix":"Ensure `failOn4xx`, `failOn5xx`, or `failOnStatusCode` are correctly spelled and set to a boolean `true` or `false` in the options object. E.g., `cy.waitForNetworkIdle(..., { failOn4xx: true })`.","cause":"Incorrect usage of `failOn4xx` or `failOn5xx` options, possibly passing a non-boolean value or misspelling the option.","error":"Expected `failOn4xx` or `failOn5xx` to be a boolean, but got `undefined`."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":""}