Implementation:Webdriverio Webdriverio PIteration
| Knowledge Sources | |
|---|---|
| Domains | Async_Utilities, Array_Processing |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Provides async-aware array iteration methods that mirror the ES5 Array prototype, with both concurrent and series execution modes.
Description
The PIteration module implements Promise-based versions of standard array iteration methods. Each method comes in two variants: a concurrent version (e.g., forEach, map, filter) that runs all callbacks in parallel using Promise.all, and a series version (e.g., forEachSeries, mapSeries, filterSeries) that awaits each callback sequentially. The module covers the full complement of array methods: forEach, map, find, findIndex, some, every, filter, and reduce. All functions accept the standard callback signature (currentValue, index, array) and an optional thisArg context. The reduce function processes elements serially by nature, awaiting both the accumulator and current value.
Usage
Use these functions when iterating over arrays of WebdriverIO elements or performing async operations on collections. The concurrent variants are used internally by the shim module to enable chained element array operations like $$('div').map(elem => elem.getText()). Use series variants when operations must not overlap (e.g., sequential clicks or navigations).
Code Reference
Source Location
- Repository: Webdriverio_Webdriverio
- File: packages/wdio-utils/src/pIteration.ts
- Lines: 1-359
Signature
export const forEach: <T>(array: T[], callback: Function, thisArg?: T) => Promise<void>
export const forEachSeries: <T>(array: T[], callback: Function, thisArg?: T) => Promise<void>
export const map: <T>(array: T[], callback: Function, thisArg?: T) => Promise<any[]>
export const mapSeries: <T>(array: T[], callback: Function, thisArg?: T) => Promise<any[]>
export const find: <T>(array: T[], callback: Function, thisArg?: T) => Promise<T | undefined>
export const findSeries: <T>(array: T[], callback: Function, thisArg?: T) => Promise<T | undefined>
export const findIndex: <T>(array: T[], callback: Function, thisArg?: T) => Promise<number>
export const findIndexSeries: <T>(array: T[], callback: Function, thisArg?: T) => Promise<number | undefined>
export const some: <T>(array: T[], callback: Function, thisArg?: T) => Promise<boolean>
export const someSeries: <T>(array: T[], callback: Function, thisArg?: T) => Promise<boolean>
export const every: <T>(array: T[], callback: Function, thisArg?: T) => Promise<boolean>
export const everySeries: <T>(array: T[], callback: Function, thisArg?: T) => Promise<boolean>
export const filter: <T>(array: T[], callback: Function, thisArg?: T) => Promise<T[]>
export const filterSeries: <T>(array: T[], callback: Function, thisArg?: T) => Promise<T[]>
export const reduce: <T>(array: T[], callback: Function, initialValue?: T) => Promise<T>
Import
import { forEach, map, filter, reduce } from '@wdio/utils/pIteration'
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| array | T[] | Yes | The array to iterate over. May contain promises that are individually awaited in series variants. |
| callback | Function | Yes | Function applied to each element. Accepts (currentValue, index, array) for most methods; (accumulator, currentValue, currentIndex, array) for reduce. |
| thisArg | T | No | Value to use as this when executing the callback. |
| initialValue | T | No (reduce only) | Initial accumulator value for reduce. If omitted and array is empty, a TypeError is thrown. |
Outputs
| Name | Type | Description |
|---|---|---|
| forEach/forEachSeries | Promise<void> | Resolves when all callbacks have completed. |
| map/mapSeries | Promise<any[]> | Array of callback return values in original order. |
| find/findSeries | Promise<T or undefined> | First element passing the test, or undefined. |
| findIndex/findIndexSeries | Promise<number> | Index of first passing element, or -1 (undefined for series). |
| some/someSeries | Promise<boolean> | True if any element passes the test. |
| every/everySeries | Promise<boolean> | True if all elements pass the test. |
| filter/filterSeries | Promise<T[]> | Array of elements that pass the test. |
| reduce | Promise<T> | Final accumulated value. |
Usage Examples
import { map, filter, forEachSeries, reduce } from '@wdio/utils/pIteration'
// Get text from all matching elements concurrently
const elements = await $$('.item')
const texts = await map(elements, async (elem) => {
return elem.getText()
})
// Filter elements that are displayed
const visibleElements = await filter(elements, async (elem) => {
return elem.isDisplayed()
})
// Click each element sequentially
await forEachSeries(elements, async (elem) => {
await elem.click()
await browser.pause(500)
})
// Sum up numeric values from elements
const total = await reduce(elements, async (acc, elem) => {
const text = await elem.getText()
return acc + parseInt(text, 10)
}, 0)