Building and using an Object Repository in Selenium Webdriver

One of the main burdens of automated GUI test script maintainability is the amount of maintenance needed when object properties change within the application under test. A very common way of minimizing the time it takes to update your automated test scripts is the use of a central object repository (or object map as it’s also referred to sometimes). A basic object repository can be implemented as a collection of key-value pairs, with the key being a logical name identifying the object and the value containing unique objects properties used to identify the object on a screen.

Selenium Webdriver offers no object repository implementation by default. However, implementing and using a basic object repository is pretty straightforward. In this article, I will show you how to do it and how to lighten the burden of test script maintenance in this way.

Note that all code samples below are written in Java. However, the object repository concept as explained here can be used with your language of choice just as easily.

Creating the object repository
First, we are going to create a basic object repository and fill it with some objects that we will use in our test script. In this article, I am going to model a very basic scenario: go to the Bing search engine, search for a particular search query and determine the number of search results returned by Bing. To execute this scenario, our script needs to manipulate three screen objects:

  • The textbox where the search string is typed
  • The search button to be clicked in order to submit the search query
  • The text field that displays the number of search results

Our object map will a simple .properties text file that we add to our Selenium project:
Our object mapThe key for each object, for example bing.homepage.textbox, is a logical name for the object that we will use in our script. The corresponding value consists of two parts: the attribute type used for uniquely identifying the object on screen and the corresponding attribute value. For example, the aforementioned text box is uniquely identified by its id attribute, which has the value sb_form_q.

Retrieving objects from the object repository
To retrieve objects from our newly created object map, we will define an ObjectMap with a constructor taking a single argument, which is the path to the .properties file:

public class ObjectMap {
	
	Properties prop;
	
