Guidelines and Recommendations

A note on "Best Practices": We've intentionally avoided the phrase "Best Practices" in this documentation. No one approach works for all situations. We prefer the idea of "Guidelines and Recommendations." We encourage you to read through these and thoughtfully decide what approaches will work for you in your particular environment.

Functional testing is difficult to get right for many reasons. As if application state, complexity, and dependencies don't make testing difficult enough, dealing with browsers (especially with cross-browser incompatibilities) makes writing good tests a challenge.

Selenium provides tools to make functional user interaction easier, but doesn't help you write well-architected test suites. In this chapter we offer advice, guidelines, and recommendations. on how to approach functional web page automation.

This chapter records software design patterns popular amongst many of the users of Selenium that have proven successful over the years.

Page object models

Page Object is a Design Pattern which has become popular in test automation for enhancing test maintenance and reducing code duplication. A page object is an object-oriented class that serves as an interface to a page of your AUT. The tests then use the methods of this page object class whenever they need to interact with that page of the UI. The benefit is that if the UI changes for the page, the tests themselves don’t need to change; only the code within the page object needs to change. Subsequently, all changes to support that new UI are located in one place.

The Page Object Design Pattern provides the following advantage: there is clean separation between test code and page specific code such as locators (or their use if you’re using a UI map) and layout.

Page object methods should return a value

Domain Specific Language

A domain specific language (DSL) is a system which provides the user with an expressive means of solving a problem. It allows a user to interact with the system on their terms – not just programmer-speak.

Your users, in general, don't care how your site looks. They don't care about the decoration, animations, or graphics. They want to use your system to push their new employees through the process with minimal difficulty. They want to book travel to Alaska. They want to configure and buy unicorns at a discount. Your job as the tester is to come as close as you can to “capturing” this mind-set. With that in mind, we set about “modeling” the application you're working on, such that the test scripts (the user's only pre-release proxy) “speak” for and represent the user.

With Selenium, DSL is usually represented by methods, written to make the API simple and readable – they enable a report between the developers and the stakeholders (users, product owners, business intelligence specialists, etc.).



Here is an example of a reasonable DSL method in Java. For brevity's sake, it assumes the `driver` object is pre-defined and available to the method.

 * Takes a username and password, fills out the fields, and clicks "login".
 * @return An instance of the AccountPage
public AccountPage loginAsUser(String username, String password) {
  WebElement loginField = driver.findElement("loginField"));

  // Fill out the password field. The locator we're using is "", and we should
  // have it defined elsewhere in the class.
  WebElement passwordField = driver.findElement("password"));

  // Click the login button, which happens to have the id "submit".

  // Create and return a new instance of the AccountPage (via the built-in Selenium
  // PageFactory).
  return PageFactory.newInstance(AccountPage.class);

This method completely abstracts the concepts of input fields, buttons, clicking, and even pages from your test code. Using this approach, all your tester has to do is call this method. This gives you a maintenance advantage: if the login fields ever changed, you would only ever have to change this method - not your tests.

