Selenium Page Object Model Guide
PDF Downloads

What is the Page Object Model?

The Page Object Model, or POM, is a design pattern for UI test automation. Each page of the application, or each significant component such as a header or a modal, gets a class. The class stores the locators of the elements on that page and exposes methods that describe what a user can do there, such as login or searchFor. Tests then call these methods and contain assertions and flow, but no locators. The result is that when the interface changes, you update one page class instead of dozens of tests, and tests read like descriptions of user behaviour. Without POM, locators are copied through many tests and maintenance becomes the main cost of automation.

Without POM versus with POM

Typical project layers

A base page with an explicit wait helper

A small shared parent class for page objects. Illustrative Java using Selenium 4.

import java.time.Duration;
import org.openqa.selenium.*;
import org.openqa.selenium.support.ui.*;

public abstract class BasePage {
    protected final WebDriver driver;
    private final WebDriverWait wait;

    protected BasePage(WebDriver driver) {
        this.driver = driver;
        this.wait = new WebDriverWait(driver, Duration.ofSeconds(10));
    }

    protected WebElement visible(By locator) {
        return wait.until(ExpectedConditions.visibilityOfElementLocated(locator));
    }

    protected void type(By locator, String text) {
        WebElement el = visible(locator);
        el.clear();
        el.sendKeys(text);
    }

    protected void click(By locator) {
        wait.until(ExpectedConditions.elementToBeClickable(locator)).click();
    }
}

A login page object and a test

The page object hides locators and returns the next page after a successful action.

public class LoginPage extends BasePage {
    private final By email = By.id("email");
    private final By password = By.id("password");
    private final By loginButton = By.id("login");
    private final By error = By.cssSelector(".error-message");

    public LoginPage(WebDriver driver) { super(driver); }

    public LoginPage open(String baseUrl) {
        driver.get(baseUrl + "/login");
        return this;
    }

    public DashboardPage loginAs(String user, String pass) {
        type(email, user);
        type(password, pass);
        click(loginButton);
        return new DashboardPage(driver);
    }
}

PageFactory and its status

Selenium offers PageFactory with the @FindBy annotation to initialise elements declared as fields. It reduces boilerplate and can cache or lazily locate elements. Many teams prefer plain By locators with explicit waits, as in the example above, because they are simple, work well with dynamic pages and are easy to debug. Check the current Selenium documentation for the status of PageFactory in your version before standardising on it, and apply whichever approach your team picks consistently.

Design rules for good page objects

• → Page classes contain locators and actions, not assertions about business rules.
• → Methods return the next page object when navigation happens, or the same page when it does not.
• → Name methods after user intent, such as submitOrder, not clickButton3.
• → Prefer stable locators such as ids, data-test attributes or accessible names over long XPath chains.
• → Use explicit waits in the base class instead of fixed sleeps.
• → Model reusable components, such as a navigation bar, as their own classes.

Locator strategy comparison

Common mistakes

Common component objects

Refactoring existing scripts to POM

1. Pick one flow, such as login, and copy its locators into a new class.
2. Move the actions into methods named by intent.
3. Replace the old script lines with the new calls.
4. Run the test and compare results.
5. Repeat flow by flow rather than rewriting everything at once.

When POM may be more than you need

A throwaway script for one-time use. A very small project with one or two pages. In these cases keep the code simple, and introduce page objects when duplication starts to hurt.