Using the Page Object Design pattern in Selenium Webdriver

In a previous post, we have seen how using an object map significantly reduces the amount of maintenance needed on your Selenium scripts when your application under test is updated. Using this object map principle minimizes duplication of code on an object level. In this post, I will introduce an additional optimization pattern that minimizes code maintenance required on a higher level of abstraction.

Even though we have successfully stored object properties in a SPOM (a Single Point Of Maintenance), we still have to write code that handles these objects every time our script processes a given page including that object in our set of test scripts. If our set of test scripts requires processing a login form five times throughout the execution, we will need to include the code that handles the objects required to log in – a username field, a password field and a submit button, for example – five times as well. If the login page changes but the objects defined previously remain the same – for example, an extra checkbox is included to have a user agree to certain terms and conditions – we still need to update our scripts five times to include the processing of the checkbox.

To eliminate this code redundancy and maintenance burden, we are going to use a different approach known as the Page Object design pattern. This pattern uses page objects that represent a web page (or a form within a page, if applicable) to separate test code (validations and test flow logic, for example) from page specific code. It does so by making all actions that can be performed on a page available as methods of the page object representing that page.

So, assuming our test scripts needs to login twice (with different credentials), instead of this code:

public static void main(String args[]) {
	
	// start testing
	WebDriver driver = new HtmlUnitDriver();
		
	// first login
	driver.get("http://ourloginpage");
	driver.findElement(objMap.getLocator("loginUsername")).sendKeys("user1");
	driver.findElement(objMap.getLocator("loginPassword")).sendKeys("pass1");
	driver.findElement(objMap.getLocator("loginSubmitbutton")).click();
		
	// do stuff
		
	// second login
	driver.get("http://ourloginpage");
	driver.findElement(objMap.getLocator("loginUsername")).sendKeys("user2");
	driver.findElement(objMap.getLocator("loginPassword")).sendKeys("pass2");
	driver.findElement(objMap.getLocator("loginSubmitbutton")).click();
		
	// do more stuff
	
	// stop testing
	driver.close();
}

we would get

public static void main(String args[]) {
		
	// start testing
	WebDriver driver = new HtmlUnitDriver();
		
	// first login
	LoginPage lp = new LoginPage(driver);
	HomePage hp = lp.login("user1","pass1");
		
	// do stuff
		
	// second login
	LoginPage lp = new LoginPage(driver);
	HomePage hp = lp.login("user2","pass2");
		
	// do more stuff
		
	// stop testing
	driver.close();
}

Now, when we want to go to and handle our login page, we simply create a new instance of that page and call the login method to perform our login action. This method in turn returns a HomePage object, which is a representation of the page we get after a successful login action. A sample implementation of our LoginPage object could look as follows:

public class LoginPage {
	
	private final WebDriver driver;
	
	public LoginPage(WebDriver driver) {
		this.driver = driver;
		
		if(!driver.getTitle().equals("Login page")) {
			// we are not at the login page, go there
			driver.get("http://ourloginpage");
		}
	}
	
	public HomePage login(String username, String password) {
		driver.findElement(objMap.getLocator("loginUsername")).sendKeys("username");
		driver.findElement(objMap.getLocator("loginPassword")).sendKeys("password");
		driver.findElement(objMap.getLocator("loginSubmitbutton")).click();
		return new HomePage(driver);
	}	
}

It contains a constructor that opens the login page if it is not visible already. Alternatively, you could throw an exception and stop test execution whenever the login page is not the current page, depending on how you want your test to behave. Our LoginPage class also contains a login method that handles our login actions. If ever the login screen changes, we only need to update our test script once thanks to the proper use of page objects.

When the login action is completed successfully, our test returns a HomePage object. This class will be set up similar to the LoginPage class and provide methods specific to the page of our application under test it represents.

In case we also want to test an unsuccessful login, we simply add a method to our LoginPage class that executes the behaviour required:

public LoginPage incompleteLogin(String username) {
	driver.findElement(objMap.getLocator("loginUsername")).sendKeys("username");
	driver.findElement(objMap.getLocator("loginSubmitbutton")).click();
	return this;
}

This alternative login procedure does not enter a password. As a result, the user is not logged in and the login page remains visible, hence we return the current LoginPage object here instead of a HomePage object. If we want to test this type of incorrect login in our script, we simply call our new incorrectLogin method:

public static void main(String args[]) {
		
	// start testing
	WebDriver driver = new HtmlUnitDriver();
		
	// incorrect login
	LoginPage lp = new LoginPage(driver);
	lp = lp.incompleteLogin("user1");
	Assert.assertEquals("You forgot to type your password",lp.getError());
		
	//stop testing
	driver.quit();
}

The getError method is implemented in our LoginPage class as well:

public String getError() {
	return driver.findElement(objMap.getLocator("errorField")).getText();
}

