Principle:SeleniumHQ Selenium Page Object Test Design
| Knowledge Sources | |
|---|---|
| Domains | Test_Design, Design_Patterns, Quality_Assurance |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Design pattern for structuring browser-based tests using Page Object classes that separate test logic from page interaction details.
Description
The Page Object Test Design pattern structures tests into two layers: Page Objects (representing web pages with locators and interaction methods) and Test Classes (containing test scenarios with assertions). Tests interact with Page Objects through their public API rather than directly with WebElements or the WebDriver. This separation ensures that UI changes only require Page Object updates, while test logic remains stable.
Page Objects combine three Selenium support mechanisms: (1) @FindBy annotations to declare element locators declaratively, (2) PageFactory.initElements() to convert those annotations into lazy-loading element proxies at runtime, and (3) optional @CacheLookup to optimize frequently accessed static elements. AbstractFindByBuilder validates annotation correctness at initialization time, catching locator configuration errors early -- for example, specifying more than one location strategy in a single @FindBy triggers an IllegalArgumentException before any test code runs.
The PageFactory class-based overload (initElements(SearchContext, Class<T>)) attempts to instantiate the Page Object using a constructor that takes WebDriver, falling back to a no-arg constructor. This allows Page Objects to receive the driver reference automatically.
Usage
Apply this pattern for any browser-based test suite with more than a few tests. Each distinct page or significant page section gets its own Page Object class. Tests compose Page Object method calls to express user journeys. Follow these conventions: Page Objects handle browser interactions and waits; test classes handle assertions and test data; Page Object methods return other Page Objects to model navigation flow.
Theoretical Basis
# Page Object Test Design Structure
Test Layer (assertions, data, flow):
@Test void shouldLoginSuccessfully() {
LoginPage loginPage = new LoginPage(driver);
DashboardPage dashboard = loginPage.login("user", "pass");
assertEquals("Welcome", dashboard.getGreeting());
}
Page Object Layer (locators, interactions):
class LoginPage {
@FindBy(id = "user") WebElement userField;
@FindBy(id = "pass") WebElement passField;
public DashboardPage login(user, pass) { ... }
}
# Separation of Concerns
- Locator changes -> only Page Object annotations change
- Interaction changes -> only Page Object methods change
- Business logic changes -> only test methods change
- New test scenarios -> reuse existing Page Objects
Key benefits of the separation:
| Concern | Responsibility | Location |
|---|---|---|
| Element locators | @FindBy annotations | Page Object fields |
| Element proxying | PageFactory.initElements() | Page Object constructor |
| Browser interactions | WebElement methods | Page Object methods |
| Navigation modeling | Return type of Page Object methods | Page Object method signatures |
| Test data | Test parameters and fixtures | Test class |
| Assertions | JUnit/TestNG assertions | Test class methods |
| Setup/teardown | WebDriver lifecycle | Test class @BeforeEach/@AfterEach |
# Annotation Validation (AbstractFindByBuilder.assertValidFindBy)
- Ensures at most one location strategy per @FindBy
- Checks: if 'how' is set, 'using' must also be set
- Counts non-empty finder attributes (id, name, css, xpath, etc.)
- If count > 1: throws IllegalArgumentException with details
- If count = 0: defaults to lookup by field name as id or name