Beginner's Guide to XPath

Follow this guide to learn the basics of XPath selectors, what they are made of and how to use them

XPath Syntax Cheat Sheet

• / - selects from the root node (absolute path)

• // - selects from the specified node (relative path)

• element - selects all elements with the given tag name

• [predicate] - adds a condition to selection filter

• @attribute="value" - selects the value of the specified attribute

• text()="value" - selects the text within an element

• position()="index" - selects the element by its position among siblings

Chaining predicates

• //*[@attribute1="value"][@attribute2="value"]

• //*[@attribute1="value" and @attribute2="value"]

Selecting position

Both expressions below select an img element that is the 2nd child of div:

• //div/img[position()="2"]

• //div/img[2]

String vs substring search algorithms

• //*[@class="className"] - searches for exact match

• //*[contains(@class, "className")] - searches for partial match

Why use XPath

Knowing the basics of this versatile tool is almost a must in automated testing. Ideally, the most reliable tests are built with the use of IDs or test-IDs. In reality though there are a lot of web sites that don't utilize IDs, forcing us to use other attributes to find elements. You may also encounter cases where, as a part of your test, you need to check on certain properties of an element, like position, text content or a state of being disabled, for example. That's when XPath and CSS selectors need to be explored for writing locator expressions.

What is XPath

XPath, or XML Path, is a syntax expression language with its own functions and operators, that uses path expressions to select nodes or node-sets in an XML or HTML document. It is wide spread across many programming languages and testing frameworks. XPath implementations are complete in Chrome, Firefox and Edge, so XPath locators work well for cross-browser testing and can be validated right in the browser devtools.

Here's what a typical XPath selector looks like:

This one targets a button that has a data-testid attribute with a value of "sign-in-btn".

How to use XPath

XPath selectors are really easy to use once you get to know how to construct them. To begin, let's take a look at the basic XPath syntax (parts in bold cannot be omitted from selector):

• current node selector (/ or //)

• element (tag name)

• [predicate]

• @attribute ="value"

• function()="value"

The most common type of a path expression in testing

Not every path expression will have all of these pieces in it. The look of a selector and how specific it is often depends on the context and the goal. There's always a slash or a double-slash, tag name also cannot be omitted, but it can be replaced with an asterisk symbol *, indicating that any tag name will match.

Omitting current node selector is the same as using a single slash /.

---

Absolute vs Relative XPath selectors

XPaths can be absolute / and relative //

• absolute / XPath expressions start from the root of the HTML document and specify the complete path to the targeted element. It is recommend to avoid using absolute paths as they are vulnerable to page structure changes. Furthermore such tests are harder to read and maintain.

Absolute XPaths often look like this

• relative // XPath expressions start from a specified element and navigate the DOM hierarchy to locate the targeted element. Such expressions are shorter, more reliable and readable. Here's an example with the same button as before, but instead of targeting it by specifying the complete path, we have located the button by specifying its tag name and ID attribute:

Relative XPath of the same button as above

---

Predicates

Predicates are used to find a specific node or a node that contains a specific value. In other words they are extra conditions added to selector to make it more specific, hence more precise. Predicates are always enclosed in square brackets [ ] and they cannot be used by themselves - there always have to be a current node selector and a tag name. Inside the brackets, there's usually an attribute and/or a function and a value.

Here are some typical examples:

Path expression	Result
//input[@placeholder="Enter your Email"]	selects an input element, anywhere on the page, that has a placeholder attribute with a value of "Enter your Email"
//div/button[@data-testid="save-changes"]	selects a button element that is a child of a div and has a data-testid attribute with a value of "save-changes"
//*[@for="tos-checkbox"]	selects an element, regardless of its tag name, that has a for attribute with a value of "tos-checkbox"

If you need to specify multiple predicates, there are two ways to go about it:

• chaining predicates separately, enclosing each one in square brackets //*[@id="accept"][@type="checkbox"]

• using and operator inside single square brackets //*[@id="accept" and @type="checkbox"]

---

Selecting position

Using the DOM hierarchy position of elements to make locators more specific can be very useful in certain scenarios. There are two ways you can select an element by its position in relation to its parent element (indexation starts from 1):

• using its index in separate square brackets [2]

• using the function [position()="2"]

Here are some examples with selectors utilizing both position and other attributes:

Path expression	Result
//img[@alt="logo"][2]	selects an img element that has an alt attribute with a value of "logo" and is the second child of an unspecified element
//tr/td[position()="3" and text()="Savings"]	selects a td element that has inner text "Savings" and is the third child of the tr element

Keep in mind that using the index with and operator in the same brackets will produce a faulty selector, e.g.,//*[2 and @attribute]

---

Functions

There are more than 200+ functions in XPath, catoring to various usage scenarios. Due to the fact that we don't need most of them in automated testing, we are only talking here about the most useful XPath functions in everyday testing routine.

Like in many high-level programming languages, calling a function in an XPath expression involves round brackets ():

Here's a shortlist of the most useful XPath functions in testing:

Function	Description	Example
text()	returns the text content of element	//button[text()="Execute"]
position()	returns the XPath index of element	//a[position()="2"]
last()	returns the highest index of an element among its siblings	//a[last()]
contains()	searches for a substring anywhere in the value	//*[contains(@class, "btn-primary")]
starts-with()	searches for a substring at the start of the value	//*[starts-with(text(), "Hello, Wor")]
ends-with()	searches for a substring at the end of the value	//*[ends-with(text(), "llo, World!")]

Please, keep in mind that all functions are case-sensitive when matching values.

One function stands out in particular. Text() allows us to find an element by its text node aka inner text. This is a powerful tool that only XPath provides. It is particularly useful when a targeted element does not have enough attributes or unique attribute values.

Will match any element with the specified inner text

Another common function is contains(), it is used for substring searches. Let's say we only want to select a certain significant part of this text value. To do that we can use the text() and the substring we are looking for as the arguments for the contains() function.

Will match the same element as above

last() returns the highest index of an element among its siblings, a numeric value, hence it can be used as is. The expression in the figure below selects a button element that is the last child of a container element.

---

Using selectors as checks

All these tools make up for a very robust and powerful selector constructor. Apart from locating elements to interact with, XPath expressions can be used as checks and often serve as test result verification steps.

Let's take a look at this simple test of a Terms and Services checkbox. In the test we are clicking on the checkbox and want to make sure that it has been checked as a result.

The expression in Step 2 finds the checkbox element by specifying its ancestor and ID attribute. Step 4 is a verification step - after the checkbox has been clicked on, it verifies that it now has the @checked attribute.

Now that we have talked about how to use XPath, we can go ahead and discuss when to use it. Please, check out the Use Cases where we are looking into the most common scenarios.