Page Objects solved one problem: locators.
They did not solve behavior, readability, or long-term maintenance.
In many Playwright projects, Page Objects slowly turn into dumping grounds. Locators, clicks, assertions, waits, logic, and workarounds all mixed together. It works at the beginning. It always does. Until it doesn’t.
That’s when tests become hard to read, harder to change, and impossible to reason about.
In my project, we separated what the page is from what the user does.
Page Objects define structure
Page Objects contain only:
- the page reference
- locators
- logical grouping (filters, buttons, textFields)
Nothing else.
They don’t click.
They don’t assert.
They don’t make decisions.
They describe the UI as it exists.
This keeps them stable even when behavior changes.
Page Actions define behavior
Page Actions are where intent lives.
They:
- perform user flows
- contain waits and retries
- apply assertions using shared guidelines
- express actions in business language, not DOM language
Instead of reading locator.click() everywhere, tests read like:
applyFilters()openArticle()expectArticleTextToBeVisible()
That difference matters. A lot.
Why this separation scales
When Playwright tests grow, three things break first:
- duplication
- unclear ownership
- fear of refactoring
Page Actions fix all three.
If a flow changes, there’s one place to update it.
If timing changes, logic lives in actions, not scattered tests.
If assertions evolve, they’re centralized and consistent.
This also makes code reviews faster. You review intent, not implementation noise.
How this works in practice
In my project:
*Object.tsholds locators only*Page.tsor*PageActions.tsholds behavior- tests stay thin and expressive
- assertion rules are enforced centrally
No any. No magic waits. No random helpers hiding logic.
Just boring, predictable structure.
The real benefit
This isn’t about architecture purity.
It’s about trust.
When a test fails, I know:
- where to look
- who owns the logic
- whether it’s app behavior, environment, or test design
That’s what senior test design looks like in practice.
Page Objects tell you where.
Page Actions tell you why.
And in long-lived Playwright projects, why is what keeps things alive.