Back to Resources

Blog

Posted April 1, 2023

Selenium 4 - Relative Locators

Selenium 4 offers a way of locating elements by using natural language terms. This article describes how to use the new Relative Locators.

This functionality brings a new way to locate elements to help you find the ones that are nearby other elements. The available locators are:

above below toLeftOf toRightOf near

The concept behind this method is to allow you to find elements based on how one would describe them on a page. It is more natural to say: “find the element that is below the image”, rather than “find the INPUT inside the DIV with the ‘id’ of ‘main’”. In general, you could think about them as a way to locate elements based on the visual placement on the page.

For additional examples, including chaining relative locators in these languages, look at our Selenium 4 Documentation.

We will use the following login form to understand how Relative Locators work:

Above

We would like to find the email address field, which is above the password field. To do that, we find the password field through its id, and then we use the above relative locator.

1
Java
2
3
import static org.openqa.selenium.support.locators.RelativeLocator.with;
4
WebElement password = driver.findElement(By.id("password"));
5
WebElement email = driver.findElement(with(By.tagName("input")).above(passwordField));
6
7
Python
8
9
from selenium.webdriver.common.by import By
10
from selenium.webdriver.support.relative_locator import locate_with
11
passwordField = driver.find_element(By.ID, "password")
12
emailAddressField = driver.find_element(locate_with(By.TAG_NAME, "input").above(passwordField))
13
14
C#
15
16
using static OpenQA.Selenium.RelativeBy;
17
IWebElement passwordField = driver.FindElement(By.Id("password"));
18
IWebElement emailAddressField = driver.FindElement(RelativeBy(By.TagName("input")).Above(passwordField));
19
20
Ruby
21
22
password_field= driver.find_element(:id, "password")
23
email_address_field = driver.find_element(relative: {tag_name: "input", above:password_field})
24
25
JavaScript
26
27
let passwordField = driver.findElement(By.id('password'));
28
let emailAddressField = await driver.findElement(locateWith(By.tagName('input')).above(passwordField));
29

Below

Going the other way around, let's find the password field, which is below the email address field.

1
Java
2
import static org.openqa.selenium.support.locators.RelativeLocator.with;
3
WebElement emailAddressField = driver.findElement(By.id("email"));
4
WebElement passwordField = driver.findElement(with(By.tagName("input"))
5
.below(emailAddressField));
6
7
Python
8
9
from selenium.webdriver.common.by import By
10
from selenium.webdriver.support.relative_locator import locate_with
11
emailAddressField = driver.find_element(By.ID, "email")
12
passwordField = driver.find_element(locate_with(By.TAG_NAME, "input").below(emailAddressField))
13
14
C#
15
16
using static OpenQA.Selenium.RelativeBy;
17
IWebElement emailAddressField = driver.FindElement(By.Id("email"));
18
IWebElement passwordField =
19
driver.FindElement(RelativeBy(By.TagName("input")).Below(emailAddressField));
20
21
Ruby
22
23
email_address_field = driver.find_element(:id, "email")
24
password_field = driver.find_element(relative: {tag_name: "input", below: email_address_field})
25
26
JavaScript
27
28
let emailAddressField = driver.findElement(By.id('email'));
29
let passwordField = await driver.findElement(locateWith(By.tagName('input')).below(emailAddressField));
30

To the Left Of

Let’s consider the case where we want to find the element on the left side of the “Submit” button.

1
Java
2
3
import static org.openqa.selenium.support.locators.RelativeLocator.with;
4
WebElement submitButton = driver.findElement(By.id("submit"));
5
WebElement cancelButton = driver.findElement(with(By.tagName("button"))
6
.toLeftOf(submitButton));
7
8
Python
9
10
from selenium.webdriver.common.by import By
11
from selenium.webdriver.support.relative_locator import locate_with
12
submitButton = driver.find_element(By.ID, "submit")
13
cancelButton = driver.find_element(locate_with(By.TAG_NAME, "button").
14
to_left_of(submitButton))
15
16
C#
17
18
using static OpenQA.Selenium.RelativeBy;
19
IWebElement emailAddressField = driver.FindElement(By.Id("email"));
20
IWebElement passwordField =
21
driver.FindElement(RelativeBy(By.TagName("input")).Below(emailAddressField));
22
23
Ruby
24
25
submit_button= driver.find_element(:id, "submit")
26
cancel_button = driver.find_element(relative: {tag_name: 'button', left:submit_button})
27
28
JavaScript
29
30
let submitButton = driver.findElement(By.id('submit'));
31
let cancelButton = await driver.findElement(locateWith(By.tagName('button')).toLeftOf(submitButton));
32

