Built-in ListPageObject Class
Relevant source files
The following files were used as context for generating this wiki page:
The ListPageObject class is a specialized component of the playwright-page-object framework designed to handle collections of repeated UI elements. It provides a typed, decorator-driven approach to managing lists, offering built-in support for filtering, indexing, and asynchronous iteration. By extending the base PageObject, it inherits wait helpers and assertion capabilities while adding specific logic for resolving child item instances.
Sources: src/page-objects/ListPageObject.ts:1-25, README.md:158-170
Architecture and Core Logic
ListPageObject acts as a container for a specific type of child element, referred to as TItem. It utilizes a SelectorType function to resolve its own root locator and then applies further selection logic to instantiate individual items. The class is designed to work seamlessly with child decorators like @ListSelector and @ListStrictSelector.
Item Resolution Strategy
When an item is accessed (e.g., via index or filter), ListPageObject uses a internal resolveItem method. This method determines how to instantiate the child based on the itemType provided during construction:
- Class Reference: If a
PageObjectsubclass is provided, it creates a new instance using the standard constructor. - Instance Template: If an existing instance is provided, it calls
cloneWithContext()to replicate the item with the specific locator of the list element. - Plain PageObject: If no
itemTypeis provided, it defaults to returning a basicPageObjectinstance.
Sources: src/page-objects/ListPageObject.ts:200-218, src/tests/page-objects/ListPageObject.spec.ts:58-95
Class Relationship Diagram
The following diagram illustrates how ListPageObject inherits from PageObject and its relationship with the items it manages.
Key Features and API
Indexed and Collection Access
The items property is a Proxy that facilitates several access patterns, including numeric indexing and negative indexing (similar to Array.at()).
| Method / Property | Description |
|---|---|
items[index] | Returns the item at the specified 0-based index. |
items.at(index) | Returns the item at the index; supports negative integers for end-relative access. |
first() / last() | Convenience methods for at(0) and at(-1). |
count() | Returns a promise resolving to the number of elements found by the locator. |
getAll() | Asynchronously retrieves all items in the list as an array of instances. |
Sources: src/page-objects/ListPageObject.ts:133-198, README.md:172-180
Filtering Logic
ListPageObject provides several methods to narrow down the collection based on Playwright-native filtering or text matching.
Async Iteration
The class supports the for await...of syntax for iterating over items. This is preferred over synchronous iteration because the count of elements and the elements themselves are resolved dynamically from the browser state.
// Example from implementation
for await (const item of checkoutPage.CartItems.items) {
await item.expect({ soft: true }).toBeVisible();
}
Sources: src/page-objects/ListPageObject.ts:153-159, example/README.md:65-69
Implementation Example
In a typical Page Object Model, the ListPageObject is initialized within a root class using a selector decorator.
@RootSelector("CheckoutPage")
export class CheckoutPage extends RootPageObject {
// List with a custom item control (CartItemControl)
@ListStrictSelector("CartItem")
accessor CartItems = new ListPageObject(CartItemControl);
// List returning generic PageObject instances
@ListStrictSelector("GenericItem")
accessor GenericList = new ListPageObject();
}
Sources: example/e2e/page-objects/CheckoutPage.ts:15-32, skills/playwright-page-object/SKILL.md:120-135
Sequence: Item Resolution
This diagram shows the sequence of events when a developer accesses a specific item in a list.
Summary
The ListPageObject class provides a robust abstraction for handling repeatable elements in Playwright. By combining a Proxy-based access layer with flexible item resolution (supporting classes, instances, or default objects), it allows developers to model complex UI collections with minimal boilerplate while maintaining full type safety and access to the underlying Playwright Locator API via the $ property.
Sources: src/page-objects/ListPageObject.ts:1-10, example/README.md:23-31