1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
# Licensed to the Software Freedom Conservancy (SFC) under one
# or more contributor license agreements. See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership. The SFC licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License. You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied. See the License for the
# specific language governing permissions and limitations
# under the License.
from typing import Dict
from typing import List
from typing import NoReturn
from typing import Optional
from typing import Union
from typing import overload
from selenium.common.exceptions import WebDriverException
from selenium.webdriver.common.by import By
from selenium.webdriver.common.by import ByType
from selenium.webdriver.remote.webelement import WebElement
def with_tag_name(tag_name: str) -> "RelativeBy":
"""Start searching for relative objects using a tag name.
Note: This method may be removed in future versions, please use
`locate_with` instead.
:Args:
- tag_name: the DOM tag of element to start searching.
:Returns:
- RelativeBy - use this object to create filters within a
`find_elements` call.
"""
if not tag_name:
raise WebDriverException("tag_name can not be null")
return RelativeBy({By.CSS_SELECTOR: tag_name})
def locate_with(by: ByType, using: str) -> "RelativeBy":
"""Start searching for relative objects your search criteria with By.
:Args:
- by: The value from `By` passed in.
- using: search term to find the element with.
:Returns:
- RelativeBy - use this object to create filters within a
`find_elements` call.
"""
assert by is not None, "Please pass in a by argument"
assert using is not None, "Please pass in a using argument"
return RelativeBy({by: using})
class RelativeBy:
"""Gives the opportunity to find elements based on their relative location
on the page from a root elelemt. It is recommended that you use the helper
function to create it.
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
"""
LocatorType = Dict[ByType, str]
def __init__(self, root: Optional[Dict[ByType, str]] = None, filters: Optional[List] = None):
"""Creates a new RelativeBy object. It is preferred if you use the
`locate_with` method as this signature could change.
:Args:
root - A dict with `By` enum as the key and the search query as the value
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
"""
self.root = root
self.filters = filters or []
@overload
def above(self, element_or_locator: Union[WebElement, LocatorType]) -> "RelativeBy": ...
@overload
def above(self, element_or_locator: None = None) -> "NoReturn": ...
def above(self, element_or_locator: Union[WebElement, LocatorType, None] = None) -> "RelativeBy":
"""Add a filter to look for elements above.
:Args:
- element_or_locator: Element to look above
"""
if not element_or_locator:
raise WebDriverException("Element or locator must be given when calling above method")
self.filters.append({"kind": "above", "args": [element_or_locator]})
return self
@overload
def below(self, element_or_locator: Union[WebElement, LocatorType]) -> "RelativeBy": ...
@overload
def below(self, element_or_locator: None = None) -> "NoReturn": ...
def below(self, element_or_locator: Union[WebElement, Dict, None] = None) -> "RelativeBy":
"""Add a filter to look for elements below.
:Args:
- element_or_locator: Element to look below
"""
if not element_or_locator:
raise WebDriverException("Element or locator must be given when calling below method")
self.filters.append({"kind": "below", "args": [element_or_locator]})
return self
@overload
def to_left_of(self, element_or_locator: Union[WebElement, LocatorType]) -> "RelativeBy": ...
@overload
def to_left_of(self, element_or_locator: None = None) -> "NoReturn": ...
def to_left_of(self, element_or_locator: Union[WebElement, Dict, None] = None) -> "RelativeBy":
"""Add a filter to look for elements to the left of.
:Args:
- element_or_locator: Element to look to the left of
"""
if not element_or_locator:
raise WebDriverException("Element or locator must be given when calling to_left_of method")
self.filters.append({"kind": "left", "args": [element_or_locator]})
return self
@overload
def to_right_of(self, element_or_locator: Union[WebElement, LocatorType]) -> "RelativeBy": ...
@overload
def to_right_of(self, element_or_locator: None = None) -> "NoReturn": ...
def to_right_of(self, element_or_locator: Union[WebElement, Dict, None] = None) -> "RelativeBy":
"""Add a filter to look for elements right of.
:Args:
- element_or_locator: Element to look right of
"""
if not element_or_locator:
raise WebDriverException("Element or locator must be given when calling to_right_of method")
self.filters.append({"kind": "right", "args": [element_or_locator]})
return self
@overload
def near(self, element_or_locator: Union[WebElement, LocatorType], distance: int = 50) -> "RelativeBy": ...
@overload
def near(self, element_or_locator: None = None, distance: int = 50) -> "NoReturn": ...
def near(self, element_or_locator: Union[WebElement, LocatorType, None] = None, distance: int = 50) -> "RelativeBy":
"""Add a filter to look for elements near.
:Args:
- element_or_locator: Element to look near by the element or within a distance
- distance: distance in pixel
"""
if not element_or_locator:
raise WebDriverException("Element or locator must be given when calling near method")
if distance <= 0:
raise WebDriverException("Distance must be positive")
self.filters.append({"kind": "near", "args": [element_or_locator, distance]})
return self
def to_dict(self) -> Dict:
"""Create a dict that will be passed to the driver to start searching
for the element."""
return {
"relative": {
"root": self.root,
"filters": self.filters,
}
}
|
