playwright-page-objects

name	playwright-page-objects
description	Use when creating page objects or refactoring Playwright E2E tests for better maintainability with Page Object Model patterns.
allowed-tools	["Bash","Read","Write","Edit"]

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

Pattern	When to Use	Reference
Fixtures	Always for page object instantiation	fixtures-pattern.md
Basic POM	All page objects	core-patterns.md
Composition	Shared UI elements (header, cards, modals)	core-patterns.md
Waiting strategies	Loading states, API responses	core-patterns.md
High-level actions	Multi-page flows (checkout, onboarding)	core-patterns.md
Form handling	Multi-step forms, validation	form-handling.md

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

Anti-Pattern	Problem	Solution
Assertions in POMs	Hidden test logic	Expose state, assert in tests
Fat page objects	50+ locators unmaintainable	Split into components
Deep inheritance	Rigid, hard to modify	Use composition
CSS selectors	Break on styling changes	Use role-based selectors
Wrapping Playwright	Unnecessary abstraction	Use Playwright directly
All members public	Exposes internals	Mark internal members private

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