public interface ElementHandle extends JSHandle
Page.querySelector() method.
import com.microsoft.playwright.*;
public class Example {
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
BrowserType chromium = playwright.chromium();
Browser browser = chromium.launch();
Page page = browser.newPage();
page.navigate("https://example.com");
ElementHandle hrefElement = page.querySelector("a");
hrefElement.click();
// ...
}
}
}
ElementHandle prevents DOM element from garbage collection unless the handle is disposed with JSHandle.dispose(). ElementHandles are auto-disposed when their origin frame gets navigated.
ElementHandle instances can be used as an argument in Page.evalOnSelector() and Page.evaluate() methods.
| Modifier and Type | Interface and Description |
|---|---|
static class |
ElementHandle.CheckOptions |
static class |
ElementHandle.ClickOptions |
static class |
ElementHandle.DblclickOptions |
static class |
ElementHandle.FillOptions |
static class |
ElementHandle.HoverOptions |
static class |
ElementHandle.PressOptions |
static class |
ElementHandle.ScreenshotOptions |
static class |
ElementHandle.ScrollIntoViewIfNeededOptions |
static class |
ElementHandle.SelectOptionOptions |
static class |
ElementHandle.SelectTextOptions |
static class |
ElementHandle.SetInputFilesOptions |
static class |
ElementHandle.TapOptions |
static class |
ElementHandle.TypeOptions |
static class |
ElementHandle.UncheckOptions |
static class |
ElementHandle.WaitForElementStateOptions |
static class |
ElementHandle.WaitForSelectorOptions |
| Modifier and Type | Method and Description |
|---|---|
BoundingBox |
boundingBox()
This method returns the bounding box of the element, or
null if the element is not visible. |
default void |
check()
This method checks the element by performing the following steps:
Ensure that element is a checkbox or a radio input.
|
void |
check(ElementHandle.CheckOptions options)
This method checks the element by performing the following steps:
Ensure that element is a checkbox or a radio input.
|
default void |
click()
This method clicks the element by performing the following steps:
Wait for actionability checks on the element, unless
force option is set.
Scroll the element into view if needed.
Use Page.mouse() to click in the center of the element, or the specified position.
Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
|
void |
click(ElementHandle.ClickOptions options)
This method clicks the element by performing the following steps:
Wait for actionability checks on the element, unless
force option is set.
Scroll the element into view if needed.
Use Page.mouse() to click in the center of the element, or the specified position.
Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
|
Frame |
contentFrame()
Returns the content frame for element handles referencing iframe nodes, or
null otherwise |
default void |
dblclick()
This method double clicks the element by performing the following steps:
Wait for actionability checks on the element, unless
force option is set.
Scroll the element into view if needed.
Use Page.mouse() to double click in the center of the element, or the specified position.
Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set. |
void |
dblclick(ElementHandle.DblclickOptions options)
This method double clicks the element by performing the following steps:
Wait for actionability checks on the element, unless
force option is set.
Scroll the element into view if needed.
Use Page.mouse() to double click in the center of the element, or the specified position.
Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set. |
default void |
dispatchEvent(String type)
The snippet below dispatches the
click event on the element. |
void |
dispatchEvent(String type,
Object eventInit)
The snippet below dispatches the
click event on the element. |
default Object |
evalOnSelector(String selector,
String expression)
Returns the return value of
expression. |
Object |
evalOnSelector(String selector,
String expression,
Object arg)
Returns the return value of
expression. |
default Object |
evalOnSelectorAll(String selector,
String expression)
Returns the return value of
expression. |
Object |
evalOnSelectorAll(String selector,
String expression,
Object arg)
Returns the return value of
expression. |
default void |
fill(String value)
This method waits for actionability checks, focuses the
element, fills it and triggers an
input event after filling. |
void |
fill(String value,
ElementHandle.FillOptions options)
This method waits for actionability checks, focuses the
element, fills it and triggers an
input event after filling. |
void |
focus()
Calls focus on the element.
|
String |
getAttribute(String name)
Returns element attribute value.
|
default void |
hover()
This method hovers over the element by performing the following steps:
Wait for actionability checks on the element, unless
force option is set.
Scroll the element into view if needed.
Use Page.mouse() to hover over the center of the element, or the specified position.
Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
|
void |
hover(ElementHandle.HoverOptions options)
This method hovers over the element by performing the following steps:
Wait for actionability checks on the element, unless
force option is set.
Scroll the element into view if needed.
Use Page.mouse() to hover over the center of the element, or the specified position.
Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
|
String |
innerHTML()
Returns the
element.innerHTML. |
String |
innerText()
Returns the
element.innerText. |
boolean |
isChecked()
Returns whether the element is checked.
|
boolean |
isDisabled()
Returns whether the element is disabled, the opposite of enabled.
|
boolean |
isEditable()
Returns whether the element is editable.
|
boolean |
isEnabled()
Returns whether the element is enabled.
|
boolean |
isHidden()
Returns whether the element is hidden, the opposite of visible.
|
boolean |
isVisible()
Returns whether the element is visible.
|
Frame |
ownerFrame()
Returns the frame containing the given element.
|
default void |
press(String key)
Focuses the element, and then uses
Keyboard.down() and Keyboard.up(). |
void |
press(String key,
ElementHandle.PressOptions options)
Focuses the element, and then uses
Keyboard.down() and Keyboard.up(). |
ElementHandle |
querySelector(String selector)
The method finds an element matching the specified selector in the
ElementHandle's subtree. |
List<ElementHandle> |
querySelectorAll(String selector)
The method finds all elements matching the specified selector in the
ElementHandles subtree. |
default byte[] |
screenshot()
Returns the buffer with the captured screenshot.
|
byte[] |
screenshot(ElementHandle.ScreenshotOptions options)
Returns the buffer with the captured screenshot.
|
default void |
scrollIntoViewIfNeeded()
This method waits for actionability checks, then tries to
scroll element into view, unless it is completely visible as defined by IntersectionObserver's
ratio. |
void |
scrollIntoViewIfNeeded(ElementHandle.ScrollIntoViewIfNeededOptions options)
This method waits for actionability checks, then tries to
scroll element into view, unless it is completely visible as defined by IntersectionObserver's
ratio. |
default List<String> |
selectOption(ElementHandle values)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
default List<String> |
selectOption(ElementHandle[] values)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
List<String> |
selectOption(ElementHandle[] values,
ElementHandle.SelectOptionOptions options)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
List<String> |
selectOption(ElementHandle values,
ElementHandle.SelectOptionOptions options)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
default List<String> |
selectOption(SelectOption values)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
default List<String> |
selectOption(SelectOption[] values)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
List<String> |
selectOption(SelectOption[] values,
ElementHandle.SelectOptionOptions options)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
List<String> |
selectOption(SelectOption values,
ElementHandle.SelectOptionOptions options)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
default List<String> |
selectOption(String values)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
default List<String> |
selectOption(String[] values)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
List<String> |
selectOption(String[] values,
ElementHandle.SelectOptionOptions options)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
List<String> |
selectOption(String values,
ElementHandle.SelectOptionOptions options)
This method waits for actionability checks, waits until
all specified options are present in the
<select> element and selects these options. |
default void |
selectText()
This method waits for actionability checks, then focuses
the element and selects all its text content.
|
void |
selectText(ElementHandle.SelectTextOptions options)
This method waits for actionability checks, then focuses
the element and selects all its text content.
|
default void |
setInputFiles(FilePayload files)
This method expects
elementHandle to point to an input element. |
default void |
setInputFiles(FilePayload[] files)
This method expects
elementHandle to point to an input element. |
void |
setInputFiles(FilePayload[] files,
ElementHandle.SetInputFilesOptions options)
This method expects
elementHandle to point to an input element. |
void |
setInputFiles(FilePayload files,
ElementHandle.SetInputFilesOptions options)
This method expects
elementHandle to point to an input element. |
default void |
setInputFiles(Path files)
This method expects
elementHandle to point to an input element. |
default void |
setInputFiles(Path[] files)
This method expects
elementHandle to point to an input element. |
void |
setInputFiles(Path[] files,
ElementHandle.SetInputFilesOptions options)
This method expects
elementHandle to point to an input element. |
void |
setInputFiles(Path files,
ElementHandle.SetInputFilesOptions options)
This method expects
elementHandle to point to an input element. |
default void |
tap()
This method taps the element by performing the following steps:
Wait for actionability checks on the element, unless
force option is set.
Scroll the element into view if needed.
Use Page.touchscreen() to tap the center of the element, or the specified position.
Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
|
void |
tap(ElementHandle.TapOptions options)
This method taps the element by performing the following steps:
Wait for actionability checks on the element, unless
force option is set.
Scroll the element into view if needed.
Use Page.touchscreen() to tap the center of the element, or the specified position.
Wait for initiated navigations to either succeed or fail, unless noWaitAfter option is set.
|
String |
textContent()
Returns the
node.textContent. |
default void |
type(String text)
Focuses the element, and then sends a
keydown, keypress/input, and keyup event for each character in the text. |
void |
type(String text,
ElementHandle.TypeOptions options)
Focuses the element, and then sends a
keydown, keypress/input, and keyup event for each character in the text. |
default void |
uncheck()
This method checks the element by performing the following steps:
Ensure that element is a checkbox or a radio input.
|
void |
uncheck(ElementHandle.UncheckOptions options)
This method checks the element by performing the following steps:
Ensure that element is a checkbox or a radio input.
|
default void |
waitForElementState(ElementState state)
Returns when the element satisfies the
state. |
void |
waitForElementState(ElementState state,
ElementHandle.WaitForElementStateOptions options)
Returns when the element satisfies the
state. |
default ElementHandle |
waitForSelector(String selector)
Returns element specified by selector when it satisfies
state option. |
ElementHandle |
waitForSelector(String selector,
ElementHandle.WaitForSelectorOptions options)
Returns element specified by selector when it satisfies
state option. |
asElement, dispose, evaluate, evaluate, evaluateHandle, evaluateHandle, getProperties, getProperty, jsonValueBoundingBox boundingBox()
null if the element is not visible. The bounding box is
calculated relative to the main frame viewport - which is usually the same as the browser window.
Scrolling affects the returned bonding box, similarly to Element.getBoundingClientRect.
That means x and/or y may be negative.
Elements from child frames return the bounding box relative to the main frame, unlike the Element.getBoundingClientRect.
Assuming the page is static, it is safe to use bounding box coordinates to perform input. For example, the following snippet should click the center of the element.
BoundingBox box = elementHandle.boundingBox();
page.mouse().click(box.x + box.width / 2, box.y + box.height / 2);
default void check()
force option is set.Page.mouse() to click in the center of the element.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
void check(ElementHandle.CheckOptions options)
force option is set.Page.mouse() to click in the center of the element.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
default void click()
force option is set.Page.mouse() to click in the center of the element, or the specified position.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
void click(ElementHandle.ClickOptions options)
force option is set.Page.mouse() to click in the center of the element, or the specified position.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
Frame contentFrame()
null otherwisedefault void dblclick()
force option is set.Page.mouse() to double click in the center of the element, or the specified position.noWaitAfter option is set. Note that if the first
click of the dblclick() triggers a navigation event, this method will throw.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
NOTE: elementHandle.dblclick() dispatches two click events and a single dblclick event.
void dblclick(ElementHandle.DblclickOptions options)
force option is set.Page.mouse() to double click in the center of the element, or the specified position.noWaitAfter option is set. Note that if the first
click of the dblclick() triggers a navigation event, this method will throw.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
NOTE: elementHandle.dblclick() dispatches two click events and a single dblclick event.
default void dispatchEvent(String type)
click event on the element. Regardless of the visibility state of the element,
click is dispatched. This is equivalent to calling element.click().
elementHandle.dispatchEvent("click");
Under the hood, it creates an instance of an event based on the given type, initializes it with eventInit properties
and dispatches it on the element. Events are composed, cancelable and bubble by default.
Since eventInit is event-specific, please refer to the events documentation for the lists of initial properties:
You can also specify JSHandle as the property value if you want live objects to be passed into the event:
// Note you can only create DataTransfer in Chromium and Firefox
JSHandle dataTransfer = page.evaluateHandle("() => new DataTransfer()");
Map<String, Object> arg = new HashMap<>();
arg.put("dataTransfer", dataTransfer);
elementHandle.dispatchEvent("dragstart", arg);
type - DOM event type: "click", "dragstart", etc.void dispatchEvent(String type, Object eventInit)
click event on the element. Regardless of the visibility state of the element,
click is dispatched. This is equivalent to calling element.click().
elementHandle.dispatchEvent("click");
Under the hood, it creates an instance of an event based on the given type, initializes it with eventInit properties
and dispatches it on the element. Events are composed, cancelable and bubble by default.
Since eventInit is event-specific, please refer to the events documentation for the lists of initial properties:
You can also specify JSHandle as the property value if you want live objects to be passed into the event:
// Note you can only create DataTransfer in Chromium and Firefox
JSHandle dataTransfer = page.evaluateHandle("() => new DataTransfer()");
Map<String, Object> arg = new HashMap<>();
arg.put("dataTransfer", dataTransfer);
elementHandle.dispatchEvent("dragstart", arg);
type - DOM event type: "click", "dragstart", etc.eventInit - Optional event-specific initialization properties.default Object evalOnSelector(String selector, String expression)
expression.
The method finds an element matching the specified selector in the ElementHandles subtree and passes it as a first
argument to expression. See Working with selectors for more
details. If no elements match the selector, the method throws an error.
If expression returns a Promise, then ElementHandle.evalOnSelector() would wait for the promise to resolve and return its value.
Examples:
ElementHandle tweetHandle = page.querySelector(".tweet");
assertEquals("100", tweetHandle.evalOnSelector(".like", "node => node.innerText"));
assertEquals("10", tweetHandle.evalOnSelector(".retweets", "node => node.innerText"));
selector - A selector to query for. See working with selectors for more
details.expression - JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted
as a function. Otherwise, evaluated as an expression.Object evalOnSelector(String selector, String expression, Object arg)
expression.
The method finds an element matching the specified selector in the ElementHandles subtree and passes it as a first
argument to expression. See Working with selectors for more
details. If no elements match the selector, the method throws an error.
If expression returns a Promise, then ElementHandle.evalOnSelector() would wait for the promise to resolve and return its value.
Examples:
ElementHandle tweetHandle = page.querySelector(".tweet");
assertEquals("100", tweetHandle.evalOnSelector(".like", "node => node.innerText"));
assertEquals("10", tweetHandle.evalOnSelector(".retweets", "node => node.innerText"));
selector - A selector to query for. See working with selectors for more
details.expression - JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted
as a function. Otherwise, evaluated as an expression.arg - Optional argument to pass to expression.default Object evalOnSelectorAll(String selector, String expression)
expression.
The method finds all elements matching the specified selector in the ElementHandle's subtree and passes an array of
matched elements as a first argument to expression. See Working
with selectors for more details.
If expression returns a Promise, then ElementHandle.evalOnSelectorAll() would wait for the promise to resolve and return its
value.
Examples:
ElementHandle feedHandle = page.querySelector(".feed");
assertEquals(Arrays.asList("Hello!", "Hi!"), feedHandle.evalOnSelectorAll(".tweet", "nodes => nodes.map(n => n.innerText)"));
selector - A selector to query for. See working with selectors for more
details.expression - JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted
as a function. Otherwise, evaluated as an expression.Object evalOnSelectorAll(String selector, String expression, Object arg)
expression.
The method finds all elements matching the specified selector in the ElementHandle's subtree and passes an array of
matched elements as a first argument to expression. See Working
with selectors for more details.
If expression returns a Promise, then ElementHandle.evalOnSelectorAll() would wait for the promise to resolve and return its
value.
Examples:
ElementHandle feedHandle = page.querySelector(".feed");
assertEquals(Arrays.asList("Hello!", "Hi!"), feedHandle.evalOnSelectorAll(".tweet", "nodes => nodes.map(n => n.innerText)"));
selector - A selector to query for. See working with selectors for more
details.expression - JavaScript expression to be evaluated in the browser context. If it looks like a function declaration, it is interpreted
as a function. Otherwise, evaluated as an expression.arg - Optional argument to pass to expression.default void fill(String value)
input event after filling. Note that you can pass an empty string to clear the input
field.
If the target element is not an <input>, <textarea> or [contenteditable] element, this method throws an error.
However, if the element is inside the <label> element that has an associated control, the control will be filled
instead.
To send fine-grained keyboard events, use ElementHandle.type().
value - Value to set for the <input>, <textarea> or [contenteditable] element.void fill(String value, ElementHandle.FillOptions options)
input event after filling. Note that you can pass an empty string to clear the input
field.
If the target element is not an <input>, <textarea> or [contenteditable] element, this method throws an error.
However, if the element is inside the <label> element that has an associated control, the control will be filled
instead.
To send fine-grained keyboard events, use ElementHandle.type().
value - Value to set for the <input>, <textarea> or [contenteditable] element.void focus()
String getAttribute(String name)
name - Attribute name to get the value for.default void hover()
force option is set.Page.mouse() to hover over the center of the element, or the specified position.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
void hover(ElementHandle.HoverOptions options)
force option is set.Page.mouse() to hover over the center of the element, or the specified position.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
String innerHTML()
element.innerHTML.String innerText()
element.innerText.boolean isChecked()
boolean isDisabled()
boolean isEditable()
boolean isEnabled()
boolean isHidden()
boolean isVisible()
Frame ownerFrame()
default void press(String key)
Keyboard.down() and Keyboard.up().
key can specify the intended keyboardEvent.key value or a single
character to generate the text for. A superset of the key values can be found here. Examples of the keys are:
F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab,
Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.
Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft.
Holding down Shift will type the text that corresponds to the key in the upper case.
If key is a single character, it is case-sensitive, so the values a and A will generate different respective
texts.
Shortcuts such as key: "Control+o" or key: "Control+Shift+T" are supported as well. When specified with the
modifier, modifier is pressed and being held while the subsequent key is being pressed.
key - Name of the key to press or a character to generate, such as ArrowLeft or a.void press(String key, ElementHandle.PressOptions options)
Keyboard.down() and Keyboard.up().
key can specify the intended keyboardEvent.key value or a single
character to generate the text for. A superset of the key values can be found here. Examples of the keys are:
F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab,
Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp, etc.
Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft.
Holding down Shift will type the text that corresponds to the key in the upper case.
If key is a single character, it is case-sensitive, so the values a and A will generate different respective
texts.
Shortcuts such as key: "Control+o" or key: "Control+Shift+T" are supported as well. When specified with the
modifier, modifier is pressed and being held while the subsequent key is being pressed.
key - Name of the key to press or a character to generate, such as ArrowLeft or a.ElementHandle querySelector(String selector)
ElementHandle's subtree. See Working with selectors for more details. If no elements match the
selector, returns null.selector - A selector to query for. See working with selectors for more
details.List<ElementHandle> querySelectorAll(String selector)
ElementHandles subtree. See Working with selectors for more details. If no elements match the
selector, returns empty array.selector - A selector to query for. See working with selectors for more
details.default byte[] screenshot()
This method waits for the actionability checks, then scrolls element into view before taking a screenshot. If the element is detached from DOM, the method throws an error.
byte[] screenshot(ElementHandle.ScreenshotOptions options)
This method waits for the actionability checks, then scrolls element into view before taking a screenshot. If the element is detached from DOM, the method throws an error.
default void scrollIntoViewIfNeeded()
ratio.
Throws when elementHandle does not point to an element connected to a Document or a ShadowRoot.
void scrollIntoViewIfNeeded(ElementHandle.ScrollIntoViewIfNeededOptions options)
ratio.
Throws when elementHandle does not point to an element connected to a Document or a ShadowRoot.
default List<String> selectOption(String values)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.List<String> selectOption(String values, ElementHandle.SelectOptionOptions options)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.default List<String> selectOption(ElementHandle values)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.List<String> selectOption(ElementHandle values, ElementHandle.SelectOptionOptions options)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.default List<String> selectOption(String[] values)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.List<String> selectOption(String[] values, ElementHandle.SelectOptionOptions options)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.default List<String> selectOption(SelectOption values)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.List<String> selectOption(SelectOption values, ElementHandle.SelectOptionOptions options)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.default List<String> selectOption(ElementHandle[] values)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.List<String> selectOption(ElementHandle[] values, ElementHandle.SelectOptionOptions options)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.default List<String> selectOption(SelectOption[] values)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.List<String> selectOption(SelectOption[] values, ElementHandle.SelectOptionOptions options)
<select> element and selects these options.
If the target element is not a <select> element, this method throws an error. However, if the element is inside the
<label> element that has an associated control, the control will be used
instead.
Returns the array of option values that have been successfully selected.
Triggers a change and input event once all the provided options have been selected.
// single selection matching the value
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});
values - Options to select. If the <select> has the multiple attribute, all matching options are selected, otherwise only the
first option matching one of the passed options is selected. String values are equivalent to {value:'string'}. Option
is considered matching if all specified properties match.default void selectText()
void selectText(ElementHandle.SelectTextOptions options)
default void setInputFiles(Path files)
elementHandle to point to an input element.
Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
void setInputFiles(Path files, ElementHandle.SetInputFilesOptions options)
elementHandle to point to an input element.
Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
default void setInputFiles(Path[] files)
elementHandle to point to an input element.
Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
void setInputFiles(Path[] files, ElementHandle.SetInputFilesOptions options)
elementHandle to point to an input element.
Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
default void setInputFiles(FilePayload files)
elementHandle to point to an input element.
Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
void setInputFiles(FilePayload files, ElementHandle.SetInputFilesOptions options)
elementHandle to point to an input element.
Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
default void setInputFiles(FilePayload[] files)
elementHandle to point to an input element.
Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
void setInputFiles(FilePayload[] files, ElementHandle.SetInputFilesOptions options)
elementHandle to point to an input element.
Sets the value of the file input to these file paths or files. If some of the filePaths are relative paths, then they
are resolved relative to the the current working directory. For empty array, clears the selected files.
default void tap()
force option is set.Page.touchscreen() to tap the center of the element, or the specified position.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
NOTE: elementHandle.tap() requires that the hasTouch option of the browser context be set to true.
void tap(ElementHandle.TapOptions options)
force option is set.Page.touchscreen() to tap the center of the element, or the specified position.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
NOTE: elementHandle.tap() requires that the hasTouch option of the browser context be set to true.
String textContent()
node.textContent.default void type(String text)
keydown, keypress/input, and keyup event for each character in the text.
To press a special key, like Control or ArrowDown, use ElementHandle.press().
elementHandle.type("Hello"); // Types instantly
elementHandle.type("World", new ElementHandle.TypeOptions().setDelay(100)); // Types slower, like a user
An example of typing into a text field and then submitting the form:
ElementHandle elementHandle = page.querySelector("input");
elementHandle.type("some text");
elementHandle.press("Enter");
text - A text to type into a focused element.void type(String text, ElementHandle.TypeOptions options)
keydown, keypress/input, and keyup event for each character in the text.
To press a special key, like Control or ArrowDown, use ElementHandle.press().
elementHandle.type("Hello"); // Types instantly
elementHandle.type("World", new ElementHandle.TypeOptions().setDelay(100)); // Types slower, like a user
An example of typing into a text field and then submitting the form:
ElementHandle elementHandle = page.querySelector("input");
elementHandle.type("some text");
elementHandle.press("Enter");
text - A text to type into a focused element.default void uncheck()
force option is set.Page.mouse() to click in the center of the element.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
void uncheck(ElementHandle.UncheckOptions options)
force option is set.Page.mouse() to click in the center of the element.noWaitAfter option is set.If the element is detached from the DOM at any moment during the action, this method throws.
When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing
zero timeout disables this.
default void waitForElementState(ElementState state)
state.
Depending on the state parameter, this method waits for one of the actionability checks to pass. This method throws when the
element is detached while waiting, unless waiting for the "hidden" state.
"visible" Wait until the element is visible."hidden" Wait until the element is not visible
or not attached. Note that waiting for hidden
does not throw when the element detaches."stable" Wait until the element is both visible
and stable."enabled" Wait until the element is enabled."disabled" Wait until the element is not
enabled."editable" Wait until the element is editable. If the element does not satisfy the condition for the timeout milliseconds, this method will throw.
state - A state to wait for, see below for more details.void waitForElementState(ElementState state, ElementHandle.WaitForElementStateOptions options)
state.
Depending on the state parameter, this method waits for one of the actionability checks to pass. This method throws when the
element is detached while waiting, unless waiting for the "hidden" state.
"visible" Wait until the element is visible."hidden" Wait until the element is not visible
or not attached. Note that waiting for hidden
does not throw when the element detaches."stable" Wait until the element is both visible
and stable."enabled" Wait until the element is enabled."disabled" Wait until the element is not
enabled."editable" Wait until the element is editable. If the element does not satisfy the condition for the timeout milliseconds, this method will throw.
state - A state to wait for, see below for more details.default ElementHandle waitForSelector(String selector)
state option. Returns null if waiting for hidden or
detached.
Wait for the selector relative to the element handle to satisfy state option (either appear/disappear from dom, or
become visible/hidden). If at the moment of calling the method selector already satisfies the condition, the method
will return immediately. If the selector doesn't satisfy the condition for the timeout milliseconds, the function will
throw.
page.setContent("<div><span></span></div>");
ElementHandle div = page.querySelector("div");
// Waiting for the "span" selector relative to the div.
ElementHandle span = div.waitForSelector("span", new ElementHandle.WaitForSelectorOptions()
.setState(WaitForSelectorState.ATTACHED));
NOTE: This method does not work across navigations, use Page.waitForSelector() instead.
selector - A selector to query for. See working with selectors for more
details.ElementHandle waitForSelector(String selector, ElementHandle.WaitForSelectorOptions options)
state option. Returns null if waiting for hidden or
detached.
Wait for the selector relative to the element handle to satisfy state option (either appear/disappear from dom, or
become visible/hidden). If at the moment of calling the method selector already satisfies the condition, the method
will return immediately. If the selector doesn't satisfy the condition for the timeout milliseconds, the function will
throw.
page.setContent("<div><span></span></div>");
ElementHandle div = page.querySelector("div");
// Waiting for the "span" selector relative to the div.
ElementHandle span = div.waitForSelector("span", new ElementHandle.WaitForSelectorOptions()
.setState(WaitForSelectorState.ATTACHED));
NOTE: This method does not work across navigations, use Page.waitForSelector() instead.
selector - A selector to query for. See working with selectors for more
details.Copyright © 2021. All rights reserved.