fix: add example and document the timeout option (#182)

* fix: add example and document the timeout option

* limit the release job

.github/workflows/ci.yml

@@ -14,12 +14,13 @@ jobs:
   release:
     runs-on: ubuntu-20.04
     needs: ['tests']
+    if: github.ref == 'refs/heads/main'
     steps:
       - name: Checkout 🛎
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Semantic Release 🚀
-        uses: cycjimmy/semantic-release-action@v3
+        uses: cycjimmy/semantic-release-action@v4
         with:
           branches: main
         env:

README.md

@@ -60,6 +60,22 @@ cy.waitForNetworkIdle('+(POST|GET)', '*', 5000)
 
 For pattern matching see more examples in the [`cy.intercept()` documentation](https://docs.cypress.io/api/commands/intercept#Pattern-Matching).
 
+## Timeouts
+
+Let's take this example
+
+```js
+cy.waitForNetworkIdle('POST', '/graphql', 5000)
+```
+
+The `5000` argument is the wait number in milliseconds. The command will check for 5 seconds with _no_ `POST /graphql` calls. But how long do we need to wait for those idle 5 seconds? By default, it is the maximum of `Cypress.config('responseTimeout')` value (usually 30 seconds in Cypress) and the three times the wait amount (in our case 15 seconds).
+
+You can set a longer time limit for waiting for network to be idle for 5 seconds. Let's wait for up to a minute for 5 second idle period:
+
+```js
+cy.waitForNetworkIdle('POST', '/graphql', 5000, { timeout: 60_000 })
+```
+
 ## No logging
 
 You can disable the log messages by adding option object with `{ log: false }` property

cypress/e2e/spec.js

@@ -1,4 +1,5 @@
 /// <reference path="../../src/index.d.ts" />
+// @ts-check
 
 import '../..'
 
@@ -88,3 +89,10 @@ it('no logging', () => {
   cy.waitForNetworkIdle('*', '/user', 1100, { log: false })
   cy.window().its('user').should('deep.equal', { name: 'Test User' })
 })
+
+it('waits for up to a minute', () => {
+  cy.intercept('GET', '/user', { name: 'Test User' })
+  cy.visit('/')
+  cy.waitForNetworkIdle('*', '/user', 1100, { timeout: 60_000 })
+  cy.window().its('user').should('deep.equal', { name: 'Test User' })
+})

src/index.d.ts

@@ -116,6 +116,7 @@ declare namespace Cypress {
      * @param method HTTP method to spy on
      * @param pattern URL pattern to spy on
      * @param waitMs Milliseconds after the last network call
+     * @param options Additional network options
      */
     waitForNetworkIdle(
       method: string,
@@ -137,6 +138,13 @@ declare namespace Cypress {
     method?: string
     pattern: string
     alias: string
+    /**
+     * Max time limit for waiting for the idle network period, ms
+     * @example
+     *  // wait for a 1-second idle period
+     *  // max waiting time is 5 seconds
+     *  cy.waitForNetworkIdle(1000, '*', { timeout: 5000 })
+     */
     timeout: number
     interval: number
     log?: boolean