Principle:SeleniumHQ Selenium Page Object Interaction Methods
| Knowledge Sources | |
|---|---|
| Domains | Test_Design, Design_Patterns, Browser_Automation |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Design principle for encapsulating WebElement interactions within Page Object methods that expose domain-specific operations rather than raw browser commands.
Description
Page Object Interaction Methods are the public API of a Page Object class. They encapsulate raw WebElement operations (click(), sendKeys(), getText(), getAttribute(), clear(), submit(), isDisplayed(), isEnabled(), isSelected()) behind domain-meaningful method names (login, search, addToCart). This abstraction means that if the UI changes (e.g., a button ID changes or an input becomes a dropdown), only the Page Object's annotations and internal methods need updating -- test methods remain unchanged.
The WebElement interface (extending SearchContext and TakesScreenshot) provides the foundational interaction methods. All method calls on WebElement perform a freshness check to ensure the element reference is still valid; if the element is no longer attached to the DOM, a StaleElementReferenceException is thrown. Thread safety for parallel test execution can be enforced using ThreadGuard.protect(), which creates a JDK dynamic proxy around the WebDriver that validates all method calls originate from the creating thread.
Usage
Implement public methods on Page Objects that represent user actions. Methods should be named after user behaviors, not UI elements. Return the Page Object itself (for actions on the same page) or another Page Object (for navigation actions) to enable fluent chaining. Keep assertions out of Page Objects -- return data values and let the test class perform assertions.
Theoretical Basis
# Page Object Method Design Principles
1. Name methods after user actions, not UI elements:
GOOD: login(user, pass)
BAD: enterUsernameAndClickLogin(user, pass)
2. Return Page Objects for navigation flow:
LoginPage.login() -> DashboardPage
SearchPage.search(query) -> ResultsPage
CartPage.checkout() -> CheckoutPage
3. Encapsulate waits within methods:
public SearchResult getFirstResult() {
wait.until(visibilityOf(results.get(0)));
return new SearchResult(results.get(0));
}
4. Keep assertions out of Page Objects:
GOOD: String getWelcomeMessage() // return data for test to assert
BAD: void assertWelcomeMessage(String expected) // don't assert in PO
5. Encapsulate complex interactions:
GOOD: public void selectDate(LocalDate date) {
datePicker.click();
monthSelector.selectByVisibleText(date.getMonth().toString());
dayButtons.stream()
.filter(d -> d.getText().equals(String.valueOf(date.getDayOfMonth())))
.findFirst().ifPresent(WebElement::click);
}
The WebElement interface provides these core interaction methods:
Action Methods:
click() - Click the element
submit() - Submit the enclosing form
sendKeys(CharSequence... keys) - Simulate typing
clear() - Reset form field value
Query Methods:
getText() - Get visible text (not hidden by CSS)
getAttribute(String name) - Get attribute/property value (may return null)
getDomAttribute(String name) - Get DOM attribute only (not property)
getDomProperty(String name) - Get DOM property only (not attribute)
getTagName() - Get HTML tag name
getCssValue(String property) - Get computed CSS value
getAriaRole() - Get WAI-ARIA role
getAccessibleName() - Get accessible name
State Methods:
isDisplayed() - Whether element is visible
isEnabled() - Whether element is interactable
isSelected() - Whether checkbox/radio/option is selected
Geometry Methods:
getLocation() - Top-left corner Point
getSize() - Width and height Dimension
getRect() - Combined location and size Rectangle