Page Object, Page Component, Screenplay, and Test Abstraction Patterns: Configuration, Design Patterns, and Trade-Offs

1. Start with the change you want to contain

The right abstraction is the smallest boundary that contains a recurring kind of change. If three tests repeat the same locator and readiness rule, a Page Object may reduce real duplication. If a single experiment has one interaction, a page class may add more code than it removes. If a multi-page business action is repeated across dozens of scenarios, a task/domain layer may keep that workflow out of multiple page classes.

2. Direct test code versus Page Objects

The following table organizes the key choices and evidence for Direct test code versus Page Objects. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

Do not begin by generating a class for every URL. Model meaningful services and reusable mechanics after the behavior is understood.

3. Components versus God page classes

A page with product cards, navigation, filters, dialogs, and tables should not necessarily expose every internal locator from one class. Page Components make ownership smaller. The page composes them; components may themselves compose smaller regions when that maps to stable UI responsibilities.

4. Separate actions from state queries

Action methods mutate browser/AUT state: add(), filter_products(), submit(). Query methods expose observable state: price_text(), cart_count(), error_message(). Keeping this distinction visible makes assertions easier to place and failures easier to explain.

# Page/component layer
page.filter_products("Cable")          # action
names = [p.name() for p in page.products()]  # query

# Test layer
assert names == ["Fiber Cable"]

5. Assertion placement is a diagnostic choice

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

6. Fluent APIs versus explicit steps

A fluent API can make a stable linear workflow readable, but long chains can hide which action changed context or failed. Selenium’s guidance treats fluent style as an option, not a requirement. Prefer a chain only when each returned object/state is unambiguous and failure reporting identifies the exact operation.

# Explicit style: easiest to inspect while learning/diagnosing.
page.filter_products("Cable")
cable = page.product_named("Fiber Cable")
cable.add()

# A fluent style can be acceptable if each method has a clear contract.
# page.filter_products("Cable").add_product("Fiber Cable")

7. Screenplay ceremony versus scalability

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

Screenplay-style structure is not a substitute for solid locators, waits, session isolation, or evidence. It is an organizational layer above those mechanics.

8. Inheritance versus composition

Use inheritance only for genuinely stable, small behavioral contracts. A giant BasePage containing every wait, click, API call, screenshot, browser option, and navigation helper creates invisible coupling. DOM containment is naturally modeled by composition: CatalogPage has ProductCards; it does not inherit from them.

9. Keep configuration layers separate

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

10. Worked design decision

Suppose a catalog suite has 60 tests, five browsers in CI, repeated add-to-cart flows, a shared navigation bar, and a frequently rerendered product grid. A reasonable design is:

1. CatalogPage owns filter/grid locators and returns fresh ProductCard components.
2. ProductCard owns card-local name/price/add mechanics.
3. NavigationBar is a reusable component shared by pages.
4. AddProductToCart becomes a task because the workflow is reused.
5. Scenario assertions remain in tests.
6. Driver factory owns browser matrix/options; test hooks own screenshots and capabilities evidence.
7. Adopt an actor/task/question vocabulary only if multiple user roles and many shared domain tasks justify it.

11. Maintainability, portability, performance, and security trade-offs

The following table organizes the key choices and evidence for Maintainability, portability, performance, and security trade-offs. Use it together with the surrounding prose so the rows serve as a comparison aid rather than standalone rules.

12. Summary and next step

Choose abstractions by change ownership and diagnostic clarity, not by pattern prestige. Start with page services and components; introduce tasks when workflows repeat; use Screenplay-style structure when domain scale earns the extra vocabulary. Lesson 4 diagnoses what happens when these boundaries collapse.

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.