A test suite usually starts failing for a boring reason: someone changed a button label, moved an input field, or wrapped a form in one more div. If your locators, waits, and page actions are scattered across dozens of test methods, every UI tweak becomes cleanup work. That is exactly why a selenium page object model tutorial matters for real automation teams – it gives your framework structure before maintenance costs get out of hand.
What the Page Object Model solves
The Page Object Model, usually shortened to POM, is a design pattern that separates test intent from UI implementation. Your test should say something like “log in as a valid user” or “add product to cart,” not repeat XPath selectors and click sequences every time.
In practice, a page object represents a screen or meaningful part of a screen. It owns the locators and the interactions for that page. The test class then uses those methods to express behavior. This improves readability, but the bigger win is maintainability. When the login button changes, you fix it in one class instead of searching through the entire suite.
That said, Page Object Model is not magic. If you create page classes with hundreds of methods, mix assertions into the wrong layers, or hide too much logic, the framework gets hard to understand. POM works best when each class has a clear responsibility.
Selenium page object model tutorial: core structure
A practical Selenium framework using POM usually has a few consistent layers. The exact package names vary by language and team preference, but the responsibilities stay similar.
Your page classes contain locators and page-level actions. Your tests describe scenarios and make assertions. Many teams also introduce a base page for shared WebDriver behavior, such as waiting for elements, clicking safely, typing into fields, and reading visible text.
Here is a simple Java example using Selenium WebDriver:
“`java public class LoginPage { private WebDriver driver;
private By username = By.id(“username”); private By password = By.id(“password”); private By loginButton = By.id(“loginBtn”);
public LoginPage(WebDriver driver) { this.driver = driver; }
public void enterUsername(String user) { driver.findElement(username).sendKeys(user); }
public void enterPassword(String pass) { driver.findElement(password).sendKeys(pass); }
public void clickLogin() { driver.findElement(loginButton).click(); }
public void loginAs(String user, String pass) { enterUsername(user); enterPassword(pass); clickLogin(); } } “`
And the test becomes much cleaner:
“`java public class LoginTest { private WebDriver driver;
@Test public void validUserCanLogIn() { driver.get(“https://example.com/login”); LoginPage loginPage = new LoginPage(driver); loginPage.loginAs(“standard_user”, “secret_sauce”);
Assert.assertTrue(driver.getCurrentUrl().contains(“dashboard”)); } } “`
This example is intentionally simple, but it shows the point. The test is about behavior. The page object is about implementation.
Build page objects around user actions, not just elements
A common beginner mistake is creating a page class that only exposes raw elements or one-line wrappers like `clickUsernameField()` and `typeIntoPasswordField()`. That can still reduce duplication, but it does not go far enough.
A stronger page object models the way a user works through the page. For a login page, a `loginAs()` method makes sense. For a checkout page, methods like `enterShippingAddress()`, `selectDeliveryMethod()`, and `placeOrder()` are more useful than exposing every low-level click separately.
There is a trade-off here. If you bundle too much into one method, your tests lose flexibility. If you keep every interaction too small, your tests become noisy again. The right balance depends on how stable the UI is and how much variation your test flows need.
Add a BasePage for repeatable WebDriver actions
Most real projects should not call `driver.findElement()` directly in every page class method. Repeated timing issues are one of the biggest sources of flaky Selenium tests, so shared helper methods are worth centralizing.
A base page often wraps explicit waits and common interactions:
“`java public class BasePage { protected WebDriver driver; protected WebDriverWait wait;
public BasePage(WebDriver driver) { this.driver = driver; this.wait = new WebDriverWait(driver, Duration.ofSeconds(10)); }
protected void click(By locator) { wait.until(ExpectedConditions.elementToBeClickable(locator)).click(); }
protected void type(By locator, String text) { wait.until(ExpectedConditions.visibilityOfElementLocated(locator)).sendKeys(text); }
protected String getText(By locator) { return wait.until(ExpectedConditions.visibilityOfElementLocated(locator)).getText(); } } “`
Then your login page extends it:
“`java public class LoginPage extends BasePage { private By username = By.id(“username”); private By password = By.id(“password”); private By loginButton = By.id(“loginBtn”);
public LoginPage(WebDriver driver) { super(driver); }
public void loginAs(String user, String pass) { type(username, user); type(password, pass); click(loginButton); } } “`
This is usually a better starting point than placing waits directly in test methods. It keeps synchronization logic close to page interactions and reduces duplicated wait code.
When to return another page object
After an action changes the screen, your method can return the next page object. This makes test flow clearer and better reflects navigation.
For example, a successful login might return a `DashboardPage`:
“`java public DashboardPage loginAs(String user, String pass) { type(username, user); type(password, pass); click(loginButton); return new DashboardPage(driver); } “`
That pattern works well when navigation is predictable. If the result depends on validation, permissions, or feature flags, returning a page object too early can hide important behavior. In those cases, separate the action from the outcome and let the test verify what actually happened.
Keep assertions mostly out of page objects
This is one of the most useful rules in any selenium page object model tutorial. In most frameworks, page objects should perform actions and expose state, while test classes own the assertions.
For example, a page object can expose `getErrorMessage()` or `isProfileBannerDisplayed()`. The test should decide whether that result is expected. This separation keeps page classes reusable across positive and negative scenarios.
There are exceptions. Lightweight checks such as `isLoaded()` can be helpful when a page object needs to validate that the page is ready for use. But once page objects start containing full test logic, they stop being reusable building blocks and become hard to maintain.
Better locator strategy matters as much as POM
Page Object Model does not fix poor locators. If your page classes rely on brittle absolute XPath expressions, moving those selectors into a separate class only centralizes the weakness.
Prefer stable IDs, names, data attributes, and selectors tied to application intent rather than visual layout. If your developers can add test-friendly attributes, that is often the cleanest long-term choice. If they cannot, choose selectors that are unlikely to change during normal styling updates.
Also be careful with overusing `@FindBy` and PageFactory in older Selenium examples. Those patterns still appear in tutorials, but many modern teams prefer explicit locators with standard WebDriver calls because they are clearer, easier to debug, and less magical. It depends on your team style, but simplicity usually wins.
Organizing pages for larger applications
Once your suite grows, a single page class per URL is not always enough. Modern web apps often have reusable components like nav bars, modal dialogs, product cards, or table widgets. In that case, component objects are often better than forcing every element into one oversized page class.
For example, a dashboard page might contain a sidebar component and a user menu component. The dashboard page owns those objects, and tests can interact through meaningful methods. This keeps classes smaller and avoids giant page files that nobody wants to touch.
If you are building a framework for a team, consistency matters more than perfection. Pick a naming convention, define where waits belong, and decide how navigation should be modeled. Selenium.Academy teaches this well because maintainability is not a bonus topic in automation – it is the difference between a useful suite and a fragile one.
Common mistakes to avoid
The first mistake is turning page objects into dumping grounds. If one class handles login, profile updates, admin controls, and generic utility methods, your framework has no real boundaries.
The second is writing tests that still reach into locators directly. Once a test bypasses the page object layer, duplication returns quickly.
The third is hiding failures with overly clever wrapper methods. If a click fails because the UI is broken, you usually want the test to fail clearly. Do not build helper methods that swallow exceptions and make debugging harder.
The fourth is chasing abstraction too early. For a small project, a few clear page classes are enough. You do not need five layers of inheritance just because a blog post said so.
A practical starting point for your framework
If you are implementing POM from scratch, keep the first version simple. Create a base page with explicit waits, build one page object per major screen, expose user-centered methods, and let tests own assertions. Once that works, introduce components where duplication appears.
That approach gives you something far more valuable than a fashionable framework pattern. It gives you tests that read clearly, fail honestly, and survive normal UI change with less rework. That is the standard to aim for if you want automation that holds up after the first demo.