diff --git a/java/src/org/openqa/selenium/WebElement.java b/java/src/org/openqa/selenium/WebElement.java index 05b661d16179b..657783836506f 100644 --- a/java/src/org/openqa/selenium/WebElement.java +++ b/java/src/org/openqa/selenium/WebElement.java @@ -14,7 +14,6 @@ // 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; @@ -22,319 +21,401 @@ import org.jspecify.annotations.Nullable; /** - * Represents an HTML element. Generally, all interesting operations to do with interacting with a - * page will be performed through this interface. + * Represents an HTML element. Generally, all interesting operations to do with + * interacting with a page will be performed through this interface. * - *

All method calls will do a freshness check to ensure that the element reference is still - * valid. This essentially determines whether the element is still attached to the DOM. If this test - * fails, then an {@link org.openqa.selenium.StaleElementReferenceException} is thrown, and all + *

+ * All method calls will do a freshness check to ensure that the element + * reference is still valid. This essentially determines whether 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. */ @NullMarked 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. - * - *

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. - * - *

There are some preconditions for an element to be clicked. The element must be visible, and - * it must have a height and width greater than 0. - * - *

See W3C WebDriver specification - * 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(); + /** + * 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. + * + *

+ * 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. + * + *

+ * There are some preconditions for an element to be clicked. The element + * must be visible, and it must have a height and width greater than 0. + * + *

+ * See W3C + * WebDriver specification + * 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. - * - *

See W3C WebDriver - * specification for more details. - * - * @param keysToSend character sequence to send to the element - * @throws IllegalArgumentException if keysToSend is null - */ - void sendKeys(CharSequence... keysToSend); + /** + * Use this method to simulate typing into an element, which may set its + * value. + * + *

+ * See W3C + * WebDriver specification 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. - * - *

See W3C WebDriver specification - * and HTML specification - * for more details. - */ - void clear(); + /** + * If this element is a form entry element, this will reset its value. + * + *

+ * See W3C + * WebDriver specification + * and + * HTML + * specification + * for more details. + */ + void clear(); - /** - * Get the tag name of this element. Not the value of the name attribute: will return - * "input" for the element <input name="foo" />. - * - *

See W3C WebDriver - * specification for more details. - * - * @return The tag name of this element. - */ - String getTagName(); + /** + * Get the tag name of this element. Not the value of the name + * attribute: will return "input" for the element + * <input name="foo" />. + * + *

+ * See W3C + * WebDriver specification 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. - * - *

See W3C WebDriver - * specification 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 @Nullable String getDomProperty(String name) { - throw new UnsupportedOperationException("getDomProperty"); - } + /** + * 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. + * + *

+ * See W3C + * WebDriver specification 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 @Nullable + String getDomProperty(String name) { + throw new UnsupportedOperationException("getDomProperty"); + } - /** - * Get the value of the given attribute of the element. - * - *

This method, unlike {@link #getAttribute(String)}, returns the value of the attribute with - * the given name but not the property with the same name. - * - *

The following are deemed to be "boolean" attributes, and will return either "true" or null: - * - *

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 - * - *

See W3C WebDriver - * specification for more details. - * - * @param name The name of the attribute. - * @return The attribute's value or null if the value is not set. - */ - default @Nullable String getDomAttribute(String name) { - throw new UnsupportedOperationException("getDomAttribute"); - } + /** + * Get the value of the given attribute of the element. + * + *

+ * This method, unlike {@link #getAttribute(String)}, returns the value of + * the attribute with the given name but not the property with the same + * name. + * + *

+ * The following are deemed to be "boolean" attributes, and will return + * either "true" or null: + * + *

+ * 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 + * + *

+ * See W3C + * WebDriver specification for more details. + * + * @param name The name of the attribute. + * @return The attribute's value or null if the value is not set. + */ + default @Nullable + 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. - * - *

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. - * - *

The "style" attribute is converted as best can be to a text representation with a trailing - * semicolon. - * - *

The following are deemed to be "boolean" attributes, and will return either "true" or null: - * - *

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 - * - *

Finally, the following commonly mis-capitalized attribute/property names are evaluated as - * expected: - * - *

- * - * Note: 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. - * - *

