Playwright Page Objects

Modern POM architecture using Playwright's fixtures pattern, composition over inheritance, and role-based locators.

When to Apply

• Setting up E2E test architecture from scratch
• Creating new page objects or component helpers
• Implementing test fixtures for dependency injection
• Refactoring existing page objects for maintainability
• Writing reusable component-level test abstractions

Core Principles

1. Fixtures over PageManager — On-demand instantiation, automatic setup/teardown, native TypeScript inference
2. Composition over inheritance — Compose from focused components, avoid deep class hierarchies
3. Role-based selectors first — getByRole() > getByLabel() > getByText() > getByTestId()
4. Tests own assertions — Page objects expose state via getters, tests make assertions
5. Separate pages by workflow — ProductListPage ≠ ProductDetailsPage (different user interactions)
6. Readonly locators — All page object locator properties should be readonly
7. Fluent interfaces — Methods return this for chaining; navigation methods return target page object
8. Private internals — Mark implementation details (spinners, retry logic, helpers) as private
9. Wait for stability — Use waitForPageLoad(), waitForResponse() before assertions
10. High-level actions — Create AppActions class for complex multi-page user flows

Quick Reference

Locator Priority

1. page.getByRole('button', { name: 'Add to Cart' })  // Preferred
2. page.getByLabel('Email')                           // Form inputs
3. page.getByText('Welcome back')                     // Non-interactive
4. page.getByPlaceholder('Search...')                 // When no label
5. page.getByTestId('cart-item-count')                // Escape hatch

Anti-Patterns Summary

References

• Fixtures Pattern — Setup and dependency injection
• Core Patterns — Basic POM, composition, locators, waiting, high-level actions
• Form Handling — Multi-step flows, validation components
• Anti-Patterns — What to avoid