Example App Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Example App is a minimal React-based checkout application designed to demonstrate the integration and capabilities of the playwright-page-object library. Its primary purpose is to showcase how decorator-driven selector composition can be used to build a maintainable, typed, and composable End-to-End (E2E) testing suite.
The architecture follows a modular approach where the frontend application (built with React and Vite) is decoupled from the testing infrastructure. The testing layer utilizes a "Control Graph" pattern, where Page Objects compose into a hierarchical structure that mirrors the application's DOM, allowing for repeatable logic and encapsulated component interactions.
Sources: example/README.md:3-5, example/package.json:15-20, example/README.md:21-25
Component Hierarchy and Control Graph
The application architecture is represented in the testing layer through a typed graph of controls. Each node in the graph represents a UI component or a logical grouping of elements, established via decorators that resolve selectors relative to their parent container.
Visual Representation of the Control Graph
The following diagram illustrates how the CheckoutPage serves as a root, containing nested selectors and list-based controls for cart items.
The graph demonstrates the relationship between top-level pages and nested repeatable controls.
Sources: example/README.md:25-31, skills/playwright-page-object/SKILL.md:120-130
Testing Infrastructure and Fixtures
The architecture utilizes Playwright fixtures to manage Page Object instantiation. Instead of manual setup in every test, the createFixtures utility is used to inject pre-configured Page Objects directly into the test context.
Fixture Configuration
The example/e2e/fixtures.ts file extends the base Playwright test object to include custom page objects like CheckoutPage and ExternalCheckoutPage. This allows tests to access these objects as destuctured arguments.
export const test = base.extend<{
checkoutPage: CheckoutPage;
externalCheckoutPage: ExternalCheckoutPage;
}>(
createFixtures({
checkoutPage: CheckoutPage,
externalCheckoutPage: ExternalCheckoutPage,
}),
);
Sources: example/e2e/fixtures.ts:1-13, example/README.md:47-52
Automated Test Execution Flow
When a test is executed, the following sequence occurs to initialize the page objects and interact with the React application:
The sequence shows the lazy resolution of locators and the interaction flow between tests and the browser.
Sources: example/e2e/checkout.spec.ts:7-14, README.md:200-210
Key Implementation Patterns
The architecture demonstrates several advanced patterns for handling dynamic UI elements and collections.
| Pattern | Description | Implementation Detail |
|---|---|---|
| Async Iteration | Iterating over dynamic lists using for await. | for await (const item of checkoutPage.CartItems.items) |
| Filtering | Locating specific items within a collection by text or attributes. | checkoutPage.CartItems.filterByText("Widget") |
| Encapsulation | Hiding complex locator logic behind named methods. | checkoutPage.expectCartEmpty() |
| Variable Reusability | Using the same control class for multiple instances. | ButtonControl used for both Apply and Remove buttons. |
Sources: example/README.md:54-72, example/e2e/checkout.spec.ts:40-45
Development and Build Pipeline
The example app is integrated into the root project's build lifecycle. It requires the parent package to be built and packed before installation to ensure the latest local changes are tested.
Build Commands
The package.json in the example folder defines the following scripts for maintenance and testing:
npm run dev: Starts the Vite development server.npm run build: Compiles the TypeScript code and builds the Vite production assets.npm run test:e2e: Executes the Playwright test suite.preinstall: Automatically triggers a package build in the parent directory vianpm run pack:example.
Sources: example/package.json:7-13, package.json:15-25
Summary
The Example App Architecture serves as a reference implementation for the playwright-page-object library. By leveraging a decorator-driven control graph and automated fixture injection, it provides a structured way to manage complex UI selectors. This architecture ensures that selectors remain relative to their component roots, promoting reusability and reducing the maintenance overhead associated with raw Playwright locator chains.