Registry / testing / cypress-network-idle

cypress-network-idle

library2.0.1jsnpmunverified

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.

testing http-networking

npm install cypress-network-idle

github ↗package ↗

INSTALL

IMPORT

SIG · CYPRESS-NETWORK-ID

cypress-network-idle

testingjavascriptv2.0.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Cypress Commands (Global)

✓ import 'cypress-network-idle'

✗ import { waitForNetworkIdle } from 'cypress-network-idle'

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.

cy.waitForNetworkIdle

✓ cy.waitForNetworkIdle(2000)

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.

cy.waitForNetworkIdlePrepare

✓ cy.waitForNetworkIdlePrepare({ method: 'GET', pattern: '*', alias: 'calls' })

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.

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.

import 'cypress-network-idle' describe('Network Idle Testing', () => { it('waits for the network to be idle after page load', () => { // First, prepare to listen for all GET requests and assign an alias cy.waitForNetworkIdlePrepare({ method: 'GET', pattern: '*', // Catch all GET requests alias: 'allGetCalls', log: false // Disable verbose logging for this preparation step }) // Visit the page, which will trigger network requests cy.visit('https://example.cypress.io/commands/network-requests') // After visiting, wait for the aliased network calls to be idle for 1 second // The default timeout for this command will be Cypress.config('responseTimeout') or 3 times the idle wait duration, whichever is larger. cy.waitForNetworkIdle('@allGetCalls', 1000, { timeout: 30000, // Explicitly set a max wait time for the idle period (e.g., 30 seconds) failOnStatusCode: true // Fail the test if any intercepted request returns a 4xx/5xx status }) cy.log('Network was idle for 1 second, proceeding with test.') cy.contains('.network-btn', 'Get Comment').click() // Wait for a POST request to a specific endpoint to be idle after interaction cy.waitForNetworkIdle('POST', '/comments/*', 500, { timeout: 10000 // Shorter timeout for a specific interaction }) cy.get('.network-comment').should('contain', 'Laudantium') }) })

Debug

Known issues

breakingThe 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.

fix

Update your `cypress/support/e2e.js` (or equivalent) file from `import 'cypress-network-idle/src/support'` to simply `import 'cypress-network-idle'`.

affects: >=2.0.0

gotchaUnderstanding 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.

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 })`

affects: >=1.0.0

gotchaBy 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.

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 })`.

affects: >=1.12.0

gotchaThe 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.

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.

affects: <12.0.0

Errors

Common errors & fixes

cy.waitForNetworkIdle is not a function

The cypress-network-idle plugin has not been imported into your Cypress support file or spec file.

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.

CypressError: `cy.waitForNetworkIdle` timed out waiting for the network to be idle. Expected to be idle for X ms within Y ms.

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.

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 })`.

Expected `failOn4xx` or `failOn5xx` to be a boolean, but got `undefined`.

Incorrect usage of `failOn4xx` or `failOn5xx` options, possibly passing a non-boolean value or misspelling the option.

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 })`.

Upgrade

Version history

2.0.1latest on npm

Audit

Dependencies

cypressrequiredPeer dependency, required to provide the `cy` commands it augments.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/bahmutov/cypress-network-idle ↗

packagehttps://www.npmjs.com/package/cypress-network-idle ↗