Understanding Locators

Owned by Michael Harnish
Last updated: Nov 28, 2017
4 min read

Many Toffee commands allow you to perform actions on elements on a web page, or to test that the contents, value, or state of that element matches your expectations. Before Toffee can manipulate or test an element, it has to know how to find that element on the page. This is the job of locator expressions, or locators for short. Locator expressions comprise an element name (e.g., button, textbox, or checkbox) and an address.

Element Names

Element names indicate the kind of element you are looking for. If you don't know (or care) what type of element you're looking for, simply use the generic name element.

If you need to be sure that the element you are looking for is a specific kind of element, you can constrain the search by using common Toffee element names. For a list of valid Toffee element names, and their HTML equivalents, see Understanding Toffee Element Names.

Addresses

Toffee recognizes the following addresses:

  • By label - Uses the labelled or textual content of an element to locate it. This is the most readable form of address.
  • By id attribute - Uses the id attribute of an element to locate it. This is the fastest addressing type.
  • By name attribute  - Uses the name attribute of an element.
  • By XPath expression - Uses the an XPath query to find an element. This is the most flexible and powerful addressing type, but also the slowest.
  • By CSS selector - Uses a CSS selector to find an element. This is also very flexible and powerful, but not particularly performant.
  • By table coordinates - Uses a Toffee-specific locator expression to locate an element within a table cell. Useful for building readable scripts when working with tabular data in a true HTML <table> element.

All locators must return one and exactly one element on the current page, else the command that contains them will fail.

By Label

Input elements can also have a label attached to them in a variety of different ways. The most common way is to use the "for" attribute of a "label" tag, like this:

<label for="textboxId">First Name:</label>
<input type="text" id="textboxId" />

Another way to label an element is to set its value. In the case of a "button" tag, this is the inner text, and the same applies for a hyperlink. In an "input" tag, its value is in the "value" attribute.

<button>Click Here</button>
<a href="index.html">This is a link.</a>
<input type="button" value="Button Text" />

To look up an element by label, simply use the element's type, followed by the label you are looking for. To click on an element from the previous examples, use these Toffee commands:

click textbox "First Name:"
click button "Click Here"
click link "This is a link."
click button "Button Text"

By id Attribute

In many cases, elements on the page you are testing are assigned an id attribute:

 <input type="button" id="btnFirstName" value="Click Here" />

Good practice for web developers is to ensure that the assigned id attribute is unique on the current page (though this is not always the case). To locate an element by id, use the command "with id" followed by the id to look for. To click the button in the example above, use the following Toffee command.

click button with id "btnFirstName"

ID attribute locators are the fastest kind of locators. This is especially important if the page you're testing is very large.

By name Attribute

Input elements can also have a name associated with them, defined like:

 <input type="button" name="btnLastName" value="Click Here" />

To locate an element by name, type "with name" followed by the name to look for. For example, to click a button with a name of "buttonName", type:

click button with name "btnLastName"

By XPath Query

A more advanced and direct way to address an element is via XPath, the XML Path Language. XPath location queries can be used by typing "element at xpath" followed by the XPath query expression. These are very powerful, e.g., for clicking the <span> "Clear" that shares a <div> element with an <h4> heading 'Your order':

click element at xpath "//div[h4[text()='Your order']]/span[text()='Clear']"

XPath query addresses trade expressive power for performance. They tend also to break whenever the page is rearranged in the slightest way. We strongly recommend using aliases to shield your scripts from the brittleness inherent in both XPath query and CSS selector addresses.


  • For an introduction to XPath syntax, visit W3Schools XPath Tutorial.
  • To execute XPath expressions right in Google Chrome, try XPath Helper.
  • In Firefox and Chrome, you can evaluate XPath expressions in the "inspect element" console

By CSS Selector

Locate an Element by CSS Selector

CSS selectors provide another advanced and powerful address type. If you've ever written a CSS stylesheet before, the same rules apply here. CSS location queries can be used by typing "at selector" followed by the CSS string, like this:

click element at selector "div.someClass > button.warning"

For more information, please see the W3C's CSS Selector Reference.

By Table Coordinates

This element location strategy works best on simple tables. The table must be a true <table> element comprised of <tr> and <td> elements. You may need to use an xpath expression if you are looking for an element within a table's cell, or if you have nested tables.

For elements located in a table, a more specific means of location must be used. The syntax is:

in column (target column) of table (locator) where (row filter) 

Using column and row numbers, if they are known:

click button in column 3 of table with id "tableId" where row = 2

Using a column number and a row filter expression, where "Salary" is the name of the filter column:

click button in column 3 of table at "(//table)[1]" where "Salary" = "12,345"

Using the header name of the target column, and a compound filter expression based on multiple tables:

click button in column "Buttons" of table with id "tableId" where "First Name" = "John" and "Last Name" = "Smith"