Relevant source files

The following files were used as context for generating this wiki page: - [src/page-objects/PageObject.ts](https://github.com/sergeyshmakov/playwright-page-object/blob/main/src/page-objects/PageObject.ts) - [src/page-objects/ListPageObject.ts](https://github.com/sergeyshmakov/playwright-page-object/blob/main/src/page-objects/ListPageObject.ts) - [src/decorators/selectors.ts](https://github.com/sergeyshmakov/playwright-page-object/blob/main/src/decorators/selectors.ts) - [src/decorators/rootSelectors.ts](https://github.com/sergeyshmakov/playwright-page-object/blob/main/src/decorators/rootSelectors.ts) - [src/fixtures.ts](https://github.com/sergeyshmakov/playwright-page-object/blob/main/src/fixtures.ts) - [README.md](https://github.com/sergeyshmakov/playwright-page-object/blob/main/README.md)

# PageObject Base Class Reference The `PageObject` class serves as the fundamental building block of the `playwright-page-object` framework. It provides a structured, TypeScript-first approach to the Page Object Model (POM), replacing traditional flat locator strings with a composable control graph. By extending this class, developers gain access to built-in wait helpers, native Playwright assertions, and a standardized mechanism for element resolution through decorators. The architecture emphasizes lazy evaluation, where locator chains are dynamically rebuilt only upon access. This ensures that test objects remain resilient to DOM re-renders and provides a clear separation between the identification of UI components (via selectors) and the actions performed upon them (via the Playwright `Locator` API). Sources: [README.md](), [src/page-objects/PageObject.ts:1-35]() ## Core Architecture and Lifecycle The `PageObject` class manages the relationship between a Playwright `Page`, a `root` Locator, and a specific `selector` function. When a child element is accessed, the framework resolves the locator by applying the selector function to the root locator. ### Class Hierarchy and Relationships The following diagram illustrates the relationship between the base `PageObject`, its specialized `ListPageObject` subclass, and the Playwright components they wrap. ```mermaid classDiagram class PageObject { +page: Page +root: Locator +$: Locator +expect(options) +waitVisible() +waitCount(n) +cloneWithContext(root, selector) } class ListPageObject { #itemType: PageObject +items: Proxy +at(index) +getAll() +count() } class PlaywrightPage { <> } class PlaywrightLocator { <> } PageObject <|-- ListPageObject PageObject o-- PlaywrightPage : contains PageObject o-- PlaywrightLocator : root PageObject ..> PlaywrightLocator : produces via $ ``` The `PageObject` constructor accepts an optional `Page` instance, a `root` Locator, and a `SelectorType` function. The `$` getter is the primary entry point for Playwright actions, returning the fully resolved locator. Sources: [src/page-objects/PageObject.ts:37-95](), [src/page-objects/ListPageObject.ts:28-55]() ### Locator Resolution Flow Element resolution is lazy and follows a hierarchical path from the root of the page down to the specific component. ```mermaid flowchart TD A[Access PageObject.$] --> B{Selector defined?} B -- No --> C[Throw Error] B -- Yes --> D{Root defined?} D -- No --> E[Throw Error] D -- Yes --> F[Apply Selector to Root] F --> G[Return Playwright Locator] ``` Sources: [src/page-objects/PageObject.ts:63-95]() ## API Reference ### Built-in Wait Helpers The base class provides several asynchronous methods to synchronize tests with the UI state. These methods wrap Playwright assertions internally. | Method | Description | Source | | :--- | :--- | :--- | | `waitVisible()` | Waits for the element to become visible. | [src/page-objects/PageObject.ts:122-124]() | | `waitHidden()` | Waits for the element to become hidden. | [src/page-objects/PageObject.ts:127-129]() | | `waitText(text)` | Waits for the element to contain specific text. | [src/page-objects/PageObject.ts:135-137]() | | `waitValue(value)` | Waits for the element to have a specific value. | [src/page-objects/PageObject.ts:143-145]() | | `waitCount(count)` | Waits for the locator to resolve to a specific count. | [src/page-objects/PageObject.ts:154-156]() | | `waitChecked()` | Waits for a checkbox or radio to be checked. | [src/page-objects/PageObject.ts:159-161]() | | `waitProp(name, val)` | Waits for a data attribute (prop) to match a value. | [src/page-objects/PageObject.ts:175-179]() | ### Assertions via `expect()` The `expect()` method provides access to the Playwright assertion library, pre-bound to the `PageObject`'s locator. It supports optional configuration for soft assertions and custom error messages. ```typescript // Usage example await header.expect({ soft: true, message: "Header should be visible" }).toBeVisible(); ``` Sources: [src/page-objects/PageObject.ts:194-206]() ## Component Nesting and Context For complex UI structures, `PageObject` instances are nested. This is achieved through the `cloneWithContext` method, which creates a new instance of the class (or subclass) bound to a new root locator and selector. ```mermaid sequenceDiagram participant P as Parent PageObject participant D as Decorator participant C as Child PageObject P->>D: Access @Selector property D->>C: Call cloneWithContext(parentRoot, childSelector) C-->>D: Return new instance bound to context D-->>P: Return contextualized child ``` This mechanism allows selectors to be relative to their parent, enabling high reusability of components like buttons or inputs across different pages. Sources: [src/page-objects/PageObject.ts:111-119](), [README.md "Philosophy"]() ## Integration and Fixtures To use `PageObject` classes in tests, they must be registered as Playwright fixtures using the `createFixtures` utility. This utility handles the instantiation of top-level page objects and injects the Playwright `page` instance into them. ```typescript import { test as base } from "@playwright/test"; import { createFixtures } from "playwright-page-object"; import { CheckoutPage } from "./CheckoutPage"; export const test = base.extend<{ checkoutPage: CheckoutPage }>( createFixtures({ checkoutPage: CheckoutPage }), ); ``` Sources: [src/fixtures.ts:40-60](), [README.md "Step 3"]() The `PageObject` base class ensures type safety and maintainability by centralizing element resolution logic and providing a consistent interface for both simple elements and complex nested components. Summary: The `PageObject` base class is the core of the framework, providing lazy locator resolution, built-in wait/assertion helpers, and a composable structure that mirrors the DOM tree. It integrates with Playwright via the `$` getter and the `createFixtures` helper. Sources: [src/page-objects/PageObject.ts](), [README.md]()