This getError method is the result of another best practice. In order to keep your test code as much separated from your object code, always place your assertions outside of your page objects. If you need to validate specific values from a page, write methods that return them, as we did in the example above using the getError method.

To wrap things up, using the Page Object design pattern, we introduced another Single Point of Maintenance or SPOM in our Selenium test framework. This means even less maintenance required and higher ROI achieved!

An example Eclipse project using the pattern described above can be downloaded here.

Best practice: use UI-driven automated testing only when necessary

Question: what do you think of when I ask ‘what does test automation look like’? Chances are high that you think of a tool that replays user interaction with an application using the graphical user interface. This user interaction is either captured through recording functionality in the tool that is used and subsequently replayed, or it is programmed by a test automation engineer, or a mixture of both approaches is used.

Traditionally, these tools use HTML object attributes to uniquely identify and manipulate objects on the screen. Recently, a number of tools have emerged that use image recognition to look for and manipulate screen objects. Object recognition approach notwithstanding, all of these tools use the user interface to interact with the application under test.

This approach to automated testing is one of the most popular ones out there. For starters, it looks good in demos and sales pitches. More importantly though, it most closely represents how a manual test engineer or an end user would interact with the application under test. However, there’s a fundamental problem attached to UI-based automated testing. Too often, the investment just isn’t outweighed by the profits. Test automation engineers spend hours upon hours on crafting and maintaining wonderful frameworks and intricate scripts, with no one evaluating the ROI for these efforts.

Now, I don’t say that UI test automation shouldn’t be done. It definitely has a place within the overall spectrum of test automation, and I have seen it used with great results in various places. However, I do feel it is overused in a lot of projects. Most of the times, the test automation team or their managers fell into one of the pitfalls of UI test automation:

  • All test scripts are automated using a UI-based test automation approach, even those test cases that aren’t really about the UI.
  • Test automation engineers try to automate every test script available, and then some more. It might be due to their own poor judgment or to the wishes / demands from management to automate all test scripts, but bottom line is that not all test scripts should be automated just because it can be done.
  • The test automation approach is suboptimal with regards to maintainability. Several best practices exist to ensure maximum maintainability for automated UI test scripts, including use of object maps and keyword-driven test frameworks. If these are not applied or if they are applied incorrectly, more time might be required for automated test script maintenance.

Therefore, I’d recommend the use of UI-based test automation only when either (or both) of the following is true:

  1. The test script actually contains validations and/or verifications on the user interface level, or
  2. There is no alternative interface available for interacting with the application.

With regards to the second point, alternative interfaces could include interfaces on web service or on database level. Using these to drive your automated tests remove some of the major drawbacks of UI-based test automation, such as the maintenance burden due to changes in UI object properties and UI synchronization issues.

Case study
I have used the principles outlined above with good results in a project a couple of years ago In this project, I was responsible for setting up an automated test suite for an application built on the Cordys (now OpenText) Business Process Management suite. This application could be decomposed into four tiers: the user interface, a BPM tier, a web service tier and a database tier.

At first, I started out building automated tests on the user interface level, as this BPMS was still new to me and this was the obvious starting point. I soon realized that automating tests on the UI level was going to be very hard work as the user interface was very dynamic with a lot of active content (lots of Javascript and Xforms). If I was to deliver a complete set of automated test scripts, I would either have to invest a lot of time on maintenance or find some other way to achieve the desired results.

Luckily, by digging deeper into the Cordys BPMS and reading lots of material, I found out that it has a very powerful web service API. This API can be used not only to drive your application, but to query and even configure the BPMS itself as well. For instance, using this web service API, you can:

  • Create new instances of the BPM models used in the application under test,
  • Send triggers and messages to it, thus making the BPM instance change state and go to a subsequent state,
  • Verify whether the new state of the BPM instance matches the expected state, and so on..

Most of this could be done using predefined web service operations, so the risk of these interfaces changing during the course of the project was small to none. Using this API, I was able to set up an automated test for 80-90% of the application logic, as the user interface was nothing more than a user-friendly way to send messages to process instances display information about the current state and the next action(s) to take. Result!

Use UI testing only when the user interface is actually tested

Even better, in later projects where Cordys was used, I have been able to reuse most of the automated testing approach and the framework I used to set up and execute automated tests. Maximum reusability achieved and minimum maintenance required, all through a change of perspective on the automated testing approach.

Have you experienced similar results, simply by a shift of test automation perspective? Let me know.

Up and running with: JUnit

This is the first article in a new series on tools used in test automation. Each of the articles in it will introduce a specific test tool and will show you how to get up and running with it. The focus will be on free and / or open source test tools as this allows everyone with an interest in the tool presented to get started using it right away.

