Relative Locators
Selenium 4 introduces Relative Locators. These locators are helpful when it is not easy to construct a locator for the desired element, but easy to describe spatially where the element is in relation to an element that does have an easily constructed locator. You can get more details about them here. To simplify the work with relative locators, aquality.selenium.locators package has been added to the aquality-selenium framework. The main functionality is implemented in the RelativeBy wrapper of this package. The following examples demonstrate the functionality of this class.
Tests can be found in the test.integration.LocatorTests class. All tests work with this page. A fragment of the page is presented below (searched elements are in red frames).
Using the above, below, toLeft, toRight methods of the RelativeBy class, a locator can be defined for an element that is above, below, to the left, or to the right of an element with an already defined locator. Below is a fragment of this class with an overloaded method above, the approach for the other three methods is similar.
The locator of the searched element (By) is used as a constructor parameter. An element that has an easily constructible locator is passed to the overloaded method. An element can be:
WebElement (2);
Locator By (1);
Wrapper element that implements the interface IElement (3).
Test methods testAboveLocatorWithDifferentAboveParametersType, testBelowLocatorWithDifferentBelowParametersType, testToLeftOfLocatorWithDifferentToLeftOfParametersType, testToRightOfLocatorWithDifferentToRightOfParametersType demonstrates the usage of relative locators. Let's take testAboveLocatorWithDifferentAboveParametersType as an example.
The search is carried out relative to the cell on the 5th row of the 5th column (cellInRow5Column5), the cell labelLocatorCell table is searched for by xPath (//td). The test shows all use cases of the above method, and (4) shows an example of working with a relative locator without using the RelativeBy wrapper, only using Selenium 4 tools.
Relative locators can be used in call chains and allows to define such locators as: an element with a
tag above some X element and below some Y element. The testAboveBelowLeftRightWithDifferentParametersType test shows examples of relative locators combinations.
Here, a table cell (//td) is searched for on the 5th line of the 5th column according to the following conditions:
Above the cell on line 7 in column 5; Below the cell on line 3 in column 5; To the right of the cell on line 5 in column 3; To the left of the cell on line 5 in column 7; Above the cell on line 7 in column 5 (repeating the above method is necessary in this case, otherwise the result will be a cell to the left of the cell on line 5 in column 7).
Using the near method, you can find an element within a certain radius from the given element (by default, this radius is 50px and can be adjusted). All variants of this method are presented below.
The signature and usage of the method is almost the same as the previous methods of the RelativeBy class. The only difference is the second parameter (atMostDistanceInPixels) that specifies the maximum search distance.
Below is the testNearWithDifferentNearParameterType test, which demonstrates how the near method works with the default search distance.
Table cell (labelLocatorCell=//td) is searched here near the cell on the 1st first row of the 1st column. The nearest cell is on the 2nd row of the 1st column.
The search radius can be set as the second parameter of the near method. The testNearWithDistanceWithDifferentParametersType test below demonstrates the use of the near method with an arbitrary search distance.
The element with xPath = "//h3[contains(text(),'Challenging DOM')]" is searched within distanceToFindElementWithPositiveResult = 300px. This element is the Challenging DOM header itself.