Monster Sandwich: Selenium JUnit Testing

I recently put together a Selenium JUnit testing project to automate testing for a web project I am working on. Having never done or worked on a Selenium project before I did a little research into finding out how it works and what approach best suits me. The following describes a few things I decided upon.

Selenium is used to automate tests through a web browser. Jenkins was used to run the tests from this project after a successful build of and deploy of the web application.

Useful Resources

Here are a couple of useful links where you can find more information on Selenium:

I decided on the following design principles for the Selenium test project:

Each test should run in its own session

Starting a new session means closing the browser and opening it again. The disadvantage to this is that it takes longer to complete a test however the advantage means that any previously run tests don’t pollute the session for the currently running test.
The change to the above also means that within Eclipse you can choose to run all tests by running the test suite or you could also selectively choose an individual test to run as each test can be run independently from each other. You could do the same within Buildr or through the command line.

Spring Support

Spring support has been added to the test project classes so that we could take advantage of the following:

Dependency injection, example would be connection to the database
The ability to run the test cases for different environments based on a spring profile setting
Use of Spring support classes, example: jdbctemplate

Important notes to keep in mind:

Tests are NOT transactional. Selenium opens a browser and users the applications configured transaction manager.

DbUnit

DbUnit is a JUnit extension targeted at database-driven projects that puts your database into a known state between test runs. DbUnit has the ability to export and import your database data to and from XML datasets.

The tests should not rely on data already in the database since I did not have a dedicated test database and the state of the database is not guaranteed. In certain scenarios we could write tests that use data from the database where we know the data is not going to change. DbUnit is used to populate the database with test data before we run the test and then it removes the data from the database at the end of the test run.

Please refer to the following link in finding out the recommended best practices for DbUnit:

http://dbunit.sourceforge.net/bestpractices.html

The test project is also using the Spring Test DbUnit project to integrated with the Spring testing framework. It allows you to setup and teardown database tables using simple annotations as well as checking expected table contents once a test completes.

Page Object Model Design Pattern

The Page Object Model is a design pattern to create Object Repository for web UI elements. The following principles apply:

Under this model, for each web page in the application there should be corresponding page class
This Page class will find the WebElements of that web page and also contains Page methods which perform operations on those WebElements
Name of these methods should be given as per the task they are performing i.e., if a loader is waiting for payment gateway to be appear, POM method name can be waitForPaymentScreenDisplay()

Here are some of the advantages of applying the Page Object Model Design Pattern:

Page Object Patten says operations and flows in the UI should be separated from verification. This concept makes our code clean and easy to understand
Second benefit is the object repository is independent of testcases, so we can use the same object repository for a different purpose with different tools. For example, we can integrate POM with TestNG/JUnit for functional testing and at the same time with JBehave/Cucumber for acceptance testing
The number of lines of code are reduced and optimized because of the reusable page methods in the POM classes
Methods get more realistic names which can easily be mapped to the operation happening in the UI, i.e. if after clicking on the button we land on the home page, the method name could be 'gotoHomePage()'

Some useful links:

PageFactory and Selenium Support Annotations

The PageFactory class provides a convenient way of initialising the Page Object fields:

  page = PageFactory.initElements(new FirefoxDriver(), TestPage.class);

It can be used to map Page Object properties to fields with matching ids or names. To make it even easier we can do this with the @FindBy annotation:

 @FindBy(id="myFieldId")
 private WebElement myField;

One problem is that every time we call a method on the WebElement the driver will go and find it on the current page again. In an AJAX-heavy application this is what you would like to happen, but in the some cases we know that the element is always going to be there and won't change. We also know that we won't be navigating away from the page and returning. It would be handy if we could "cache" the element once we'd looked it up:

  // The element is now looked up using the name attribute,
  // and we never look it up once it has been used the first time 
  @FindBy(name="myFieldId")
  @CacheLookup
  private WebElement myField;

For more information on the PageFactory please read the following link:

https://code.google.com/p/selenium/wiki/PageFactory

Waiting for an element to exist before looking it up

Selenium tests require a browser to open and a page to load before the code attempts to lookup the expected elements in the page. Selenium has a number of settings to try and cater for this scenario:

Implicit Wait

We can tell Selenium that we would like it to wait for a certain amount of time before throwing an exception when it cannot find the element on the page. Implicit waits will be in place for the entire time the browser is open. This means that any search for elements on the page could take the time the implicit wait is set for.

  WebDriver driver = new FirefoxDriver();
  driver.manage().timeouts().implicitlyWait(10, TimeUnit.SECONDS);
  driver.get("http://url_that_delays_loading");
  WebElement myDynamicElement = driver.findElement(By.id("myDynamicElement"));

During Implicit wait if the Web Driver cannot find it immediately because of its availability, the WebDriver will wait for the mentioned time and it will not try to find the element again during the specified time period. Once the specified time is over, it will try to search the element once again the last time before throwing exception. The default setting is zero. Once we set a time, the Web Driver waits for the period of the WebDriver object instance.