What is JUnit?
JUnit is a unit testing framework for Java. Is it part of a family of unit testing frameworks for a variety of programming languages, known collectively as xUnit. With JUnit, you can quickly develop and run unit tests for Java classes to verify their correctness.

Where can I get JUnit?
JUnit can be downloaded from here. However, when you use an IDE such as Eclipse or IntelliJ, JUnit comes with the installation, making getting started with JUnit test development even easier.

How do I install and configure JUnit?
As I prefer using Eclipse, the instructions below show you how to start developing and running JUnit tests in Eclipse. Those using IntelliJ are referred to the IntelliJ homepage.

To start using JUnit to run tests on your code, all you need to do is to add the JUnit library to your existing Java project. To do this, right-click on your project, select Properties, go to the Libraries tab and press the ‘Add Library’ button. Select JUnit from the list and click ‘Next’. Then, select ‘JUnit 4’ as the library version and click ‘Finish’. JUnit has now been added to your project libraries and you’re ready to go.

junit_add_library

Creating a first test script
Now, let’s create a first JUnit test script. First of all, as JUnit tests are Java classes in themselves, we create a new source folder in our project to prevent test code getting mixed up with application code. Right-click on your project, select Properties and in the Source tab, select ‘Add Folder’. Name this folder ‘test’ for instance and add it to your project.

It’s a good idea to structure the test code in your test folder similar to the application code to be tested. So, if the Java class you are writing tests for is in package x.y.z in the ‘src’ folder, your test code for this class is placed in package x.y.z in the ‘test’ folder. Create this package in the ‘test’ folder by right-clicking it and selecting ‘New > Package’.

One of the features of Eclipse is that it can automatically generate JUnit test skeletons for you based on the definition of the class you’re writing tests for. To do so, right-click on the package you’ll place the test code in and select ‘New > JUnit Test Case’. Name your test class – I prefer adding ‘Test’ to the name of the class to be tested, so tests for class Apple.java are placed in AppleTest.java – and select the class under test using the button ‘Select’ next to ‘Class under test:’. Click ‘Next’ and select the methods for which you want to generate JUnit tests.

junit_select_methods

Click ‘Finish’ to generate JUnit test skeletons for the selected methods. The code generated should be similar to this:

package com.ontestautomation.selenium.objectmap;

import static org.junit.Assert.*;

import org.junit.Test;

public class ObjectMapTest {

	@Test
	public void testObjectMap() {
		fail("Not yet implemented");
	}

	@Test
	public void testGetLocator() {
		fail("Not yet implemented");
	}

}

The annnotation @Test is used by JUnit to indicate the start of a test case. The generated test code is neatly placed in the right package in your Java project:

junit_package_explorer

Running your test
To run your JUnit tests, simply right-click the test code file and select ‘Run As > JUnit Test’. Your test methods will be executed and a new tab opens displaying the test results:

junit_test_results_1

Both tests fail for now as they have not yet been implemented. That is, no actual tests are being executed so far as we haven’t written the tests itself yet. Below you see a simple test for the getLocator method that tests whether the object retrieved from the object map using this method is equal to the object that is expected.

@Test
public void testGetLocator() {
	ObjectMap objMap = new ObjectMap("objectmap.properties");
	try {
		By testLocator = objMap.getLocator("bing.homepage.textbox");
		assertEquals("Check testLocator object",By.id("sb_form_q"),testLocator);
	} catch (Exception e) {
		System.out.println("Error during JUnit test execution:\n" + e.toString());
	}
		
}

If we rerun the test code, we now see that the test for the getLocator method passes, meaning we have successfully implemented and run our first JUnit test!

junit_test_results_2

Useful features
To write more advanced and better maintainable tests, JUnit provides some nice features. The most important of these features are:

  • The ability to test for expected exceptions. If you want to validate that the method you developed throws the right exception under the right circumstances, you can easily verify this with JUnit, using the expected=NameOfException.class notation:
@Test(expected=Exception.class)
public void testGetLocatorException() throws Exception {
	ObjectMap objMap = new ObjectMap("objectmap.properties");
	By testLocator = objMap.getLocator("unknownobject");
}
  • The ability to create test suites using the @Suite annotation. Using this you can run a set of test classes by calling a single test suite class.
  • The ability to parameterize tests with test data, using the @Parameterized annotation. Using this you can make your unit tests data driven and run the same tests using multiple sets of test data without the need for duplicate test code.
  • The ability to easily export test results to continuous integration frameworks, such as Jenkins. JUnit generates reports in an XML format that can easily be interpreted by Jenkins and similar CI frameworks. This results in a very readable graphical representation of your JUnit test results:

build_result_test_detail

Further reading
For more information on JUnit, you can visit the sites below:

An Eclipse project including the tests I’ve demonstrated above and the reports that have been generated can be downloaded here.

Happy unit testing!