object-model-patterns

Overview

This skill is a pure reference - no execution steps; it is the canonical catalog cited to determine "what good looks like" per pattern. The catalog complements test-code-conventions (which is file-level §1-§10) with the architecture-tier vocabulary.

When to use

• Designing a new test automation framework - pick one canonical pattern; do not mix.
• Reviewing an existing framework's architecture - audit which pattern is in use and whether it is applied consistently.
• Migrating from one pattern to another (the most common migration: classic POM → Screenplay or POM → App Actions).
• Onboarding new engineers - point them at the canonical citation for the pattern the team uses.

Do not use this skill to:

• Author per-framework tool configuration - that's the per-framework skill (playwright-testing, cypress-testing, etc.).
• Pick the framework itself - that's framework-choice-advisor.
• Audit a running codebase against the chosen pattern - that's a separate framework-architecture audit (this catalog is the reference it cites).

Each pattern below states what it is: its definition, canonical citation, and load-bearing rules. Use the pattern selection matrix to choose one; the detailed per-pattern when-to-use rules and anti-pattern tables live in references/pattern-catalog.md.

Pattern 1 - Page Object Model (POM)

Canonical source: Martin Fowler's PageObject definition (the bliki article is the cross-language canonical reference) + Selenium HQ documentation on Page Object Models.

Fowler's definition: "A page object wraps an HTML page, or fragment, with an application-specific API, allowing you to manipulate page elements without digging around in the HTML."

Selenium HQ's elaboration: "A page object is an object-oriented class that serves as an interface to a page of your AUT… There is a clean separation between the test code and page-specific code, such as locators."

The three load-bearing rules:

1. No assertions in the POM body. Fowler: "Page objects are most commonly used in testing, but should not make assertions themselves." Selenium HQ: "Page objects themselves should never make verifications or assertions. This is part of your test and should always be within the test's code, never in a page object." One narrow exception (Selenium HQ): a verification at instantiation that the page loaded.
2. Navigation methods return the next POM. Fowler: "If you navigate to another page, the initial page object should return another page object for the new page." This enables compile-time detection of broken workflows.
3. POM exposes the page's services, not its widgets. Methods are named after the user-meaningful action (addToCart, submitOrder), not the DOM mechanic (clickButton, typeIntoField).

Pattern 2 - Screenplay

Canonical source: Antony Marcano, Andy Palmer, and Jan Molak - Serenity BDD documentation on Screenplay; origin article Marcano, Palmer, Molak and Smart, "Page Objects Refactored: SOLID Steps to the Screenplay/Journey Pattern," which traces the approach to Marcano's 2007 conception.

The Screenplay vocabulary (Serenity BDD docs):

Why Screenplay vs POM: Screenplay separates what the user does (Tasks, Interactions) from what the user can do (Abilities) from what the user observes (Questions). The result is a SOLID-aligned object model that survives UI refactors better than POM in large suites.

Pattern 3 - Component Object

Canonical source: Selenium HQ docs (Page Components are part of the official POM extension) + practitioner consensus (testing-library, Storybook, Playwright Component Testing). Treated as a refinement of POM, not a competing pattern.

Definition: A Component Object is a Page Object scoped to a UI component (header, nav, form, modal, card) rather than a whole page. Where a page contains a re-used component (the navbar appears on every page), the Component Object models that component once; each Page Object that contains it composes it in.

Pattern 4 - App Actions (Cypress idiom)

Canonical source: Gleb Bahmutov - "Application Actions: Use Them Instead of Page Objects" (Cypress blog, 2019).

Definition: App Actions bypass the UI for setup steps by exposing application functions (Redux dispatches, store mutations, API calls) directly via cy.window().its('app') or equivalent. The test still asserts via the UI; only the Arrange phase is short-circuited.

Why App Actions vs POM: "Logging in" is not what the test is about - it's overhead. App Actions skip the login UI flow and inject a session directly, making the test 10× faster and removing flake from the login form.

Pattern 5 - Service Object

Canonical source: Ruby on Rails / Java enterprise testing patterns + practitioner blog consensus. Refinement of POM for non-UI test layers.

Definition: A Service Object is the API-test equivalent of a Page Object - it wraps a remote service (REST endpoint, GraphQL query, gRPC method, message-queue producer) with a domain API the test consumes. Methods like cartService.addItem(sku, qty) rather than httpClient.post('/api/cart/items', { sku, qty }).

Pattern 6 - Repository (test-data access)

Canonical source: Martin Fowler's Repository pattern (originally for domain-driven design) adapted for test-data setup. Practitioner adoption in 2020+ test frameworks (factory libraries layer on top).

Definition: A Repository in test context is the data-access abstraction that hides the storage mechanism (DB, fixture file, factory call) behind a domain API: userRepo.createTestUser({ role: 'admin' }).