	public ObjectMap (String strPath) {
		
		prop = new Properties();
		
		try {
			FileInputStream fis = new FileInputStream(strPath);
			prop.load(fis);
			fis.close();
		}catch (IOException e) {
			System.out.println(e.getMessage());
		}
	}

The class contains a single method getLocator, which returns a By object that is used by the Selenium browser driver object (such as a HtmlUnitDriver or a FirefoxDriver):

public By getLocator(String strElement) throws Exception {
		
		// retrieve the specified object from the object list
		String locator = prop.getProperty(strElement);
		
		// extract the locator type and value from the object
		String locatorType = locator.split(":")[0];
		String locatorValue = locator.split(":")[1];
		
		// for testing and debugging purposes
		System.out.println("Retrieving object of type '" + locatorType + "' and value '" + locatorValue + "' from the object map");
		
		// return a instance of the By class based on the type of the locator
		// this By can be used by the browser object in the actual test
		if(locatorType.toLowerCase().equals("id"))
			return By.id(locatorValue);
		else if(locatorType.toLowerCase().equals("name"))
			return By.name(locatorValue);
		else if((locatorType.toLowerCase().equals("classname")) || (locatorType.toLowerCase().equals("class")))
			return By.className(locatorValue);
		else if((locatorType.toLowerCase().equals("tagname")) || (locatorType.toLowerCase().equals("tag")))
			return By.className(locatorValue);
		else if((locatorType.toLowerCase().equals("linktext")) || (locatorType.toLowerCase().equals("link")))
			return By.linkText(locatorValue);
		else if(locatorType.toLowerCase().equals("partiallinktext"))
			return By.partialLinkText(locatorValue);
		else if((locatorType.toLowerCase().equals("cssselector")) || (locatorType.toLowerCase().equals("css")))
			return By.cssSelector(locatorValue);
		else if(locatorType.toLowerCase().equals("xpath"))
			return By.xpath(locatorValue);
		else
			throw new Exception("Unknown locator type '" + locatorType + "'");
	}

As you can see, objects can be identified using a number of different properties, including object IDs, CSS selectors and XPath expressions.

Using objects in your test script
Now that we can retrieve objects from our object map, we can use these in our scripts to execute the desired scenario:

public static void main (String args[]) {

		// Create a new instance of the object map
		ObjectMap objMap = new ObjectMap("objectmap.properties");

		// Start a browser driver and navigate to Google
		WebDriver driver = new HtmlUnitDriver();
        driver.get("http://www.bing.com");

        // Execute our test
        try {
        	
        	// Retrieve search text box from object map and type search query
        	WebElement element = driver.findElement(objMap.getLocator("bing.homepage.textbox"));
			element.sendKeys("Alfa Romeo");
			
			// Retrieve search button from object map and click it
			element = driver.findElement(objMap.getLocator("bing.homepage.searchbutton"));
			element.click();
			
			// Retrieve number of search results using results object from object map
			element = driver.findElement(objMap.getLocator("bing.resultspage.results"));
			System.out.println("Search result string: " + element.getText());
			
			// Verify page title
			Assert.assertEquals(driver.getTitle(), "Alfa Romeo - Bing");
			
		} catch (Exception e) {
			System.out.println("Error during test execution:\n" + e.toString());
		}
        
	}

You can see from this code sample that using an object from the object map in your test is as easy as referring to its logical name (i.e., the key in our object map).

Object repository maintenance
With this straightforward mechanism we have been able to vastly reduce the amount of time needed for script maintenance in case object properties change. All it takes is an update of the appropriate entries in the object map and we’re good to go and run our tests again.

Thanks to Selenium Master for explaining this concept clearly for me to apply.

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

Running Selenium Webdriver tests in Jenkins using Ant

In a previous post I introduced a very simple and straightforward way to run data-driven tests in Selenium Webdriver using test data stored in an Excel sheet. In this post, I want to show how to run these tests using a continuous integration (CI-) solution.

My preferred CI-tool is Jenkins, as it is open source, very flexible and easy to use.
First, make sure that Jenkins is set up properly and is running as a service. Installation is very easy, so I won’t go into details here.

I also recommend using Ant as a software build tool to further ease the process of compiling and running our tests. While it is not strictly necessary to use Ant, it will make life a lot easier for us. Again, install Ant and make sure it is running smoothly by typing ant on the command prompt. If it starts asking for a build.xml file, it’s running properly.

ant_running

Next, open the Selenium Webdriver project in your IDE. Again, I prefer using Eclipse, so the images shown here will be based on Eclipse. Other IDEs such as IntelliJ usually provide the same functionality, it’s just hidden behind different menu options.

Before we start configuring our project for using Ant and running in Jenkins, we are going to add some flexibility to it. Jenkins uses its own workspace and might be running on another server altogether. However, our Selenium project contains a reference to a locally stored Excel data source. Therefore, we are going to add the possibility to provide the path to the data source to be used as an argument to our main method in the Selenium test. In this way, we can simply specify the location of the data source when we run the test. Not only is this necessary to have our test run smoothly in Jenkins, it also adds the possibility to execute several test runs with separate test data sets.

public static void main (String args[]) {
		
		String strPath;
		
		if (args.length == 1) {
			strPath = args[0];
		} else {
			strPath = "Z:\\Documents\\Bas\\blog\\datasources\\testdata.xls";
		}
		
		try {
			// Open the Excel file
			FileInputStream fis = new FileInputStream(new File(strPath).getAbsolutePath());

If an argument is specified when running the main method of our test, we assume this is a relative path to our Excel data source. In order to be able to use it, all we have to do is to get the absolute path for it and off we go. If no argument is specified, we use the default Excel file.

Next, we create a build.xml file that provides Ant with the necessary instructions and details on how to build and run our test. In Eclipse, this can be done easily by right-clicking our project and selecting ‘Export > General > Ant Buildfiles’. After selecting the appropriate project, a build.xml file is generated and added to the root of our project. The example below is a part of the resulting file:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- WARNING: Eclipse auto-generated file.
              Any modifications will be overwritten.
              To include a user specific buildfile here, simply create one in the same
              directory with the processing instruction <?eclipse.ant.import?>
              as the first entry and export the buildfile again. --><project basedir="." default="build" name="seleniumTest">
<property environment="env"/>
<property name="ECLIPSE_HOME" value="C:/Tools/eclipse"/>
<property name="debuglevel" value="source,lines,vars"/>
<property name="target" value="1.7"/>
<property name="source" value="1.7"/>
<path id="seleniumTest.classpath">
    <pathelement location="bin"/>
    <pathelement location="../../../../../vmware-host/Shared Folders/Documents/Bas/blog/libs/selenium-server-standalone-2.37.0.jar"/>
    <pathelement location="../../../../../vmware-host/Shared Folders/Documents/Bas/blog/libs/poi-3.9-20121203.jar"/>
</path>
<target name="init">
    <mkdir dir="bin"/>
    <copy includeemptydirs="false" todir="bin">
        <fileset dir="src">
            <exclude name="**/*.java"/>
        </fileset>
    </copy>
</target>
<target name="clean">
    <delete dir="bin"/>
</target>

Before we can run our tests using Ant, we need to make two modifications.

First, we need to clean up the classpath as we want to use clear and relative paths. Make sure that the necessary libraries can be found on the designated locations. These are specified relative to the location of the build.xml file.

<path id="seleniumTest.classpath">
    <pathelement location="bin"/>
    <pathelement location="libs/selenium-server-standalone-2.37.0.jar"/>
    <pathelement location="libs/poi-3.9-20121203.jar"/>
</path>

Next, we need to make sure that our Excel data source is specified as an argument in the designated Ant target:

<target name="ExcelDataDriven">
    <java classname="com.ontestautomation.selenium.ExcelDataDriven" failonerror="true" fork="yes">
        <arg line="datasources/testdata.xls"/>
        <classpath refid="seleniumTest.classpath"/>
    </java>
</target>

Now, we can execute our test using Ant either in Eclipse or at the command line. When you choose the latter, go to the subdirectory for the Selenium project in your workspace (build.xml should be located there) and execute ant <> (ant ExcelDataDriven in this case). You’ll see that the test is run successfully using Ant.

ant_run_test

The final step is to have this step performed by Jenkins. This should be very straightforward now. Create a new job in Jenkins and add ‘Invoke Ant’ as a build step. Specify the correct target (again, ExcelDataDriven in our case).

jenkins_ant_target

Make sure that all referenced libraries and data sources can be found at the correct locations in the workspace for the Jenkins job (this is where using relative paths comes in handy!). Normally, you would do this using some sort of version control sytem such as Subversion. Next, schedule a build for the job, which should run smoothly now:

jenkins_test_output

That’s it, we’ve now successfully run our Selenium Webdriver tests in Jenkins using Ant. One step closer to a successful continuous integration approach!

Data driven testing in Selenium Webdriver using Excel

Most commercial automated software tools on the market support some sort of data driven testing, which allows you to automatically run a test case multiple times with different input and validation values. As Selenium Webdriver is more an automated testing framework than a ready-to-use tool, you will have to put in some effort to support data driven testing in your automated tests. In this article, I will show you one way of implementing data driven testing in Selenium. There are lots of different approaches possible, and I am aware that the solution presented here can possible be enhanced further enhanced and extended as well, but it will set you off in the right direction when you want to implement data driven testing in your own tests.

The test data source
Before we dive into the implementation in Selenium, let’s first look at the test data source we are going to use to store our input and validation values. As it is widely used in the testing world for test script and test data administration, I usually prefer to use Microsoft Excel as the format for storing my parameters. An additional advantage of using Excel is that you can easily outsource the test data administration to someone other than yourself, someone who might have better knowledge of the test cases that need to be run and the parameters required to execute them.

In the example presented here, I have used a very simple Excel sheet containing a single input parameter (SearchString – a Google search string) and a single validation parameter (PageTitle – the page title displayed by the browser after the search has been executed). Yes, we are performing a pretty trivial test case, but it is sufficient to demonstrate the principle behind the solution presented here.

data_driven_test_data_source

Reading data from the test data source
Next, we need a way to open this Excel sheet and read data from it within our Selenium test script. For this purpose, I use the Apache POI library, which allows you to read, create and edit Microsoft Office-documents using Java. The library, as well as its JavaDoc, can be found at http://poi.apache.org. The classes and methods we are going to use to read data from our Excel sheet are located in the org.apache.poi.hssf.usermodel package.

A simple main method, where we loop through all rows in the Excel sheet containing test data and call the actual test method using the current test data, could look like this:

public static void main (String args[]) {

	try {
		// Open the Excel file
		FileInputStream fis = new FileInputStream("Z:\\Documents\\Bas\\blog\\datasources\\testdata.xls");
		// Access the required test data sheet
		HSSFWorkbook wb = new HSSFWorkbook(fis);
		HSSFSheet sheet = wb.getSheet("testdata");
		// Loop through all rows in the sheet
		// Start at row 1 as row 0 is our header row
		for(int count = 1;count<=sheet.getLastRowNum();count++){
			HSSFRow row = sheet.getRow(count);
			System.out.println("Running test case " + row.getCell(0).toString());
			// Run the test for the current test data row
			runTest(row.getCell(1).toString(),row.getCell(2).toString());
		}
		fis.close();
	} catch (IOException e) {
		System.out.println("Test data file not found");
	}	
}

Simple, yet effective. Of course, many enhancements or improvements can be made to this example, such as:

  • The path to the test data file can be passed as an argument to the main method, or the user can be allowed to select a test data sheet, for example using JFileChooser
  • The fact that the first row contains column headers can be made optional, for example by passing a Boolean argument to our method
  • Instead of using column indexes as we have done here (in the getCell method, we could use column headers and have our code determine the correct column index for a given column at runtime

Executing our sample test
The actual test we are going to execute is located in the runTest method, which is called from the main method for every test data row in our sheet. It starts a browser driver, in this case a HtmlUnitDriver, executes a Google query using the query from the Excel sheet and checks the page title to see whether it matches the expected value. The code is pretty straightforward:

public static void runTest(String strSearchString, String strPageTitle) {
		
		// Start a browser driver and navigate to Google
		WebDriver driver = new HtmlUnitDriver();
        driver.get("http://www.google.com");

        // Enter the search string and send it
        WebElement element = driver.findElement(By.name("q"));
        element.sendKeys(strSearchString);
        element.submit();
        
        // Check the title of the page
        if (driver.getTitle().equals(strPageTitle)) {
        	System.out.println("Page title is " + strPageTitle + ", as expected");
        } else {
        	System.out.println("Expected page title was " + strPageTitle + ", but was " + driver.getTitle() + " instead");
        }
        
        //Close the browser
        driver.quit();
}

When we run this test, we can see in our stdout that the test script is executed three times, once for each row in the test data sheet:
data_driven_console_outputAdding or changing test cases is now as easy as editing the Excel sheet associated with our test. As long as nothing is changed in the location or the order of the columns, no maintenance is required in our Selenium script.