Iterate through an array like structure (arrays or objects with a length property).

Syntax

.each(callbackFn)

Usage

Correct Usage

cy.get('ul>li').each(function () {...}) // Iterate through each 'li'
cy.getCookies().each(function () {...}) // Iterate through each cookie

Incorrect Usage

cy.each(function () {...})            // Errors, cannot be chained off 'cy'
cy.location().each(function () {...}) // Errors, 'location' doesn't yield an array

Arguments

callbackFn (Function)

Pass a function that is invoked with the following arguments:

value
index
collection

Yields

.each() yields the same subject it was given from the previous command.

Examples

DOM Elements

Iterate over an array of DOM elements

cy
  .get('ul>li')
  .each(($el, index, $list) => {
    // $el is a wrapped jQuery element
    if ($el.someMethod() === 'something') {
      // wrap this element so we can
      // use cypress commands on it
      cy.wrap($el).click()
    } else {
      // do something else
    }
  })

The original array is always yielded

No matter what is returned in the callback function, .each() will always yield the original array.

cy
  .get('li').should('have.length', 3)
  .each(($li, index, $lis) => {
    return 'something else'
  })
  .then(($lis) => {
    expect($lis).to.have.length(3) // true
  })

Promises

Promises are awaited

If your callback function returns a Promise, it will be awaited before iterating over the next element in the collection.

cy.wrap([1, 2, 3]).each((num, i, array) => {
  return new Cypress.Promise((resolve) => {
    setTimeout(() => {
      resolve()
    }, num * 100)
  })
})

Notes

Return early

Stop each prematurely

You can stop the .each() loop early by returning false in the callback function.

Rules

Requirements

.each() requires being chained off a previous command.

Assertions

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

Timeouts

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

Command Log

cy.each() does not log in the Command Log

W3cubDocs

each