Pattern 7 - Screen Object (desktop / mobile sibling of Page Object)

Canonical source: Martin Fowler's PageObject article - the current bliki entry defines it as an object that "wraps an HTML page, or fragment, with an application-specific API". The earlier name WindowDriver (Fowler, 2004) covered desktop GUI windows under the same encapsulation principle before the term migrated to web. The desktop / mobile community reuses the structurally-identical pattern under the name Screen Object (one class per logical screen, locators + actions encapsulated, no assertions inside). No single owner formally documents the rename - screen object is community-canonical across FlaUI, XCUITest, Appium / Espresso practitioner literature.

The mobile sibling is documented inside Google's Android testing guidance as Screen Robot (Jake Wharton - Instrumentation Testing Robots (2016)) and inside Square's mobile literature as well; both reproduce the same encapsulation contract.

The three load-bearing rules transfer unchanged from POM:

1. No assertions in the Screen Object body. Same rationale Fowler gives for POM ("page objects … should not make assertions themselves"). The desktop test asserts on window.Title, element.IsEnabled, control-pattern state; the Screen Object exposes those via getters but does not verify them.
2. Navigation methods return the next Screen Object. login.SubmitsCredentials() returns MainScreen. Compile-time detection of broken workflows survives the migration from web POM to desktop Screen Object.
3. Screen Object exposes the screen's services, not its widgets. login.SubmitsCredentials(creds) not login.LoginButton.Click(). Methods are named after the user-meaningful action - same vocabulary rule as POM.

Worked desktop example (FlaUI / xUnit)

Bad (mechanical leakage into the test body - same shape as the web POM anti-pattern):

[StaFact]
public void Logs_in_with_valid_credentials() {
    var window = _fx.App.GetMainWindow(_fx.Automation);
    window.FindFirstDescendant(cf => cf.ByAutomationId("Username")).AsTextBox().Enter("alice@example.com");
    window.FindFirstDescendant(cf => cf.ByAutomationId("Password")).AsTextBox().Enter("hunter2");
    window.FindFirstDescendant(cf => cf.ByAutomationId("LoginButton")).AsButton().Invoke();
    Assert.Equal("Invoices", _fx.App.GetMainWindow(_fx.Automation).Title);
}

Good (Screen Object at the business layer):

[StaFact]
public void Logs_in_with_valid_credentials() {
    var login = new LoginScreen(_fx.App.GetMainWindow(_fx.Automation));
    var main  = login.SubmitsCredentials("alice@example.com", "hunter2");
    Assert.Equal("Invoices", main.Title);
}

The mechanics live inside LoginScreen (constants for AutomationIds, retry-wrapped element fetches, SubmitsCredentials returns the next Screen Object). The test reads as a specification.

Pattern selection matrix

The patterns are not equally good for every project. The matrix:

Cross-cutting anti-patterns (apply to any pattern)

Hand-off targets

• Pick the framework itself before applying these patterns → framework-choice-advisor (in the qa-process plugin).
• Test-data construction patterns (Builder / Factory / Fixture) → test-data-patterns (in the qa-test-data plugin, sister catalog).
• Test isolation / fixture lifecycle / parallel safety → test-isolation-patterns (sister catalog).
• Test step granularity and abstraction → test-step-design-patterns (sister catalog).
• Cross-file convention reference → test-code-conventions (file-level companion).

References

Canonical sources, each cited inline above at the rule it grounds:

• Fowler, PageObject: https://martinfowler.com/bliki/PageObject.html
• Selenium HQ, Page Object Models: https://www.selenium.dev/documentation/test_practices/encouraged/page_object_models/
• Marcano, Palmer, Molak, Screenplay Fundamentals (Serenity BDD): https://serenity-bdd.github.io/docs/screenplay/screenplay_fundamentals
• Marcano, Palmer, Molak, Smart, Page Objects Refactored: SOLID Steps to the Screenplay/Journey Pattern: https://dzone.com/articles/page-objects-refactored-solid-steps-to-the-screenp
• Cypress team, Stop using Page Objects and Start using App Actions: https://www.cypress.io/blog/stop-using-page-objects-and-start-using-app-actions/
• Fowler, Repository pattern: https://martinfowler.com/eaaCatalog/repository.html
• Jake Wharton, Instrumentation Testing Robots (2016): https://jakewharton.com/testing-robots/
• Apple, Testing with Xcode - UI Testing chapter: https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/testing_with_xcode/chapters/09-ui_testing.html
• ISTQB glossary, Service Virtualisation: https://glossary.istqb.org/en_US/term/service-virtualization
• desktop-test-strategy-reference (qa-desktop), test-code-conventions - sibling catalogs.