W3cubDocs

/Cypress

spread

Expand an array into multiple arguments.

Identical to .then(), but always expects an array-like structure as its subject.

Syntax

.spread(callbackFn)
.spread(options, callbackFn)

Usage

Correct Usage

cy.getCookies().spread(() => {}) // Yield all cookies

Incorrect Usage

cy.spread(() => {}) // Errors, cannot be chained off 'cy'
cy.location().spread()   // Errors, 'location' does not yield an array

Arguments

fn (Function)

Pass a function that expands the array into its arguments.

options (Object)

Pass in an options object to change the default behavior of .spread().

Option Default Description
timeout defaultCommandTimeout Time to wait for .spread() to resolve before timing out

Yields

  • .spread() yields the return value of your callback function.

  • .spread() will not change the subject if null or undefined is returned.

Examples

Aliased Routes

Expand the array of aliased routes

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

Cookies

Expand the array of cookies

cy.getCookies().spread((cookie1, cookie2, cookie3) => {
  // each cookie is now an individual argument
})

Rules

Requirements

  • .spread() requires being chained off a previous command.

  • .spread() requires being chained off of a command that yields an array-like structure.

Assertions

  • .spread() will only run assertions you've chained once, and will not retry.

Timeouts

  • .spread() can time out waiting for a promise you've returned to resolve.

Command Log

.spread() does not log in the Command Log

History

Version Changes
0.5.9 .spread() command added

See also

© 2020 Cypress.io
Licensed under the MIT License.
https://docs.cypress.io/api/commands/spread.html