To the Right Of

Now we'll consider the opposite case, where we want to find the element on the right side of the “Cancel” button.

1
Java
2
3
import static org.openqa.selenium.support.locators.RelativeLocator.with;
4
WebElement cancelButton = driver.findElement(By.id("cancel"));
5
WebElement submitButton = driver.findElement(with(By.tagName("button")).toRightOf(cancelButton));
6
7
Python
8
9
from selenium.webdriver.common.by import By
10
from selenium.webdriver.support.relative_locator import locate_with
11
cancelButton = driver.find_element(By.ID, "cancel")
12
submitButton = driver.find_element(locate_with(By.TAG_NAME, "button").
13
to_right_of(cancelButton))
14
15
C#
16
17
using static OpenQA.Selenium.RelativeBy;
18
IWebElement cancelButton = driver.FindElement(By.Id("cancel"));
19
IWebElement submitButton = driver.FindElement(RelativeBy(By.TagName("button")).RightOf(cancelButton));
20
21
Ruby
22
23
cancel_button = driver.find_element(:id, "cancel")
24
submit_button = driver.find_element(relative: {tag_name: 'button', right:cancel_button})
25
26
JavaScript
27
28
let cancelButton = driver.findElement(By.id('cancel'));
29
let submitButton = await driver.findElement(locateWith(By.tagName('button')).toRightOf(cancelButton));
30

Near

near is helpful when we need to find an element that is at most 50px away from the specified element. In this case, we would like to find the email address field by first finding the label of that field.

1
Java
2
3
import static org.openqa.selenium.support.locators.RelativeLocator.with;
4
WebElement emailAddressLabel = driver.findElement(By.id("lbl-email"));
5
WebElement emailAddressField = driver.findElement(with(By.tagName("input")).near(emailAddressLabel));
6
7
Python
8
9
from selenium.webdriver.common.by import By
10
from selenium.webdriver.support.relative_locator import locate_with
11
emailAddressLabel = driver.find_element(By.ID, "lbl-email")
12
emailAddressField = driver.find_element(locate_with(By.TAG_NAME, "input").
13
near(emailAddressLabel))
14
15
C#
16
17
using static OpenQA.Selenium.RelativeBy;
18
IWebElement emailAddressLabel = driver.FindElement(By.Id("lbl-email"));
19
IWebElement emailAddressField = driver.FindElement(RelativeBy(By.TagName("input")).Near(emailAddressLabel));
20
21
Ruby
22
23
email_address_label = driver.find_element(:id, "lbl-email")
24
email_address_field = driver.find_element(relative: {tag_name: 'input', near: email_address_label})
25
26
JavaScript
27
28
let emailAddressLabel = driver.findElement(By.id("lbl-email"));
29
let emailAddressField = await driver.findElement(with(By.tagName("input")).near(emailAddressLabel));
30

An updated set of methods, utilities and examples can be found at the official documentation.

Check out our comprehensive guide to Selenium 4 for more information.

Titus Fortner
Sr. Developer Experience Engineer, Sauce Labs
Diego Molina
Staff Software Engineer at Sauce Labs
Published:
Apr 1, 2023
Share this post
Copy Share Link

Ready to start testing with Selenium and Sauce Labs?

Let's go!

© 2023 Sauce Labs Inc., all rights reserved. SAUCE and SAUCE LABS are registered trademarks owned by Sauce Labs Inc. in the United States, EU, and may be registered in other jurisdictions.