forked from SeleniumHQ/selenium
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathWebElement.java
More file actions
338 lines (315 loc) · 13.7 KB
/
Copy pathWebElement.java
File metadata and controls
338 lines (315 loc) · 13.7 KB
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
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
// 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.
package org.openqa.selenium;
import java.util.List;
/**
* Represents an HTML element. Generally, all interesting operations to do with interacting with a
* page will be performed through this interface.
* <p>
* All method calls will do a freshness check to ensure that the element reference is still valid.
* This essentially determines whether or not the element is still attached to the DOM. If this test
* fails, then an {@link org.openqa.selenium.StaleElementReferenceException} is thrown, and all
* future calls to this instance will fail.
*/
public interface WebElement extends SearchContext, TakesScreenshot {
/**
* Click this element. If this causes a new page to load, you
* should discard all references to this element and any further
* operations performed on this element will throw a
* StaleElementReferenceException.
* <p>
* Note that if click() is done by sending a native event (which is
* the default on most browsers/platforms) then the method will
* _not_ wait for the next page to load and the caller should verify
* that themselves.
* <p>
* There are some preconditions for an element to be clicked. The
* element must be visible and it must have a height and width
* greater then 0.
* <p>
* See <a href="https://w3c.github.io/webdriver/#element-click">W3C WebDriver specification</a>
* for more details.
*
* @throws StaleElementReferenceException If the element no
* longer exists as initially defined
*/
void click();
/**
* If this current element is a form, or an element within a form, then this will be submitted to
* the remote server. If this causes the current page to change, then this method will block until
* the new page is loaded.
*
* @throws NoSuchElementException If the given element is not within a form
*/
void submit();
/**
* Use this method to simulate typing into an element, which may set its value.
* <p>
* See <a href="https://w3c.github.io/webdriver/#element-send-keys">W3C WebDriver specification</a>
* for more details.
*
* @param keysToSend character sequence to send to the element
*
* @throws IllegalArgumentException if keysToSend is null
*/
void sendKeys(CharSequence... keysToSend);
/**
* If this element is a form entry element, this will reset its value.
* <p>
* See <a href="https://w3c.github.io/webdriver/#element-clear">W3C WebDriver specification</a>
* and <a href="https://html.spec.whatwg.org/#concept-form-reset-control">HTML specification</a>
* for more details.
*/
void clear();
/**
* Get the tag name of this element. <b>Not</b> the value of the name attribute: will return
* <code>"input"</code> for the element <code><input name="foo" /></code>.
* <p>
* See <a href="https://w3c.github.io/webdriver/#get-element-tag-name">W3C WebDriver specification</a>
* for more details.
*
* @return The tag name of this element.
*/
String getTagName();
/**
* Get the value of the given property of the element. Will return the current value, even if
* this has been modified after the page has been loaded.
* <p>
* See <a href="https://w3c.github.io/webdriver/#get-element-property">W3C WebDriver specification</a>
* for more details.
*
* @param name The name of the property.
* @return The property's current value or null if the value is not set.
*/
default String getDomProperty(String name) {
throw new UnsupportedOperationException("getDomProperty");
}
/**
* Get the value of the given attribute of the element.
* <p>
* This method, unlike {@link #getAttribute(String)}, returns the value of the attribute with the
* given name but not the property with the same name.
* <p>
* The following are deemed to be "boolean" attributes, and will return either "true" or null:
* <p>
* async, autofocus, autoplay, checked, compact, complete, controls, declare, defaultchecked,
* defaultselected, defer, disabled, draggable, ended, formnovalidate, hidden, indeterminate,
* iscontenteditable, ismap, itemscope, loop, multiple, muted, nohref, noresize, noshade,
* novalidate, nowrap, open, paused, pubdate, readonly, required, reversed, scoped, seamless,
* seeking, selected, truespeed, willvalidate
* <p>
* See <a href="https://w3c.github.io/webdriver/#get-element-attribute">W3C WebDriver specification</a>
* for more details.
*
* @param name The name of the attribute.
* @return The attribute's value or null if the value is not set.
*/
default String getDomAttribute(String name) {
throw new UnsupportedOperationException("getDomAttribute");
}
/**
* Get the value of the given attribute of the element. Will return the current value, even if
* this has been modified after the page has been loaded.
* <p>
* More exactly, this method will return the value of the property with the given name, if it
* exists. If it does not, then the value of the attribute with the given name is returned. If
* neither exists, null is returned.
* <p>
* The "style" attribute is converted as best can be to a text representation with a trailing
* semi-colon.
* <p>
* The following are deemed to be "boolean" attributes, and will return either "true" or null:
* <p>
* async, autofocus, autoplay, checked, compact, complete, controls, declare, defaultchecked,
* defaultselected, defer, disabled, draggable, ended, formnovalidate, hidden, indeterminate,
* iscontenteditable, ismap, itemscope, loop, multiple, muted, nohref, noresize, noshade,
* novalidate, nowrap, open, paused, pubdate, readonly, required, reversed, scoped, seamless,
* seeking, selected, truespeed, willvalidate
* <p>
* Finally, the following commonly mis-capitalized attribute/property names are evaluated as
* expected:
* <ul>
* <li>If the given name is "class", the "className" property is returned.
* <li>If the given name is "readonly", the "readOnly" property is returned.
* </ul>
* <i>Note:</i> The reason for this behavior is that users frequently confuse attributes and
* properties. If you need to do something more precise, use {@link #getDomAttribute(String)}
* or {@link #getDomProperty(String)} to obtain the result you desire.
* <p>
* See <a href="https://w3c.github.io/webdriver/#get-element-attribute">W3C WebDriver specification</a>
* for more details.
*
* @param name The name of the attribute.
* @return The attribute/property's current value or null if the value is not set.
*/
String getAttribute(String name);
/**
* Gets result of computing the WAI-ARIA role of element.
* <p>
* See <a href="https://www.w3.org/TR/webdriver/#get-computed-role">W3C WebDriver specification</a>
* for more details.
*
* @return the WAI-ARIA role of the element.
*/
default String getAriaRole() {
throw new UnsupportedOperationException("getAriaRole");
}
/**
* Gets result of a Accessible Name and Description Computation for the Accessible Name of the element.
* <p>
* See <a href="https://www.w3.org/TR/webdriver/#get-computed-label">W3C WebDriver specification</a>
* for more details.
*
* @return the accessible name of the element.
*/
default String getAccessibleName() {
throw new UnsupportedOperationException("getAccessibleName");
}
/**
* Determine whether or not this element is selected or not. This operation only applies to input
* elements such as checkboxes, options in a select and radio buttons.
* For more information on which elements this method supports,
* refer to the <a href="https://w3c.github.io/webdriver/webdriver-spec.html#is-element-selected">specification</a>.
* <p>
* See <a href="https://w3c.github.io/webdriver/#is-element-selected">W3C WebDriver specification</a>
* for more details.
*
* @return True if the element is currently selected or checked, false otherwise.
*/
boolean isSelected();
/**
* Is the element currently enabled or not? This will generally return true for everything but
* disabled input elements.
* <p>
* See <a href="https://w3c.github.io/webdriver/#is-element-enabled">W3C WebDriver specification</a>
* for more details.
*
* @return True if the element is enabled, false otherwise.
*/
boolean isEnabled();
/**
* Get the visible (i.e. not hidden by CSS) text of this element, including sub-elements.
* <p>
* See <a href="https://w3c.github.io/webdriver/#get-element-text">W3C WebDriver specification</a>
* for more details.
*
* @return The visible text of this element.
*/
String getText();
/**
* Find all elements within the current context using the given mechanism. When using xpath be
* aware that webdriver follows standard conventions: a search prefixed with "//" will search the
* entire document, not just the children of this current node. Use ".//" to limit your search to
* the children of this WebElement.
* This method is affected by the 'implicit wait' times in force at the time of execution. When
* implicitly waiting, this method will return as soon as there are more than 0 items in the
* found collection, or will return an empty list if the timeout is reached.
* <p>
* See <a href="https://w3c.github.io/webdriver/#find-elements-from-element">W3C WebDriver specification</a>
* for more details.
*
* @param by The locating mechanism to use
* @return A list of all {@link WebElement}s, or an empty list if nothing matches.
* @see org.openqa.selenium.By
* @see org.openqa.selenium.WebDriver.Timeouts
*/
@Override
List<WebElement> findElements(By by);
/**
* Find the first {@link WebElement} using the given method. See the note in
* {@link #findElements(By)} about finding via XPath.
* This method is affected by the 'implicit wait' times in force at the time of execution.
* The findElement(..) invocation will return a matching row, or try again repeatedly until
* the configured timeout is reached.
* <p>
* findElement should not be used to look for non-present elements, use {@link #findElements(By)}
* and assert zero length response instead.
* <p>
* See <a href="https://w3c.github.io/webdriver/#find-element-from-element">W3C WebDriver specification</a>
* for more details.
*
* @param by The locating mechanism
* @return The first matching element on the current context.
* @throws NoSuchElementException If no matching elements are found
* @see org.openqa.selenium.By
* @see org.openqa.selenium.WebDriver.Timeouts
*/
@Override
WebElement findElement(By by);
/**
* @return A representation of an element's shadow root for accessing the shadow DOM of a web component.
* @throws NoSuchShadowRootException If no shadow root is found
*/
default SearchContext getShadowRoot() {
throw new UnsupportedOperationException("getShadowRoot");
}
/**
* Is this element displayed or not? This method avoids the problem of having to parse an
* element's "style" attribute.
*
* @return Whether or not the element is displayed
*/
boolean isDisplayed();
/**
* Where on the page is the top left-hand corner of the rendered element?
* <p>
* See <a href="https://w3c.github.io/webdriver/#get-element-rect">W3C WebDriver specification</a>
* for more details.
*
* @return A point, containing the location of the top left-hand corner of the element
*/
Point getLocation();
/**
* What is the width and height of the rendered element?
* <p>
* See <a href="https://w3c.github.io/webdriver/#get-element-rect">W3C WebDriver specification</a>
* for more details.
*
* @return The size of the element on the page.
*/
Dimension getSize();
/**
* @return The location and size of the rendered element
* <p>
* See <a href="https://w3c.github.io/webdriver/#get-element-rect">W3C WebDriver specification</a>
* for more details.
*/
Rectangle getRect();
/**
* Get the value of a given CSS property.
* Color values could be returned as rgba or rgb strings.
* This depends on whether the browser omits the implicit opacity value or not.
*
* For example if the "background-color" property is set as "green" in the
* HTML source, the returned value could be "rgba(0, 255, 0, 1)" if implicit opacity value is
* preserved or "rgb(0, 255, 0)" if it is omitted.
*
* Note that shorthand CSS properties (e.g. background, font, border, border-top, margin,
* margin-top, padding, padding-top, list-style, outline, pause, cue) are not returned,
* in accordance with the
* <a href="http://www.w3.org/TR/DOM-Level-2-Style/css.html#CSS-CSSStyleDeclaration">DOM CSS2 specification</a>
* - you should directly access the longhand properties (e.g. background-color) to access the
* desired values.
* <p>
* See <a href="https://w3c.github.io/webdriver/#get-element-css-value">W3C WebDriver specification</a>
* for more details.
*
* @param propertyName the css property name of the element
* @return The current, computed value of the property.
*/
String getCssValue(String propertyName);
}