Assertions and Wait Helpers

Relevant source files

The following files were used as context for generating this wiki page:

• src/page-objects/PageObject.ts
• README.md
• skills/playwright-page-object/SKILL.md
• src/tests/page-objects/PageObject.spec.ts
• example/e2e/checkout.spec.ts
• src/page-objects/ListPageObject.ts

Assertions and Wait Helpers in the playwright-page-object framework provide a high-level, readable API for validating application state and managing asynchronous UI transitions. These utilities are primarily encapsulated within the PageObject base class and its derivatives, abstracting raw Playwright expect calls into semantic methods like waitVisible() or waitText().

The system is designed to be version-agnostic by exposing a raw locator via the $ property, while simultaneously offering a "batteries-included" POM layer for common validation patterns. This allows developers to choose between low-level Playwright assertions and high-level framework-provided helpers.

Sources: README.md:144-154, skills/playwright-page-object/SKILL.md:113-118

Core Assertion Architecture

The framework leverages Playwright's native expect library but wraps it to provide context-aware assertions. The PageObject class serves as the primary provider for these capabilities.

The expect() Method

The expect() method is the gateway to all assertions within a page object. It returns a Playwright assertion API specifically bound to the page object's resolved locator.

• Standard Assertions: Returns expect(locator).
• Soft Assertions: Returns expect.soft(locator) when the soft: true option is provided, allowing tests to continue even if the assertion fails.
• Custom Messages: Supports passing a custom error message to improve failure diagnostics.

Sources: src/page-objects/PageObject.ts:182-195, src/tests/page-objects/PageObject.spec.ts:241-274

Data Flow for Assertions

The following diagram illustrates how an assertion call flows from a high-level helper down to the Playwright engine.

Semantic Wait Helpers

PageObject provides a suite of asynchronous methods that wait for specific conditions to be met. These methods utilize the internal expect() mechanism to perform retriable checks.

Available Wait Methods

Method	Description	Derived Playwright Assertion
waitVisible()	Waits for the element to become visible.	toBeVisible()
waitHidden()	Waits for the element to become hidden.	toBeHidden()
waitText(text)	Waits for the element to contain specific text.	toHaveText(text)
waitValue(value)	Waits for an input element to have a specific value.	toHaveValue(value)
waitNoValue()	Waits for the element to have no value attribute.	not.toHaveAttribute('value')
waitCount(n)	Waits for the locator to resolve to exactly n elements.	toHaveCount(n)
waitChecked()	Waits for a checkbox or radio button to be checked.	toBeChecked()
waitUnChecked()	Waits for a checkbox/radio to be unchecked.	not.toBeChecked()
waitProp(name, val)	Waits for a data attribute (prop) to match a value.	toHaveAttribute(data-name, val)

Sources: src/page-objects/PageObject.ts:110-175, README.md:162-171

Implementation Example

The wait helpers are implemented by calling the internal expect() method and chaining the appropriate Playwright matcher:

// src/page-objects/PageObject.ts
async waitVisible() {
    await this.expect().toBeVisible();
}

async waitProp(name: string, value: string) {
    await this.expect({
        message: `Waiting for prop «${name}» to be equal to «${value}»`,
    }).toHaveAttribute(prop(name), value);
}

Sources: src/page-objects/PageObject.ts:111-113, src/page-objects/PageObject.ts:160-165

Assertions in List Contexts

ListPageObject extends assertion capabilities to collections of elements. It allows for validating the state of the entire list or specific filtered subsets.

List Validation Features

• Count Validation: Using waitCount(n) on a list to ensure the correct number of items are rendered.
• Filtered Assertions: Using filterByText(text) combined with expect() to validate specific items within a list.
• Async Iteration: Using for await loops to perform assertions across every item in a collection.

Specialized Property Assertions

The framework includes specialized support for "props," which are mapped to data attributes (often used in React or Vue components). This is handled via the waitProp and waitPropAbsence methods.

• Internal Mapping: The prop(name) helper typically maps a prop name like active to a selector-friendly attribute like [data-active].
• Usage Caution: Documentation recommends using these sparingly and preferring user-visible assertions (like text or roles) whenever possible.

Sources: src/page-objects/PageObject.ts:156-175, src/tests/page-objects/PageObject.spec.ts:220-238

Conclusion

Assertions and Wait Helpers in this framework bridge the gap between low-level Playwright locators and high-level test intent. By centralizing validation logic within the PageObject class, the framework ensures that tests remain readable and maintainable, while still allowing full access to the underlying Playwright engine via the $ accessor and the expect() bridge.