Wait for a number of milliseconds or wait for an aliased resource to resolve before moving on to the next command.
Syntax
cy.wait(time) cy.wait(alias) cy.wait(aliases) cy.wait(time, options) cy.wait(alias, options) cy.wait(aliases, options)
Usage
Correct Usage
cy.wait(500) cy.wait('@getProfile')
Arguments
time (Number)
The amount of time to wait in milliseconds.
alias (String)
An aliased route as defined using the .as()
command and referenced with the @
character and the name of the alias.
Core ConceptYou can read more about aliasing routes in our Core Concept Guide.
aliases (Array)
An array of aliased routes as defined using the .as()
command and referenced with the @
character and the name of the alias.
options (Object)
Pass in an options object to change the default behavior of cy.wait()
.
Option | Default | Description |
---|---|---|
log | true | Displays the command in the Command log |
timeout |
requestTimeout , responseTimeout
| Time to wait for cy.wait() to resolve before timing out
|
requestTimeout | requestTimeout | Overrides the global requestTimeout for this request. Defaults to timeout . |
responseTimeout | responseTimeout | Overrides the global responseTimeout for this request. Defaults to timeout . |
Yields
When given a time
argument:
cy.wait()
yields the same subject it was given from the previous command.
When given an alias
argument:
cy.wait()
yields an object containing the HTTP request and response properties of the XHR.
🚨 Please be aware that Cypress only currently supports intercepting XMLHttpRequests. Requests using the Fetch API and other types of network requests like page loads and
<script>
tags will not be intercepted or visible in the Command Log. You can automatically polyfillwindow.fetch
to spy on and stub requests by enabling an experimental featureexperimentalFetchPolyfill
. See #95 for more details and temporary workarounds.Cypress also has a new experimental route2 feature that supports requests using the Fetch API and other types of network requests like page loads. For more information, check out the cy.route2() documentation.
Examples
Time
Wait for an arbitrary period of milliseconds:
cy.wait(2000) // wait for 2 seconds
Anti-PatternYou almost never need to wait for an arbitrary period of time. There are always better ways to express this in Cypress.
Read about best practices here.
Additionally, it is often much easier to use cy.debug()
or cy.pause()
when debugging your test code.
Alias
For a detailed explanation of aliasing, read more about waiting on routes here.
Wait for a specific XHR to respond
// Wait for the route aliased as 'getAccount' to respond // without changing or stubbing its response cy.server() cy.route('/accounts/*').as('getAccount') cy.visit('/accounts/123') cy.wait('@getAccount').then((xhr) => { // we can now access the low level xhr // that contains the request body, // response body, status, etc })
Wait automatically increments responses
Each time we use cy.wait()
for an alias, Cypress waits for the next nth matching request.
cy.server() cy.route('/books', []).as('getBooks') cy.get('#search').type('Grendel') // wait for the first response to finish cy.wait('@getBooks') // the results should be empty because we // responded with an empty array first cy.get('#book-results').should('be.empty') // now re-define the /books response cy.route('/books', [{ name: 'Emperor of all maladies' }]) cy.get('#search').type('Emperor of') // now when we wait for 'getBooks' again, Cypress will // automatically know to wait for the 2nd response cy.wait('@getBooks') // we responded with 1 book item so now we should // have one result cy.get('#book-results').should('have.length', 1)
Aliases
You can pass an array of aliases that will be waited on before resolving.
When passing an array of aliases to cy.wait()
, Cypress will wait for all requests to complete within the given requestTimeout
and responseTimeout
.
cy.server() cy.route('users/*').as('getUsers') cy.route('activities/*').as('getActivities') cy.route('comments/*').as('getComments') cy.visit('/dashboard') cy.wait(['@getUsers', '@getActivities', '@getComments']).then((xhrs) => { // xhrs will now be an array of matching XHR's // xhrs[0] <-- getUsers // xhrs[1] <-- getActivities // xhrs[2] <-- getComments })
Using .spread()
to spread the array into multiple arguments.
cy.server() cy.route('users/*').as('getUsers') cy.route('activities/*').as('getActivities') cy.route('comments/*').as('getComments') cy.wait(['@getUsers', '@getActivities', '@getComments']) .spread((getUsers, getActivities, getComments) => { // each XHR is now an individual argument })
Notes
Nesting
Cypress automatically waits for the network call to complete before proceeding to the next command.
// Anti-pattern: placing Cypress commands inside .then callbacks cy.wait('@alias') .then(() => { cy.get(...) }) // Recommended practice: write Cypress commands serially cy.wait('@alias') cy.get(...) // Example: assert response property before proceeding cy.wait('@alias').its('status').should('eq', 200) cy.get(...)
Read Guide: Introduction to Cypress
Timeouts
requestTimeout
and responseTimeout
When used with an alias, cy.wait()
goes through two separate “waiting” periods.
The first period waits for a matching request to leave the browser. This duration is configured by the requestTimeout
option - which has a default of 5000
ms.
This means that when you begin waiting for an aliased XHR, Cypress will wait up to 5 seconds for a matching XHR to be created. If no matching XHR is found, you will get an error message that looks like this:
Once Cypress detects that a matching XHR has begun its request, it then switches over to the 2nd waiting period. This duration is configured by the responseTimeout
option - which has a default of 20000
ms.
This means Cypress will now wait up to 20 seconds for the external server to respond to this XHR. If no response is detected, you will get an error message that looks like this:
This gives you the best of both worlds - a fast error feedback loop when requests never go out and a much longer duration for the actual external response.
Using an Array of Aliases
When passing an array of aliases to cy.wait()
, Cypress will wait for all requests to complete within the given requestTimeout
and responseTimeout
.
Rules
Requirements
When passed a
time
argumentcy.wait()
can be chained off ofcy
or off another command.When passed an
alias
argumentcy.wait()
requires being chained off ofcy
.
Assertions
cy.wait()
will only run assertions you've chained once, and will not retry.
Timeouts
cy.wait()
can time out waiting for request to go out.cy.wait()
can time out waiting for response to return.
Command Log
Wait for the PUT to users to resolve.
cy.server() cy.route('PUT', /users/, {}).as('userPut') cy.get('form').submit() cy.wait('@userPut').its('url').should('include', 'users')
The commands above will display in the Command Log as:
When clicking on wait
within the command log, the console outputs the following:
History
Version | Changes |
---|---|
3.1.3 | Added requestTimeout and responseTimout option |
< 0.3.3 |
cy.wait() command added |