No-code XPath Selector Builder by BugBug

There are thousands of ways for a tester to write XPath selectors and thousands of mistakes one can make. At BugBug we see such mistakes every day, when we try to help our clients create automated tests where our recorded selectors are not fully accurate. We created an interface for easy generation of XPath selectors, because it will help you work faster, reduce trial and error and avoid common pitfalls. Moreover it's a great aid for beginners!

Do note, that you may encounter "xpath expression" as a synonym of "selector". We decided to use the latter in our article.

A video showing how to make a complex XPath in 1 minute in a real use case.

Features overview

With this online XPath generator you have all essential features to create a robust selector that should work in any test case

Create XPath selectors based on tags, attributes and text content
Combine multiple conditions
Join multiple selectors into one complex traversing selector
Copy selector to clipboard with one click
Make informed decisions by contextual tips
Learn basic information about selectors and HTML for beginner QA engineers

Why write selectors without code?

Here are some benefits of using our no-code tool:

You will make less mistakes
You don't need to pay attention to every single character - no more counting the brackets
You will use the best XPath practices out of the box
You can make conscious decisions based on our contextual recommendations
You will work faster
Easy for people who are mostly using no-code tools such as BugBug

About the authors

This no-code selector generator tool is brought to you by BugBug Team for free. We are the developers of an easy automation testing tool, and our users would certainly benefit from being able to writing selectors without code. But this tool can also help you if you write Selenium or Cypress tests.

QUICK START

Intro to XPath selectors for beginners

Why use XPath selectors?

If you visited this page, you are probably working on automation testing. One of the XPath functions is to help in writing automated end-to-end UI tests. When writing tests you need to specify a test step, for example "Click the submit button". But computers are not intelligent so they don't know what is a submit button. You need to specify it. And you need to be very specific, there should be just one button in the HTML that matches your criteria. Such criteria are called "selectors" or "locators".

XPath selectors are compex beasts. But very often they are the only way of creating a reliable automation testing. The XPath technology has been created in ancient times, when XML databases where popular. It has been developed for querying a database and complex sets of data, and not for test automation. 🤦

Before we explain how to understand XPath selectors, let's take a look at some basic of HTML - you need to know the fundamental terminology to work with selectors.

What is an HTML element tag?

Tags is the type of HTML element like "div". Below you can see an example HTML element with its tagged annotated.

Tags often describe the function of the element on your page.
Some tags are purely descriptive, some add special functionality for the element on page (like inputs, checkobxes, etc.).

Most common tags are:
div, span, footer, nav - usually static elements, no special function
td, th, tr - tags for HTML tables
href - for links
li, ol, ul - bullets list or numbered lists
input, textarea, select- for text input fields, radio buttons, checkboxes
form, label, name- tags used inside HTML forms, sometimes have special functions (for example clicking the label also ticks the checkbox)
img, video, svg- for media files, videos, images
‍

What is an HTML attribute?

An attribute is an additional parameter in the HTML code that is not visible to the end-user.