See W3C WebDriver - * specification 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. - * @deprecated This method is deprecated. Use {@link #getDomProperty(String)} or {@link - * #getDomAttribute(String)} for more precise attribute retrieval. - */ - @Deprecated - @Nullable String getAttribute(String name); + /** + * 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. + * + *

+ * 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. + * + *

+ * The "style" attribute is converted as best can be to a text + * representation with a trailing semicolon. + * + *

+ * The following are deemed to be "boolean" attributes, and will return + * either "true" or null: + * + *

+ * 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 + * + *

+ * Finally, the following commonly mis-capitalized attribute/property names + * are evaluated as expected: + * + *

+ * + * Note: 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. + * + *

+ * See W3C + * WebDriver specification 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. + * @deprecated This method is deprecated. Use + * {@link #getDomProperty(String)} or {@link + * #getDomAttribute(String)} for more precise attribute retrieval. + */ + @Deprecated + @Nullable + String getAttribute(String name); - /** - * Gets result of computing the WAI-ARIA role of element. - * - *

See W3C WebDriver - * specification for more details. - * - * @return the WAI-ARIA role of the element. - */ - default @Nullable String getAriaRole() { - throw new UnsupportedOperationException("getAriaRole"); - } + /** + * Gets result of computing the WAI-ARIA role of element. + * + *

+ * See W3C + * WebDriver specification for more details. + * + * @return the WAI-ARIA role of the element. + */ + default @Nullable + String getAriaRole() { + throw new UnsupportedOperationException("getAriaRole"); + } - /** - * Gets result of a Accessible Name and Description Computation for the Accessible Name of the - * element. - * - *

See W3C WebDriver - * specification for more details. - * - * @return the accessible name of the element. - */ - default @Nullable String getAccessibleName() { - throw new UnsupportedOperationException("getAccessibleName"); - } + /** + * Gets result of a Accessible Name and Description Computation for the + * Accessible Name of the element. + * + *

+ * See W3C + * WebDriver specification for more details. + * + * @return the accessible name of the element. + */ + default @Nullable + String getAccessibleName() { + throw new UnsupportedOperationException("getAccessibleName"); + } - /** - * Determine whether 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 specification. - * - *

See W3C WebDriver - * specification for more details. - * - * @return True if the element is currently selected or checked, false otherwise. - */ - boolean isSelected(); + /** + * Determine whether 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 specification. + * + *

+ * See W3C + * WebDriver specification 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. - * - *

See W3C WebDriver - * specification for more details. - * - * @return True if the element is enabled, false otherwise. - */ - boolean isEnabled(); + /** + * Is the element currently enabled or not? This will generally return true + * for everything but disabled input elements. + * + *

+ * See W3C + * WebDriver specification 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. - * - *

See W3C WebDriver - * specification for more details. - * - * @return The visible text of this element. - */ - String getText(); + /** + * Get the visible (i.e. not hidden by CSS) text of this element, including + * sub-elements. + * + *

+ * See W3C + * WebDriver specification 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. - * - *

See W3C WebDriver - * specification 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 findElements(By by); + /** + * 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. + * + *

+ * See + * W3C + * WebDriver specification 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 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. - * - *

findElement should not be used to look for non-present elements, use {@link - * #findElements(By)} and assert zero length response instead. - * - *

See W3C WebDriver - * specification 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); + /** + * 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. + * + *

+ * findElement should not be used to look for non-present elements, use {@link + * #findElements(By)} and assert zero length response instead. + * + *

+ * See + * W3C + * WebDriver specification 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"); - } + /** + * @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 the element is displayed - */ - boolean isDisplayed(); + /** + * Is this element displayed or not? This method avoids the problem of + * having to parse an element's "style" attribute. + * + * @return Whether the element is displayed + */ + boolean isDisplayed(); - /** - * Where on the page is the top left-hand corner of the rendered element? - * - *

See W3C WebDriver - * specification for more details. - * - * @return A point, containing the location of the top left-hand corner of the element - */ - Point getLocation(); + /** + * Where on the page is the top left-hand corner of the rendered element? + * + *

+ * See W3C + * WebDriver specification 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? - * - *

See W3C WebDriver - * specification for more details. - * - * @return The size of the element on the page. - */ - Dimension getSize(); + /** + * What is the width and height of the rendered element? + * + *

+ * See W3C + * WebDriver specification for more details. + * + * @return The size of the element on the page. + */ + Dimension getSize(); - /** - * @return The location and size of the rendered element - *

See W3C WebDriver - * specification for more details. - */ - Rectangle getRect(); + /** + * @return The location and size of the rendered element + *

+ * See W3C + * WebDriver specification 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 DOM CSS2 - * specification - you should directly access the longhand properties (e.g. background-color) - * to access the desired values. - * - *

See W3C WebDriver - * specification for more details. - * - * @param propertyName the css property name of the element - * @return The current, computed value of the property. - */ - String getCssValue(String propertyName); + /** + * 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 DOM + * CSS2 specification - you should directly access the longhand + * properties (e.g. background-color) to access the desired values. + * + *

+ * See W3C + * WebDriver specification for more details. + * + * @param propertyName the css property name of the element + * @return The current, computed value of the property. + */ + String getCssValue(String propertyName); + /** + * Gets the value attribute of the element. + * + *

+ * This method retrieves the current value of the element, similar to + * {@code getAttribute("value")}. It is useful for getting text entered in + * input fields or selected values in dropdowns. + * + *

+ * See W3C + * WebDriver specification + * for more details. + * + * @return the value of the element as a string. + */ + String getValue(); } diff --git a/java/src/org/openqa/selenium/remote/RemoteWebElement.java b/java/src/org/openqa/selenium/remote/RemoteWebElement.java index 599f895fd42a0..20948fd68f9c7 100644 --- a/java/src/org/openqa/selenium/remote/RemoteWebElement.java +++ b/java/src/org/openqa/selenium/remote/RemoteWebElement.java @@ -144,6 +144,11 @@ public String getDomAttribute(String name) { return stringValueOf(execute(DriverCommand.GET_ELEMENT_DOM_ATTRIBUTE(id, name)).getValue()); } + @Override + public String getValue() { + return getDomProperty("value"); + } + @Override public String getAttribute(String name) { return stringValueOf(execute(DriverCommand.GET_ELEMENT_ATTRIBUTE(id, name)).getValue());