selenium.webdriver.support.relative_locator#

Functions

`locate_with`(by, using)	Start searching for relative objects your search criteria with By.
`with_tag_name`(tag_name)	Start searching for relative objects using a tag name.

Classes

RelativeBy([root, filters])

Find elements based on their relative location from a root element.

with_tag_name(tag_name)[source]#

Start searching for relative objects using a tag name.

Parameters:: tag_name (str) – The DOM tag of element to start searching.
Returns:: Use this object to create filters within a find_elements call.
Return type:: RelativeBy
Raises:: WebDriverException – If tag_name is None.

Note

This method is deprecated and may be removed in future versions. Please use locate_with instead.

locate_with(by, using)[source]#

Start searching for relative objects your search criteria with By.

Parameters:

by (Literal['id', 'xpath', 'link text', 'partial link text', 'name', 'tag name', 'class name', 'css selector']) – The method to find the element.
using (str) – The value from By passed in.

Returns:

Use this object to create filters within a find_elements call.

Return type:

RelativeBy

Example

>>> lowest = driver.find_element(By.ID, "below")
>>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))

class RelativeBy(root=None, filters=None)[source]#

Bases: object

Find elements based on their relative location from a root element.

It is recommended that you use the helper function to create instances.

Example:#

>>> lowest = driver.find_element(By.ID, "below")
>>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))
>>> ids = [el.get_attribute("id") for el in elements]
>>> assert "above" in ids
>>> assert "mid" in ids

Create a RelativeBy object (prefer using locate_with instead).

param root:: A dict with By enum as the key and the search query as the value
param filters:: A list of the filters that will be searched. If none are passed in please use the fluent API on the object to create the filters

LocatorType#: alias of dict[Literal[‘id’, ‘xpath’, ‘link text’, ‘partial link text’, ‘name’, ‘tag name’, ‘class name’, ‘css selector’], str]

above(element_or_locator: WebElement | LocatorType) → RelativeBy[source]#

above(element_or_locator: None = None) → NoReturn

Add a filter to look for elements above.

Parameters:: element_or_locator – Element to look above
Returns:: RelativeBy
Raises:: WebDriverException – If element_or_locator is None.

Example:#

>>> lowest = driver.find_element(By.ID, "below")
>>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").above(lowest))

below(element_or_locator: WebElement | LocatorType) → RelativeBy[source]#

below(element_or_locator: None = None) → NoReturn

Add a filter to look for elements below.

Parameters:: element_or_locator – Element to look below
Returns:: RelativeBy
Raises:: WebDriverException – If element_or_locator is None.

Example

>>> highest = driver.find_element(By.ID, "high")
>>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").below(highest))

to_left_of(element_or_locator: WebElement | LocatorType) → RelativeBy[source]#

to_left_of(element_or_locator: None = None) → NoReturn

Add a filter to look for elements to the left of.

Parameters:: element_or_locator – Element to look to the left of
Returns:: RelativeBy
Raises:: WebDriverException – If element_or_locator is None.

Example

>>> right = driver.find_element(By.ID, "right")
>>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").to_left_of(right))

to_right_of(element_or_locator: WebElement | LocatorType) → RelativeBy[source]#

to_right_of(element_or_locator: None = None) → NoReturn

Add a filter to look for elements right of.

Parameters:: element_or_locator – Element to look right of
Returns:: RelativeBy
Raises:: WebDriverException – If element_or_locator is None.

Example

>>> left = driver.find_element(By.ID, "left")
>>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").to_right_of(left))

straight_above(element_or_locator: WebElement | LocatorType) → RelativeBy[source]#

straight_above(element_or_locator: None = None) → NoReturn

Add a filter to look for elements above.

Parameters:: element_or_locator – Element to look above

straight_below(element_or_locator: WebElement | LocatorType) → RelativeBy[source]#

straight_below(element_or_locator: None = None) → NoReturn

Add a filter to look for elements below.

Parameters:: element_or_locator – Element to look below

straight_left_of(element_or_locator: WebElement | LocatorType) → RelativeBy[source]#

straight_left_of(element_or_locator: None = None) → NoReturn

Add a filter to look for elements to the left of.

Parameters:: element_or_locator – Element to look to the left of

straight_right_of(element_or_locator: WebElement | LocatorType) → RelativeBy[source]#

straight_right_of(element_or_locator: None = None) → NoReturn

Add a filter to look for elements right of.

Parameters:: element_or_locator – Element to look right of

near(element_or_locator: WebElement | LocatorType, distance: int = 50) → RelativeBy[source]#

near(element_or_locator: None = None, distance: int = 50) → NoReturn

Add a filter to look for elements near.

Parameters:

element_or_locator – Element to look near by the element or within a distance
distance – Distance in pixel

Returns:

RelativeBy

Raises:

WebDriverException – If element_or_locator is None
WebDriverException – If distance is less than or equal to 0.

Example

>>> near = driver.find_element(By.ID, "near")
>>> elements = driver.find_elements(locate_with(By.CSS_SELECTOR, "p").near(near, 50))

to_dict()[source]#

Create a dict to be passed to the driver for element searching.

Return type:: dict

Parameters:

root (dict[Literal['id', 'xpath', 'link text', 'partial link text', 'name', 'tag name', 'class name', 'css selector'], str] | None)
filters (list | None)