Page Object, Page Component, Screenplay, and Test Abstraction Patterns: Core Concepts and Mental Model

1. The practical problem: duplication becomes operational debt

Chapters 1–12 built reliable browser mechanics: sessions, locators, waits, contexts, actions, dialogs, modern DOMs, files/state, and browser configuration. A suite can use all of those correctly and still become fragile if every test repeats selectors, waits, navigation rules, screenshots, and business workflows.

The abstraction problem is therefore not “how do I hide Selenium?” It is “which code should know about which kind of change?” A renamed locator should not force fifty scenario edits. A new browser option should not require changing every page object. A failed business assertion should still tell the test author what outcome was wrong.

2. Mental model: intent flows down; evidence flows back up

flowchart TD
  T[Test scenario intent] --> K[Task / domain action]
  T --> Q[Assertion / question]
  K --> P[Page Object service]
  P --> C[Page Component]
  P --> L[Locator + wait policy]
  C --> L
  L --> W[WebDriver]
  W --> B[Browser context]
  B --> A[AUT DOM / application state]
  A --> Q
  Q --> T
  I[Test infrastructure] --> W
  I --> E[Evidence / teardown]
  E --> T

The scenario names the behavior that matters. A task or domain action may coordinate several page services. A Page Object represents services offered by one page or view. Page Components model reusable regions contained by a page. Locators and explicit waits are mechanics inside those boundaries. WebDriver still owns the browser session; infrastructure owns driver creation, evidence directories, and teardown.

Assertions and “questions” flow in the other direction: the abstraction exposes observable state and the test decides whether that state satisfies the scenario.

3. Terms and boundaries

The following table organizes the key choices and evidence for Terms and boundaries. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

4. Page Objects model services, not HTML trivia

Selenium’s current Page Object guidance treats the object as the test-facing interface to a page. Public methods should describe what the page offers: filter_products("Cable"), product_named("Fiber Cable"), or cart_count(). The object may know locators and wait conditions, because those are implementation details the scenario should not repeat.

class CatalogPage:
    FILTER = (By.CSS_SELECTOR, "[data-testid='filter']")
    CART_COUNT = (By.ID, "cart-count")

    def filter_products(self, text: str) -> None:
        field = self._driver.find_element(*self.FILTER)
        field.clear()
        field.send_keys(text)

    def cart_count(self) -> int:
        return int(self.driver.find_element(*self.CART_COUNT).text)

The methods are not “clickFilterField” and “readStrongTag.” They expose application-oriented services/state while keeping DOM details private.

5. Assertion placement: preserve failure meaning

The Selenium project’s Page Object guidance generally keeps test assertions in the test, with a narrow exception for validating that a newly constructed page object is actually on the page it claims to represent. This keeps “what outcome should be true?” close to the scenario while allowing the page object to throw a clear contract error if its basic page precondition is absent.

6. Page Components use composition

Real pages are composed of regions. A catalog contains product cards; a dashboard contains widgets; a table contains rows. The page can return component objects scoped to those regions. This keeps a product card’s name/price/add-button locators out of the page class and avoids an inheritance tree that tries to mirror DOM nesting.

class ProductCard:
    NAME = (By.CSS_SELECTOR, "[data-testid='product-name']")
    PRICE = (By.CSS_SELECTOR, "[data-testid='product-price']")
    ADD = (By.CSS_SELECTOR, "[data-testid='add']")

    def __init__(self, root):
        self.root = root

    def name(self) -> str:
        return self.root.find_element(*self.NAME).text

    def price_text(self) -> str:
        return self.root.find_element(*self.PRICE).text

    def add(self) -> None:
        self.root.find_element(*self.ADD).click()

A component root is still a WebElement reference and can become stale after rerender. The page should reacquire components when the DOM changes rather than caching them for the life of the session.

7. Task-oriented and Screenplay-style layers

A task layer becomes useful when the same business action spans page/component services or must read like domain language. A Screenplay-style design names an actor, the actor’s browser ability, tasks the actor performs, and questions the actor asks. This chapter uses a small framework-free sketch so learners can understand the architecture without adding a dependency.

class AddProductToCart:
    def __init__(self, product_name: str):
        self.product_name = product_name

    def perform(self, catalog: "CatalogPage") -> None:
        catalog.product_named(self.product_name).add()

class CartCount:
    def answered_by(self, catalog: "CatalogPage") -> int:
        return catalog.cart_count()

The key distinction is responsibility, not naming. The task coordinates intent; the page/component owns UI mechanics; the test owns the expectation.

8. Read-only state inspection before mutation

The following example makes the Read-only state inspection before mutation behavior concrete. Read it with the stated assumptions, then compare its observable output or state changes with the explanation that follows.

import selenium
from selenium import webdriver
from selenium.webdriver.common.by import By

URL = "http://127.0.0.1:8782/"
driver = webdriver.Chrome()
try:
    driver.get(URL)
    print({
        "selenium": selenium.__version__,
        "session_id": driver.session_id,
        "browser": driver.capabilities.get("browserName"),
        "browser_version": driver.capabilities.get("browserVersion"),
        "url": driver.current_url,
        "title": driver.title,
        "products": len(driver.find_elements(By.CSS_SELECTOR, "[data-testid='product-card']")),
        "cart": driver.find_element(By.ID, "cart-count").text,
    })
finally:
    driver.quit()

This inspection proves which session/page/DOM state exists before any abstraction changes it. The page object does not create the browser; it receives a session whose provenance and teardown remain infrastructure concerns.

9. Keep state stores distinct

The following table organizes the key choices and evidence for Keep state stores distinct. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

10. Common misconceptions

The following table organizes the key choices and evidence for Common misconceptions. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

11. Why this matters in DevOps

Cross-browser CI magnifies maintenance cost: every browser/version/environment can expose slightly different timing and layout behavior. Centralized locator/wait contracts reduce duplicated fixes, while visible test assertions and infrastructure evidence keep diagnosis explainable. Good abstractions also make code review meaningful: a browser-policy change belongs in infrastructure, a locator change in a page/component, and a business expectation change in the scenario.

12. Summary and next step

Page Objects localize page services and mechanics; Page Components localize reusable regions; task/DSL layers express domain actions; Screenplay-style actor/task/question structure is optional; assertions normally remain in tests; browser/test infrastructure remains outside page classes.

Knowledge check

Official references and version notes

• Selenium 4.47 release notes — stable binding/Grid baseline pinned for this chapter.
• Selenium downloads — current stable client and Server/Grid releases.
• Page Object Models — page services, assertion placement, page component composition, and encapsulation guidance.
• Design patterns and development strategies — page/object and command-oriented alternatives for maintainable suites.
• Domain-specific language — express test intent in user/domain terms rather than UI mechanics.
• Avoid sharing state — isolate test data and create a new WebDriver instance per test where practical.
• Fresh browser per test — clean browser/session state guidance.
• Generating application state — repetitive setup should normally use lower-layer APIs rather than browser UI.