Best practices

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 – and especially 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, or best practices if you will, 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 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 or the animations or the 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"
 * @returns 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. An 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

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 you 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);