How To Minimize The Pain Of Locator Breakage

Posted by Adam Goucher in Selenium Resources

In the Agile world, a common saying is 'never break the build.' But this thought can actually hinder agility if taken too literally. Sometimes, you want the build to break, as that means things are changing and progressing. A better phrase is 'don't leave the build broken'. The same could be said for Selenium and element locators. They will break, and we want them to...periodically. The measures that count are:

  • How long it takes to go from broken to fixed - this should be small; really, really small
  • How big is the change to fix them - ideally, only one line per element. Total. Throughout the whole code base.

So how do we go about fixing these intermittent breakages? The easiest locator to use is 'id.' To be most successful with this strategy, a static id attribute is put on each html element being interacted with. And since we don't know what elements will be needed to automate in the future, it's best to put an id on every element. The scripts will always know how to find the elements on the page uniquely, as WSC standards require that ids be unique in a single page. While this solves the html structure change problems that often come from using XPath and CSS selectors by finding elements independently of their position, it still doesn't solve id change issues. Solving that requires discipline and communication among the development and automation teams. One geographically dispersed team I worked with created the following two-part policy for this.

  1. Anyone can add an id to an element that does not have one
  2. If you change an id, the change must be communicated to both the dev and automation teams

Of course, knowing about a change is a bitter pill to swallow when it involves updating hundreds of scripts. A better solution is to separate the locator definitions from the main test code.

Selenium IDE
Separation of scripts from locators is achievable in Selenium IDE through the use of user-extensions. A previous Sauce Labs blog post, Parametrizing Selenese tests, explains how to make use of these extensions, but rather than provide the 'Value' column, the 'Target' is what could [should] be provided by the user-extension.

storedVars["registrationFirstname"] = "first";
storedVars["registrationLastname"] = "last";
storedVars["registrationSubmit"] = "register";

A script that interacts with a registration form might look like:

open /registration
type ${registrationFirstname} fred
type ${registrationFirstname} flintstone
click ${registrationSubmit}

Going back and updating Selenese scripts is a pain, but using user-extensions to provide the locators to your scripts makes it as simple as updating an external JS file. Selenium RC Most Selenium RC languages have a way of reading run-time properties from external files in some native manner:

  • Java - Properties
  • Python - ConfigParser or maybe just python dictionaries
  • Ruby - YAML
  • C# - App.Config

If you're writing your scripts in Java, you should create a file, which would include something along the lines of:

# uses the id locator
# xpath
# css
registration.submit=css=form submit

Here is a Java class that interacts with our very simplistic registration form, and uses the external properties file (above) for its locators.

import java.util.Properties;

import org.junit.Before; import org.junit.Test; import org.junit.After;

import com.thoughtworks.selenium.DefaultSelenium; import com.thoughtworks.selenium.Selenium;

public class TestRegistration. { private Selenium selenium; public static Properties locators = new Properties();

public void setUp() throws Exception
    InputStream is = TestRegistration.class.getResourceAsStream("/");

    selenium = new DefaultSelenium("localhost", 4444, "*firefox", "http://localhost:3000");

public void testVisibleElement() throws Exception
    selenium.type(locators.getProperty("registration.firstname"), "fred");
    selenium.type(locators.getProperty("registration.lastname"), "flintstone");"registration.firstname");

public void tearDown() throws Exception


Notice there are no hardcoded locator strings in the test, so we can change locators without changing the script. And if a consistent, well-thought-out naming convention is used for the property names, it CAN actually increase the readability of the scripts. By using the same throughout the whole suite of scripts, a single change will cascade to all scripts. It also means that as ids become available on elements that didn't have them previously, they can quickly be replaced with more structurally dependent methods, such as XPath and CSS. A further benefit is that, by quickly scanning the file, one can determine where in the suite XPath is still being used; converting from XPath to CSS is currently a recommended practice for performance reasons.

Page Objects
Page Objects are a way of representing a web page as a class (or number of classes) to bring Object Oriented techniques and patterns to Selenium. Most Page Object patterns have the locators abstracted out of the actual Page Objects and into a higher level parent class. But even then, those locators should be loaded from an external mechanism to allow for locator changes without recompilation. Page Objects are beyond the scope of this article, but for an introduction and a sample implementation pattern of them in Python, see Page Objects in Python - Automating Page Checking without Brittleness.

Next Steps
Separating scripts from the locators being used is an important step towards reducing the amount of time teams invest in keeping their automation running. Too often, though, teams jump on this idea and invest valuable time converting their whole suite, which sets them further behind what the features development is producing. A better solution for the team is to collectively decide that scripts and locators will be separate, and from then on, only create scripts in this model, and only backport the abstraction of locator string when they break in existing code. The scripts will be 'hybrid' for a time, but ultimately it's a much faster approach.

Discuss: How To Minimize The Pain Of Locator Breakage

Free Trial

Get access to a free 14-day trial version, or contact Sales for more information.