public void loginTest() {
    loginAsUser("cbrown", "cl0wn3");

    // Now that we're logged in, do some other stuff--since we used a DSL to support
    // our testers, it's as easy as choosing from available methods.
    Assert.assertTrue("Something should have been done!", something.wasDone());

    // Note that we still haven't referred to a button or web control anywhere in this
    // script...

It bears repeating: one of your primary goals should be writing an API that allows your tests to address the problem at hand, and NOT the problem of the UI. The UI is a secondary concern for your users – they don't care about the UI, they just want to get their job done. Your test scripts should read like a laundry list of things the user wants to DO, and the things they want to KNOW. The tests should not concern themselves with HOW the UI requires you to go about it.

Generating application state

Selenium should not be used to prepare a test case. All repetitive actions, and preparation for a test case, should be done through other methods. For example, most web UIs have authentication (e.g. a login form). Eliminating logging in via web browser before every test will improve both the speed and stability of the test. A method should be created to gain access to the AUT (e.g. using an API to login and set a cookie). Also, creating methods to pre-load data for testing should not be done using Selenium. As mentioned previously, existing APIs should be leveraged to create data for the AUT.

Mock external services

Eliminating the dependencies on external services will greatly improve the speed and stability of your tests.

Improved reporting

Selenium is not designed to report on the status of test cases run. Taking advantage of the built-in reporting capabilities of unit test frameworks is a good start. Most unit test frameworks have reports that can generate xUnit or HTML formatted reports. xUnit reports are popular for importing results to a Continuous Integration (CI) server like Jenkins, Travis, Bamboo, etc. Here are some links for more information regarding report outputs for several languages.

Avoid sharing state

Although mentioned in several places it is worth mentioning again. Ensure tests are isolated from one another.

Don't share test data. Imagine several tests that each query the database for valid orders before picking one to perform an action on. Should two tests pick up the same order you are likely to get unexpected behaviour.

Clean up stale data in the application that might be picked up by another test e.g. invalid order records.

Create a new WebDriver instance per test. This helps ensure test isolation and makes parallelisation simpler.

Test independency

Write each test as its own unit. Write the tests in a way that won't be reliant on other tests to complete:

Let's say there is a content management system with which you can create some custom content which then appears on your website as a module after publishing, and it may take some time to sync between the CMS and the application.

A wrong way of testing your module is that the content is created and published in one test, and then checking the module in another test. This is not feasible as the content may not be available immediately for the other test after publishing.

Instead, you can create a stub content which can be turned on and off within the affected test, and use that for validating the module. However, for content creation, you can still have a separate test.

Consider using a fluent API

Martin Fowler coined the term "Fluent API". Selenium already implements something like this in their FluentWait class which is meant as an alternative to the standard Wait class. You could enable the Fluent API design pattern in your page object and then query the Google search page with a code snippet like this one:

driver.get( "" );
GoogleSearchPage gsp = new GoogleSearchPage();

The Google page object class with this fluent behavior might look like this:

public class GoogleSearchPage extends LoadableComponent<GoogleSearchPage> {
  private final WebDriver driver;
  private GSPFluentInterface gspfi;

  public class GSPFluentInterface {
    private GoogleSearchPage gsp;

    public GSPFluentInterface(GoogleSearchPage googleSearchPage) {
        gsp = googleSearchPage;

    public GSPFluentInterface clickSearchButton() {;
        return this;

    public GSPFluentInterface setSearchString( String sstr ) {
        clearAndType( gsp.searchField, sstr );
        return this;

  @FindBy(id = "gbqfq") private WebElement searchField;
  @FindBy(id = "gbqfb") private WebElement searchButton;
  public GoogleSearchPage(WebDriver driver) {
    gspfi = new GSPFluentInterface( this );
    this.get(); // If load() fails, calls isLoaded() until page is finished loading
    PageFactory.initElements(driver, this); // Initialize WebElements on page

  public GSPFluentInterface withFluent() {
    return gspfi;

  public void clickSearchButton() {;

  public void setSearchString( String sstr ) {
    clearAndType( searchField, sstr );

  protected void isLoaded() throws Error {
    Assert.assertTrue("Google search page is not yet loaded.", isSearchFieldVisible() );

  protected void load() {
    if ( isSFieldPresent ) {
      Wait<WebDriver> wait = new WebDriverWait( driver, 3 );
      wait.until( visibilityOfElementLocated("gbqfq") ) ).click();

Fresh browser per test

Start each test from a clean known state. Ideally, spin up a new virtual machine for each test. If spinning up a new virtual machine is not practical, at least start a new WebDriver for each test. For Firefox, start a WebDriver with your known profile.

FirefoxProfile profile = new FirefoxProfile(new File("pathToFirefoxProfile"));
WebDriver driver = new FirefoxDriver(profile);