What the Page Object Model actually is
The Page Object Model (POM) is a design pattern where each page or component in your application is represented as a class. That class encapsulates the selectors, interactions, and assertions for that page. Tests then call methods on these classes rather than writing raw Playwright actions inline.
The intent is to centralise selector definitions so that when the UI changes, you update one class and all tests that use it stay current. It is a response to a real and painful problem: test suites that break across dozens of files every time a developer renames a button or restructures a form.
- Centralised selectors reduce the blast radius of UI changes
- Readable method names (page.login(), page.addToCart()) describe intent rather than implementation
- Shared setup logic lives in one place rather than duplicated across test files
- IDEs can provide autocomplete and navigation across test files
Where POM adds complexity without adding value
The pattern works well on stable, well-structured applications with experienced engineers who maintain both the app and the test suite. It struggles when those conditions do not hold.
Page Object classes grow over time. A checkout page class might accumulate 40 methods covering every possible state variation. New team members have to learn the class API before they can write a test. PMs and QA staff who want to contribute scenarios cannot read the class-based tests without JavaScript context.
There is also an abstraction mismatch: POM encourages thinking about pages as objects, but your actual users think about workflows and tasks. A test that calls cart.addItem(), checkout.fillShipping(), checkout.submitOrder() is still describing implementation, just at one level of indirection.
- Deep class hierarchies are hard to navigate and easy to break
- High onboarding cost — contributors must learn the class API to write tests
- Over-abstraction can obscure what a test is actually doing
- Does not eliminate selector brittleness — it just centralises it
The alternative: scenario-first authoring
Assert takes a different approach. Instead of encoding page structure into classes, you describe what a user should be able to do in plain-English Markdown. Assert generates the Playwright execution from that description. The scenario stays readable by the whole team. The generated code handles the selector logic.
This does not mean POM is wrong — on large codebases with dedicated automation engineers, it remains a solid pattern. But for most product teams, the overhead of maintaining page classes is not worth the organisational benefit. Assert removes that trade-off entirely.
## Checkout with saved card - User is logged in with a saved payment method - User has at least one item in their cart - Navigate to /cart - Click "Proceed to Checkout" - Confirm the saved card is displayed - Click "Place Order" - Assert the confirmation page shows an order number
FAQ
Should I use Page Object Model with Playwright?
It depends on team size and velocity. POM is valuable when you have many tests maintained by dedicated automation engineers. For smaller teams or teams that want non-engineers to contribute test scenarios, the overhead often outweighs the benefit. Assert's Markdown-first model is designed for teams who want readable, maintainable tests without class-based abstractions.
Does Playwright recommend the Page Object Model?
Playwright's documentation includes a POM guide and their own Page Object pattern implementation. However, they also recommend using built-in locators (getByRole, getByLabel) and keeping tests simple. POM is a suggested pattern, not a requirement.
What is the alternative to POM in Playwright?
Common alternatives include using Playwright's built-in locators and fixtures directly, using a fixtures-based composition model, or using a Markdown-first authoring tool like Assert that generates the test code from human-readable scenarios.
Put the workflow in your repo, not in a chat transcript
Assert is strongest when scenarios become durable project assets: readable Markdown in the repo, generated execution underneath, and result inspection in the dashboard.