mirror of
https://github.com/cypress-io/cypress.git
synced 2026-05-19 06:38:45 -05:00
Jennifer Mann
85 lines
2.1 KiB
Markdown
85 lines
2.1 KiB
Markdown
---
|
|
title: each
|
|
comments: true
|
|
description: ''
|
|
---
|
|
|
|
The `cy.each()` will iterate through an array like structure (arrays and objects with a `length` property).
|
|
|
|
Each time the callback function runs, it is invoked with three arguments: `value`, `index`, and `collection`.
|
|
|
|
If your callback function returns a `Promise` it will be awaited before iterating over the next element in the collection.
|
|
|
|
You can stop the loop early by returning `false` in the callback function.
|
|
|
|
| | |
|
|
|--- | --- |
|
|
| **Returns** | the original array subject given to `cy.each()` |
|
|
| **Timeout** | `cy.each` will retry for the duration of the [`defaultCommandTimeout`](https://on.cypress.io/guides/configuration#timeouts) |
|
|
|
|
# [cy.each( *function* )](#usage)
|
|
|
|
Iterate over an array-like structure.
|
|
|
|
# Usage
|
|
|
|
## Iterate over an array of DOM elements
|
|
|
|
```javascript
|
|
cy
|
|
.get('ul>li')
|
|
.each(function($el, index, $list){
|
|
// $el is 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
|
|
}
|
|
})
|
|
```
|
|
|
|
## Promises are awaited
|
|
|
|
```javascript
|
|
cy
|
|
.wrap([1,2,3])
|
|
.each(function(num, index, array){
|
|
// promises returned are automatically
|
|
// awaited on before calling the next item
|
|
return new Cypress.Promise(function(resolve){
|
|
setTimeout(function(){
|
|
resolve()
|
|
}, num * 100)
|
|
})
|
|
})
|
|
```
|
|
|
|
## The original subject is always returned
|
|
|
|
```javascript
|
|
cy
|
|
.get('li').should('have.length', 3)
|
|
.each(function($li, index, $lis){
|
|
// no matter what we return here
|
|
// the next subject will still
|
|
// be the collection of <li>
|
|
return 'something else'
|
|
})
|
|
.then(function($lis){
|
|
expect($lis).to.have.length(3) // true
|
|
})
|
|
```
|
|
|
|
# Errors
|
|
|
|
## cy.each() can only operate on an array like subject.
|
|
|
|
This error occurs when the subject passed to `cy.each()` does not have a `length` property. Ensure the subject passed to `cy.each()` is an array-like structure.
|
|
|
|
# See also
|
|
|
|
- [spread](https://on.cypress.io/api/spread)
|
|
- [then](https://on.cypress.io/api/then)
|