Built-in RootPageObject Class
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The RootPageObject class serves as the foundational base class for top-level Page Object Model (POM) structures within the playwright-page-object framework. It is specifically designed for root-decorated classes that are instantiated directly using a Playwright Page instance. By extending this class, developers can establish a typed, decorator-driven entry point for their test automation suites, facilitating the creation of complex control graphs.
Within the project's architecture, RootPageObject acts as the bridge between the raw Playwright Page and the framework's internal locator composition layer. It enforces a strict contract where the primary constructor argument must be a Page object, ensuring that the root context is correctly bound to the browser's current state.
Sources: src/page-objects/RootPageObject.ts:16-21, README.md:126-130, skills/playwright-page-object/SKILL.md:103-107
Architecture and Inheritance
RootPageObject extends the base PageObject class but modifies its behavior to strictly handle top-level page contexts rather than nested components.
Hierarchy and Constraints
While a standard PageObject is intended for nested components and supports cloning with context, RootPageObject explicitly prevents nesting. Attempting to use RootPageObject as a nested child (via cloneWithContext) will result in a runtime error, enforcing the architectural rule that RootPageObject should only exist at the top of the hierarchy.
The diagram above illustrates the inheritance relationship where RootPageObject specializes PageObject for top-level usage.
Sources: src/page-objects/RootPageObject.ts:22-42, src/page-objects/PageObject.ts:39-44
Core Functionality
Constructor Requirements
The RootPageObject constructor is designed to receive a Playwright Page as its first argument. This is critical for the framework's dependency injection and fixture system.
| Parameter | Type | Description |
|---|---|---|
page | Page | The Playwright Page instance to bind the root object to. |
...rest | unknown[] | Optional additional arguments supported by custom constructors. |
Sources: src/page-objects/RootPageObject.ts:8-12, src/tests/decorators/rootSelectors.spec.ts:51-54
Interaction with Root Decorators
The RootPageObject is almost always used in conjunction with @RootSelector decorators. These decorators modify the class to establish the base locator context (often page.locator("body") if no ID is provided) from which all child selectors within the class resolve.
The flow shows how the RootPageObject initialization combines with decorators to set the search context for the entire class.
Sources: src/tests/decorators/rootSelectors.spec.ts:36-41, README.md:132-140
Usage with Fixtures
RootPageObject classes are compatible with the createFixtures() utility. This allows for seamless integration into Playwright's test runner, where the page objects are automatically instantiated and injected into tests.
@RootSelector("CheckoutPage")
class CheckoutPage extends RootPageObject {
@Selector("PromoCodeInput")
accessor PromoCode = new PageObject();
}
// Fixture setup
export const test = base.extend(
createFixtures({ checkoutPage: CheckoutPage })
);
Sources: README.md:154-167, skills/playwright-page-object/SKILL.md:113-125
Key Methods and Properties
| Method/Property | Type | Description |
|---|---|---|
page | Page | The active Playwright Page instance. |
isRootClass(value) | static | Type guard to check if a class constructor is a RootPageObject subclass. |
cloneWithContext() | override | Throws an error; prevents RootPageObject from being nested. |
$ | Locator | Inherited from PageObject; provides the raw Playwright locator for the root element. |
Sources: src/page-objects/RootPageObject.ts:23-43, src/page-objects/PageObject.ts:84-86
Comparison: RootPageObject vs. Plain Classes
While the framework allows the use of plain classes as roots, RootPageObject is recommended when the developer wants a "batteries-included" experience.
| Feature | Plain Decorated Class | RootPageObject |
|---|---|---|
| Base Inheritance | None required | Extends RootPageObject |
| Built-in Waits | Manual implementation | Inherited (waitVisible, etc.) |
| Assertion API | Manual (expect(this.page...)) | Built-in (this.expect()) |
| Constructor | (page: Page, ...rest) | (page: Page, ...rest) |
Sources: skills/playwright-page-object/SKILL.md:52-70, README.md:132-152
Summary
The RootPageObject class is a specialized component of the playwright-page-object library that defines the entry point for a structured Page Object hierarchy. It enforces a page-first constructor contract and integrates deeply with root decorators to establish a stable locator context. By inheriting from RootPageObject, developers gain immediate access to built-in wait helpers and Playwright assertions, while maintaining a strict architectural boundary that prevents root classes from being incorrectly nested within other components.
Sources: src/page-objects/RootPageObject.ts:16-21, README.md:132-140