Here are some common attributes and our tips if they are a good selector:
class - typically used for styling with CSS, many items can have the same class
id - unique attribute for specific element, in theory there should be no two elements with the same id (but that's not always true)
src - usually for some media source, like image file
aria-label - used for accessibility and screen-readers, but also can make quite good selectors for test automation
data-testid - special selector that is dedicated to test automation, needs to be implemented by a developer
There are hundreds more!

What are parents, children & siblings?

HTML documents have a hierarchical structure. It's similar folders and files. Elements can be nested inside other elements on your web page. If an element is inside another, it's called a child. The upper-level element is a parent. Elements on the same level are called siblings.

Another terminology is ancestors or descendants - see the image below

How to read XPath selectors?

Here's an example of the simplest XPath selector.
//div
It means: Find any "div" element.
This selector is not very specific as it will find hundreds of elements on your page.

You can add additional filters to your selectors in square brackets.
//div[3]
It means: Find element with tag "div" that is third
This selector is based on order of elements and is not a good selector for test automation. If your app changes, for example, developers add another div in the HTML structure, such selectors will stop working.
‍
You can add filters to your selectors that are based on other HTML attributes.
//div[@id="submit-button"]
It means: Find any element with tag "div" that has an attribute "id" with value "submit-button.
‍
You can have more than one filters if you add more square brackets. You can also filter elements by text content.
//div[@id="submit-button"][contains(text(), "Sign in")]

It means: Find any element with tag "div" that has an attribute "id" with value "submit-button" and contains text "Sign in"

If you see a slash / in the middle of the selector, it means that this selector is a combination of several smaller selectors, each of them can have its own filters.
//div[@id="submit-button"][contains(text(), "Sign in")]/div[@id="arrow"]
It means: Find any element with tag "div" that has an attribute "id" with value "submit-button and contains text "Sign in", then inside this element find another div that has attribute "id" with value "arrow".
The above example first looks for an element matching this selector //div[@id="submit-button"][contains(text(), "Sign in")]
and then looks for another element inside the previously found element with selector /div[@id="arrow"]

By default, after a / character, XPath is looking inside the element, but you can add special operators that allow you to traverse to parent elements or siblings. The operators are for example ancestor:: , descendant:: or ::sibling
//div[@id="submit-button"][contains(text(), "Sign in")]/sibling::div[@id="arrow"]
It means: Find any element with tag "div" that has an attribute "id" with value "submit-button and contains text "Sign in", then find sibling of this element that has attribute "id" with value "arrow".
‍
Read more below to learn what are parents, children, ancestors, descendants, siblings, etc.

TIPS ON SELECTORS

How to create reliable XPath selectors for test automation?

What makes a good selector?

A good selector for automation testing is:

specific - it only points to one element
resilient to changes - when your app interface changes the selector still matches the correct element
easy to edit - when your app changes, you can update the selector without lots of debugging

Here's a secret: you don't need to know all XPath features to create robust selectors. You just need 2-3 techniques that allow you to create automated test for any use case.

Why XPath and not CSS selectors?

Another popular way of writing selectors for test automation are CSS selectors. But they have one drawback - you can't traverse the HTML document to parents (elements higher in the hierarchy). With XPath locators you can combine them and jump from a child element to a parent, then to a child again. This is not possible with CSS!

When to use tags in selectors?

Selectors based on tags are not very specific. There might be hundreds of "divs" in your HTML document.

Use tags when:

you want to find a specific form element like checkbox, select, input, textarea
you've already narrowed down the selector and you just want to find a specific children, for example a span in a specific div //div[@id="submit-button"]/span
‍‍

In other situations we recommend that you leave this set to "any" and specify the selector by attribute or text content.

Should I use attributes for selectors?

It depends.

‍Use attributes when:

your developers added special data-testid attributes to your app
your app is multi-language and you want to test different languages
the HTML element doesn't have text, for example it's a checkbox

Don't use attributes when:

the attribute is not unique, there are other HTML elements with the same attribute
the attribute is random value, for example a random class name class="34yfhfg" or a random ID is added to the element with each deployment‍‍

Should I use "text contains" for selectors?

It depends.

Use text content for selector when:

there is no other way to specify the element via attributes
the text is surely unique, for example you are looking for a specific surname,
the text is unique in the given context, for example on the login screen there is probably just one button with a label "Forgot password?"

Don't use text content when:

the text is quite generic, for example "Next" button in the wizard will appear on each step, so your selector can accidentally point to a previous or next step
the text is dynamic, for example it contains a date that changes every time your run an automated test‍‍

Should I use a combination of attributes and text content?

Yes, this is usually the best solution and makes your selectors more robust and resilient to changes.
‍

Problem solving

Common problems with selectors and how to solve them

How to create good selectors for apps with tables and interactive lists?

Here's a typical problem to solve: you have an app with list of orders in a table. Each row has a checkbox in it. You want to create a test automation that clicks the checkbox in the second row.

The above example comes from an open-source demo app

The problem is that there is no way to write a unique selector directly to this checkbox. There are more checkboxes on the list and we don't want to rely on the order of elements. We don't want the second checkbox, we want a specific checkbox.‍

There is nothing unique in the HTML element itself. Wait, is that class attribute unique? It is, but it's not good for test automation selectors. It's a random string that changes with every app deployment. ‍

XPath traversing comes to the rescue!
We will guide you step by step how to create a reliable selector, that first identifies the right row in the table and then finds the checkbox inside. The result selector will "traverse" the parents and children in 3 steps.

1. Find a specific text in the table

2. Find the parent table row by searching ancestors of the element from step 1

3. Find the checkbox inside the row

Here's how to do this with our no-code tool. You need to use "Then find..." button and connect these 3 steps into one sophisticated and powerful XPath selector
//*[contains(text(), "KYDGHM") ]/ancestor::tr/descendant::input[@type="checkbox"]

You can apply the same technique to multiple other test cases:

Capitalisation of selectors values matters

Make sure your selector uses the same capitalisation of characters as in the page. Pay attention to uppercase and lowercase letters! Ideally copy-paste the text from HTML via Chrome developer tools.

My selector works on desktop but doesn't work on mobile. Why?

Your app may have 2 different button "duplicates", one dedicated for desktop and one for mobile. One is always hidden, depending on the window width.

In such situation, the best solution is to create 2 separate tests for mobile and desktop with 2 different selectors.

Or try refactoring the code so that there is only one button present at a time - not hiding, but removing the button from the document.

You can also try to write a clunky selector that matches the 2 buttons, but somehow remove the hidden button with the not operator, for example
//button[contains(text(), "Example") and not(ancestor::div[contains(@style, 'display:none')]) and not(ancestor::div[contains(@style, 'display:none')])]

How to check if your selector works in Chrome?

In the above example we created a selector, now we should check if it works.

Open this demo app and login with "demo / demo", then go to "Orders" tab
Open Chrome developer tools
Click Ctrl+F to open the "Find" box (Cmd+F on Mac)
Paste the selector
Click enter
The matching element will be higlighted
Click enter several times to make sure that this is the only element that has a match

Here's a quick video that shows the whole XPath selector verification process in Chrome