FluentWait

Each FluentWait instance defines the maximum amount of time to wait for a condition, as well as the frequency with which to check the condition. Furthermore, the user may configure the wait to ignore specific types of exceptions whilst waiting, such as NoSuchElementExceptions when searching for an element on the page.

If you have an element which sometime appears in just 1 second and some time it takes minutes to appear than it is better to use fluent wait, as this will try to find the element again and again until it finds it or until the final timer runs out.

 // Waiting 30 seconds for an element to be present on the page, checking
 // for its presence once every 5 seconds.
 Wait wait = new FluentWait(driver)
   .withTimeout(30, SECONDS)
   .pollingEvery(5, SECONDS)
   .ignoring(NoSuchElementException.class);
 
 WebElement foo = wait.until(new Function() {
   public WebElement apply(WebDriver driver) {
     return driver.findElement(By.id("foo"));
   }
 });

Another case where FluentWait can and is used is when certain events on a page cause the DOM tree to be modified, you can end up with a StaleElementException to the reference you have of that element. When this happens you will need to reinitialise the element or look it up again after the DOM tree has been rebuilt. A StaleElementException is thrown when the element you were interacting is destroyed and then recreated. An example of where this happens in the Meterflow application is on showing a Modal dialog and trying to enter values in input texts to submit a form. Here is an example of code that you can use in this scenario:

 
 public MyPage waitForModalDialogToShow() {
   final Wait<WebDriver> wait = new FluentWait<WebDriver>(driver).withTimeout(30, TimeUnit.SECONDS)
     .pollingEvery(5, TimeUnit.SECONDS)
     .ignoring(NoSuchElementException.class, StaleElementReferenceException.class);
   
   wait.until(new Function<WebDriver, WebElement>() {
     public WebElement apply(WebDriver driver) {
       return driver.findElement(By.id("myModelDialog"));
     }
   });
   
   return this;
 }

In situations where you are using the FindBy annotations on a PO class and not explicitly calling driver.findElement and the DOM was changed due to some user events you may also need to reinitialise the PO object so that the fields are looked up again after the DOM has been recreated. To do this you can call the following static method on the PageFactory class:

 
 /**
  * Reinitialise a PageObject by replacing the fields of an already instantiated Page Object. 
  */
  public void initElements() {
    PageFactory.initElements(driver, this);
  }

Explicit WebDriverWait

The WebDriverWait is a specialization of FluentWait that uses WebDriver instances. It is more extendible in the means that you can set it up to wait for any condition you might like. Usually, you can use some of the prebuilt ExpectedConditions to wait for elements to become clickable, visible, invisible, etc.

There can be an instance when a particular element takes more than a minute to load. In that case you don't want to set a huge time to Implicit wait because then your browser will wait the same time for every element. To avoid that situation you can put a separate time on the required element.

  WebDriverWait wait = new WebDriverWait(driver, 10);
  WebElement element = wait.until(ExpectedConditions.elementToBeClickable(By.id("someid")));

Selenium Locator Strategies

There are 8 locators that Selenium’s commands support:

id - Ids are the most preferred way to locate elements on a page, fast and reliable way to locate elements
name - An efficient way to locate an element but unlike Ids, name attributes don’t have to be unique in a page
identifier - Combination of id and name, first checks the @id attribute and if no match is found it tries the @name attribute
css - Locate an element by using CSS selectors to find the element in the page
xpath - Locate an element using an XPath query
link - Locate a link element ("a" tag) by the text used within the link tag
dom - Locate elements that match the JavaScript expression referring to an element in the DOM of the page
ui - Selenium IDE extension (http://ttwhy.org/code/ui-doc.html)

FindBy annotation support

The @FindBy annotation supports the following locators:
id

 My text

 
 @FindBy(id="elementId")
 private WebElement myElement;

name

 
 My text

 @FindBy(name="elementName")
 private WebElement myElement;

className

  
    block

 
 @FindBy(className="element-css")
 private WebElement myElement;

css

 
   block
 
 
   block
 
  
 

 Google

 @FindBy(css="div.element-css")
 private WebElement myElementEx1;

 @FindBy(css="div.element-css[id='myElementId']")
 private WebElement myElementEx2;

 @FindBy(css="input[name='textName'][type='text']")
 private WebElement myElementEx3;

 @FindBy(css="a[name='link']")  
 private WebElement myElementEx4;

linkText

 Google

 @FindBy(linkText="Google")
 private WebElement myElement;

partialLinkText

 Google

 @FindBy(partialLinkText="Goo")
 private WebElement myElement;

tagName

 
 Link1
 
 Link2

 Link3

 
 @FindBy(tagName = "a")
 private List myLinks;

xpath

  
    block

 
 @FindBy(xpath="//span[@class='element-css']")
 private WebElement myElement;

A few examples

Finding a cell in a table generated by Primefaces, an example of what the generated html table would look like:

 <div id="myFormId:myTableId" class="ui-datatable ui-widget">
  <div class="ui-datatable-tablewrapper">
    <table role="grid">
      <thead id="myFormId:myTableId_head">
        <tr role="row">
          <th id="myFormId:myTableId:j_idt44" class="ui-state-default" role="columnheader">
            <span class="ui-column-title">Column 1</span>
          </th>
          <th id="myFormId:myTableId:j_idt45" class="ui-state-default" role="columnheader">
            <span class="ui-column-title">Column 2</span>
          </th>
        </tr>
      </thead>
      <tfoot id="myFormId:myTableId_foot"/>
      <tbody id="myFormId:myTableId_data" class="ui-datatable-data ui-widget-content">
        <tr class="ui-widget-content ui-datatable-even ui-datatable-selectable" role="row">
          <td role="gridcell">
            <span id="myFormId:myTableId:0:col1">Row 1 - Value of column 1</span>
          </td>
          <td role="gridcell">
            <span id="myFormId:myTableId:0:col2">Row 1 - Value of column 2</span>
          </td>
        </tr>
        <tr class="ui-widget-content ui-datatable-even ui-datatable-selectable" role="row">
          <td role="gridcell">
            <span id="myFormId:myTableId:2:col1">Row 2 - Value of column 1</span>
          </td>
          <td role="gridcell">
            <span id="myFormId:myTableId:2:col2">Row 2 - Value of column 2</span>
          </td>
        </tr>
      </tbody>
    </table>
  </div>
 </div>

 // find all the table cells that match the css selector
 @FindBy(css="div[id='myFormId:myTableId'] > div > table > tbody > tr > td > span")

 // same as above but won't only check the next element in tree and will keep searching until a match is found
 @FindBy(css="div[id='myFormId:myTableId'] table td span")

 // find all the table cells that match the xpath query
 @FindBy(xpath="//div[@id='myFormId:myTableId']/div/table/tbody/tr/td/span")

 // same as above but won't only check the next element in tree and will keep searching until a match is found
 @FindBy(xpath="//div[@id='myFormId:myTableId']//table//td//span")

 // to find a cell that contains text
 @FindBy(xpath="//div[@id='myFormId:myTableId']//table//td//span[contains(text(),'Row 1 - Value of column 1')]")

Find an element whose ID matches part of an expression, the following examples use an "a" link element but can be any valid html tag:

 <a id="j_idt38:myLink" href="/tmp.xhtml" class="ui-link ui-widget">Tmp</a>

 // css strategy to find an element whose ID starts with 'j_idt38'
 @FindBy(css="a[id^='j_idt38']")

 // css strategy to find an element whose ID ends with 'myLink'
 @FindBy(css="a[id$='myLink']")

 // css strategy to find an element whose ID contains 'myLink'
 @FindBy(css="a[id*='myLink']")

 // xpath query strategy to find an element whose ID contains 'myLink'
 @FindBy(xpath="//a[contains(@id, 'myLink')]")

Perform Javascript actions, the following example describes a javascript event being carried out when the mouse hovers over certain menu items:

 <li id="topNavFrm:adminSubmenu">
  <a href="#">
    <span />
    <span >Administration</span>
    <span />
  </a>
  <ul role="menu">
    <li id="topNavFrm:usersSubMenu">
      <a href="#">
        <span />
        <span>Users</span>
        <span />
      </a>
      <ul>
        <li>
          <a id="topNavFrm:userGroupMenuItem" href="/users/groups.xhtml">
            <span>User Groups</span>
          </a>
        </li>
        <li>
          <a href="/users/users.xhtml">
            <span>Users</span>
          </a>
        </li>
      </ul>
    </li>
  </ul>
 </li>

 @FindBy(id="topNavFrm:adminSubmenu")
 private WebElement adminMenu;

 public UsersAdminPage mouseOverUsersDetailMenu() {
   Actions action = new Actions(driver);
   action.moveToElement(adminMenu).perform();
       
   WebElement usersSubElement = adminMenu.findElement(By.cssSelector("li[id='topNavFrm:usersSubMenu'] a"));
   action.moveToElement(usersSubElement);
       
   WebElement usersAdminSubElement = adminMenu.findElement(By.id("topNavFrm:usersMenuItem"));
   action.moveToElement(usersAdminSubElement);
       
   action.click();
   action.perform();
  
   return this;
 }

XPath Query Testing

Testing XPath queries can be done within the browser, this sections shows examples of how you could do it with some of them:

Chrome

To type in an xpath to search a page:

Press F12 to open Chrome Developer Tool
In "Elements" panel, press Ctrl+F
In the search box, type in XPath or CSS Selector, if elements are found, they will be highlighted in yellow.

To copy an xpath from an element in the page (same can be done to retrieve CSS path):

Right click on element and select Inspect Element
In elements view right click on element line and select Copy XPath

Firefox