Calls blur on the element.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method returns the bounding box of the element, or 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 bounding 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.
Usage
const box = await element.boundingBox();
await page.mouse.click(box.x + box.width / 2, box.y + box.height / 2);
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method checks the element by performing the following steps:
force option is set.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.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional position?: { A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Optional trial?: booleanWhen set, this method only performs the actionability checks and skips the action. Defaults
to false. Useful to wait until the element is ready for the action without performing it.
This method waits for actionability checks, focuses the element, clears it and triggers an
input event after clearing.
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 cleared
instead.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Click an element.
Details
This method clicks the element by performing the following steps:
force option is set.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.
Optional options: { Optional button?: "left" | "right" | "middle"Defaults to left.
Optional clickdefaults to 1. See [UIEvent.detail].
Optional delay?: numberTime to wait between mousedown and mouseup in milliseconds. Defaults to 0.
Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional modifiers?: ("Alt" | "Control" | "Meta" | "Shift")[]Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional position?: { A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Optional trial?: booleanWhen set, this method only performs the actionability checks and skips the action. Defaults
to false. Useful to wait until the element is ready for the action without performing it.
This method double clicks the element by performing the following steps:
force option is set.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 element.dblclick() dispatches two click events and a single dblclick event.
Optional options: { Optional button?: "left" | "right" | "middle"Defaults to left.
Optional delay?: numberTime to wait between mousedown and mouseup in milliseconds. Defaults to 0.
Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional modifiers?: ("Alt" | "Control" | "Meta" | "Shift")[]Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional position?: { A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Optional trial?: booleanWhen set, this method only performs the actionability checks and skips the action. Defaults
to false. Useful to wait until the element is ready for the action without performing it.
The snippet below dispatches the click event on the element. Regardless of the visibility state of the element,
click is dispatched. This is equivalent to calling
element.click().
Usage
await element.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
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await element.dispatchEvent('dragstart', { dataTransfer });
DOM event type: "click", "dragstart", etc.
Optional eventInit: EvaluationArgumentOptional event-specific initialization properties.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method drags the locator to another target locator or target position. It will first move to the source
element, perform a mousedown, then move to the target element or position and perform a mouseup.
Usage
const source = page.locator('#source');
const target = page.locator('#target');
await source.dragTo(target);
// or specify exact positions relative to the top-left corners of the elements:
await source.dragTo(target, {
sourcePosition: { x: 34, y: 7 },
targetPosition: { x: 10, y: 20 },
});
Locator of the element to drag to.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional sourceClicks on the source element at this point relative to the top-left corner of the element's padding box. If not specified, some visible point of the element is used.
Optional targetDrops on the target element at this point relative to the top-left corner of the element's padding box. If not specified, some visible point of the element is used.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Optional trial?: booleanWhen set, this method only performs the actionability checks and skips the action. Defaults
to false. Useful to wait until the element is ready for the action without performing it.
Resolves given locator to the first matching DOM element. If no elements matching the query are visible, waits for them up to a given timeout. If multiple elements match the selector, throws.
Optional options: { Optional timeout?: numberResolves given locator to all matching DOM elements.
Returns the return value of pageFunction.
This method passes this handle as the first argument to pageFunction.
If pageFunction returns a [Promise], then handle.evaluate would wait for the promise to resolve and return its
value.
Usage
const tweets = page.locator('.tweet .retweets');
expect(await tweets.evaluate(node => node.innerText)).toBe('10 retweets');
Function to be evaluated in the page context.
Optional argument to pass to pageFunction.
Optional options: { Optional timeout?: numberReturns the return value of pageFunction.
This method passes this handle as the first argument to pageFunction.
If pageFunction returns a [Promise], then handle.evaluate would wait for the promise to resolve and return its
value.
Usage
const tweets = page.locator('.tweet .retweets');
expect(await tweets.evaluate(node => node.innerText)).toBe('10 retweets');
Function to be evaluated in the page context.
Optional options: { Optional timeout?: numberThe method finds all elements matching the specified locator and passes an array of matched elements as a first
argument to pageFunction. Returns the result of pageFunction invocation.
If pageFunction returns a [Promise], then
locator.evaluateAll(pageFunction[, arg])
would wait for the promise to resolve and return its value.
Usage
const elements = page.locator('div');
const divCounts = await elements.evaluateAll((divs, min) => divs.length >= min, 10);
Function to be evaluated in the page context.
Optional argument to pass to pageFunction.
The method finds all elements matching the specified locator and passes an array of matched elements as a first
argument to pageFunction. Returns the result of pageFunction invocation.
If pageFunction returns a [Promise], then
locator.evaluateAll(pageFunction[, arg])
would wait for the promise to resolve and return its value.
Usage
const elements = page.locator('div');
const divCounts = await elements.evaluateAll((divs, min) => divs.length >= min, 10);
Function to be evaluated in the page context.
Returns the return value of pageFunction as a [JSHandle].
This method passes this handle as the first argument to pageFunction.
The only difference between locator.evaluate(pageFunction[, arg, options]) and locator.evaluateHandle(pageFunction[, arg, options]) is that locator.evaluateHandle(pageFunction[, arg, options]) returns [JSHandle].
If the function passed to the locator.evaluateHandle(pageFunction[, arg, options]) returns a [Promise], then locator.evaluateHandle(pageFunction[, arg, options]) would wait for the promise to resolve and return its value.
See page.evaluateHandle(pageFunction[, arg]) for more details.
Function to be evaluated in the page context.
Optional arg: EvaluationArgumentOptional argument to pass to pageFunction.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method waits for actionability checks, focuses the element, fills it and triggers an
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 locator.type(text[, options]).
Value to set for the <input>, <textarea> or [contenteditable] element.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method narrows existing locator according to the options, for example filters by text. It can be chained to filter multiple times.
Usage
const rowLocator = page.locator('tr');
// ...
await rowLocator
.filter({ hasText: 'text in column 1' })
.filter({ has: page.getByRole('button', { name: 'column 2 button' }) })
.screenshot();
Optional options: { Optional has?: LocatorMatches elements containing an element that matches an inner locator. Inner locator is queried against the outer
one. For example, article that has text=Playwright matches <article><div>Playwright</div></article>.
Note that outer and inner locators must belong to the same frame. Inner locator must not contain [FrameLocator]s.
Optional hasMatches elements containing specified text somewhere inside, possibly in a child or a descendant element. When
passed a [string], matching is case-insensitive and searches for a substring. For example, "Playwright" matches
<article><div>Playwright</div></article>.
Calls focus on the element.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Usage
When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in that iframe:
const locator = page.frameLocator('iframe').getByText('Submit');
await locator.click();
A selector to use when resolving DOM element.
Returns element attribute value.
Attribute name to get the value for.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Allows locating elements by their alt text. For example, this method will find the image by alt text "Castle":
<img alt='Castle'>
Text to locate the element for.
Optional options: { Optional exact?: booleanWhether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.
Allows locating input elements by the text of the associated label. For example, this method will find the input by label text "Password" in the following DOM:
<label for="password-input">Password:</label>
<input id="password-input">
Text to locate the element for.
Optional options: { Optional exact?: booleanWhether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.
Allows locating input elements by the placeholder text. For example, this method will find the input by placeholder "Country":
<input placeholder="Country">
Text to locate the element for.
Optional options: { Optional exact?: booleanWhether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.
Allows locating elements by their ARIA role, ARIA attributes and accessible name. Note that role selector does not replace accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.
Note that many html elements have an implicitly
defined role that is recognized by the role selector.
You can find all the supported roles here. ARIA guidelines
do not recommend duplicating implicit roles and attributes by setting role and/or aria-* attributes to
default values.
Required aria role.
Optional options: { Optional checked?: booleanAn attribute that is usually set by aria-checked or native <input type=checkbox> controls.
Learn more about aria-checked.
Optional disabled?: booleanAn attribute that is usually set by aria-disabled or disabled.
NOTE Unlike most other attributes, disabled is inherited through the DOM hierarchy. Learn more about
aria-disabled.
Optional exact?: booleanWhether name is matched exactly: case-sensitive and whole-string. Defaults to false. Ignored when name is a
regular expression. Note that exact match still trims whitespace.
Optional expanded?: booleanAn attribute that is usually set by aria-expanded.
Learn more about aria-expanded.
Optional includeOption that controls whether hidden elements are matched. By default, only non-hidden elements, as defined by ARIA, are matched by role selector.
Learn more about aria-hidden.
Optional level?: numberA number attribute that is usually present for roles heading, listitem, row, treeitem, with default values
for <h1>-<h6> elements.
Learn more about aria-level.
Optional name?: string | RegExpOption to match the accessible name. By default, matching is
case-insensitive and searches for a substring, use exact to control this behavior.
Learn more about accessible name.
Optional pressed?: booleanAn attribute that is usually set by aria-pressed.
Learn more about aria-pressed.
Optional selected?: booleanAn attribute that is usually set by aria-selected.
Learn more about aria-selected.
Locate element by the test id. By default, the data-testid attribute is used as a test id. Use
selectors.setTestIdAttribute(attributeName)
to configure a different test id attribute if necessary.
// Set custom test id attribute from @playwright/test config:
use: {
testIdAttribute: 'data-pw'
}
Id to locate the element by.
Allows locating elements that contain given text. Consider the following DOM structure:
<div>Hello <span>world</span></div>
<div>Hello</div>
You can locate by text substring, exact string, or a regular expression:
// Matches <span>
page.getByText('world')
// Matches first <div>
page.getByText('Hello world')
// Matches second <div>
page.getByText('Hello', { exact: true })
// Matches both <div>s
page.getByText(/Hello/)
// Matches second <div>
page.getByText(/^hello$/i)
See also locator.filter([options]) that allows to match by another criteria, like an accessible role, and then filter by the text content.
NOTE Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
NOTE Input elements of the type button and submit are matched by their value instead of the text content.
For example, locating by text "Log in" matches <input type=button value="Log in">.
Text to locate the element for.
Optional options: { Optional exact?: booleanWhether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.
Allows locating elements by their title. For example, this method will find the button by its title "Place the order":
<button title='Place the order'>Order Now</button>
Text to locate the element for.
Optional options: { Optional exact?: booleanWhether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a regular expression. Note that exact match still trims whitespace.
Highlight the corresponding element(s) on the screen. Useful for debugging, don't commit the code that uses locator.highlight().
This method hovers over the element by performing the following steps:
force option is set.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.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional modifiers?: ("Alt" | "Control" | "Meta" | "Shift")[]Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional position?: { A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Optional trial?: booleanWhen set, this method only performs the actionability checks and skips the action. Defaults
to false. Useful to wait until the element is ready for the action without performing it.
Returns the element.innerHTML.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Returns the element.innerText.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Returns input.value for the selected <input> or <textarea> or <select> element.
Throws for non-input elements. However, if the element is inside the <label> element that has an associated
control, returns the value of the
control.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Returns whether the element is checked. Throws if the element is not a checkbox or radio input.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Returns whether the element is disabled, the opposite of enabled.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Returns whether the element is editable.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Returns whether the element is enabled.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Returns whether the element is hidden, the opposite of visible.
Optional options: { Optional timeout?: numberThis option is ignored. locator.isHidden([options]) does not wait for the element to become hidden and returns immediately.
Returns whether the element is visible.
Optional options: { Optional timeout?: numberThis option is ignored. locator.isVisible([options]) does not wait for the element to become visible and returns immediately.
The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to locator.filter([options]) method.
A selector to use when resolving DOM element.
Optional options: { Optional has?: LocatorMatches elements containing an element that matches an inner locator. Inner locator is queried against the outer
one. For example, article that has text=Playwright matches <article><div>Playwright</div></article>.
Note that outer and inner locators must belong to the same frame. Inner locator must not contain [FrameLocator]s.
Optional hasMatches elements containing specified text somewhere inside, possibly in a child or a descendant element. When
passed a [string], matching is case-insensitive and searches for a substring. For example, "Playwright" matches
<article><div>Playwright</div></article>.
Focuses the element, and then uses keyboard.down(key) and keyboard.up(key).
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.
Name of the key to press or a character to generate, such as ArrowLeft or a.
Optional options: { Optional delay?: numberTime to wait between keydown and keyup in milliseconds. Defaults to 0.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method captures a screenshot of the page, clipped to the size and position of a particular element matching the locator. If the element is covered by other elements, it will not be actually visible on the screenshot. If the element is a scrollable container, only the currently scrolled content will be visible on the 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.
Returns the buffer with the captured screenshot.
Optional options: LocatorScreenshotOptionsThis method waits for actionability checks, then tries to scroll element into view, unless
it is completely visible as defined by
IntersectionObserver's ratio.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Selects option or options in <select>.
Details
This method waits for actionability checks, waits until all specified options are present in
the <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.
Usage
<select multiple>
<option value="red">Red</div>
<option value="green">Green</div>
<option value="blue">Blue</div>
</select>
// single selection matching the value or label
element.selectOption('blue');
// single selection matching the label
element.selectOption({ label: 'Blue' });
// multiple selection for red, green and blue options
element.selectOption(['red', 'green', 'blue']);
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 matching both values and
labels. Option is considered matching if all specified properties match.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method waits for actionability checks, then focuses the element and selects all its text content.
If the element is inside the <label> element that has an associated
control, focuses and selects text in
the control instead.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method checks or unchecks an element by performing the following steps:
force option is set. If
the element is detached during the checks, the whole action is retried.noWaitAfter option is set.When all steps combined have not finished during the specified timeout, this method throws a [TimeoutError].
Passing zero timeout disables this.
Whether to check or uncheck the checkbox.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional position?: { A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Optional trial?: booleanWhen set, this method only performs the actionability checks and skips the action. Defaults
to false. Useful to wait until the element is ready for the action without performing it.
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 current working directory. For empty array, clears the selected files.
This method expects [Locator] to point to an
input element. However, if the element is inside
the <label> element that has an associated
control, targets the control instead.
Optional options: { Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method taps the element by performing the following steps:
force option is set.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 element.tap() requires that the hasTouch option of the browser context be set to true.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional modifiers?: ("Alt" | "Control" | "Meta" | "Shift")[]Modifier keys to press. Ensures that only these modifiers are pressed during the operation, and then restores current modifiers back. If not specified, currently pressed modifiers are used.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional position?: { A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Optional trial?: booleanWhen set, this method only performs the actionability checks and skips the action. Defaults
to false. Useful to wait until the element is ready for the action without performing it.
Returns the node.textContent.
Optional options: { Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the
text.
To press a special key, like Control or ArrowDown, use
locator.press(key[, options]).
Usage
await element.type('Hello'); // Types instantly
await element.type('World', {delay: 100}); // Types slower, like a user
An example of typing into a text field and then submitting the form:
const element = page.getByLabel('Password');
await element.type('my password');
await element.press('Enter');
A text to type into a focused element.
Optional options: { Optional delay?: numberTime to wait between key presses in milliseconds. Defaults to 0.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
This method checks the element by performing the following steps:
force option is set.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.
Optional options: { Optional force?: booleanWhether to bypass the actionability checks. Defaults to false.
Optional noActions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You
can opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as
navigating to inaccessible pages. Defaults to false.
Optional position?: { A point to use relative to the top-left corner of element padding box. If not specified, uses some visible point of the element.
Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Optional trial?: booleanWhen set, this method only performs the actionability checks and skips the action. Defaults
to false. Useful to wait until the element is ready for the action without performing it.
Returns when element specified by locator satisfies the state option.
If target element already satisfies the condition, the method returns immediately. Otherwise, waits for up to
timeout milliseconds until the condition is met.
Usage
const orderSent = page.locator('#order-sent');
await orderSent.waitFor();
Optional options: { Optional state?: "attached" | "detached" | "visible" | "hidden"Defaults to 'visible'. Can be either:
'attached' - wait for element to be present in DOM.'detached' - wait for element to not be present in DOM.'visible' - wait for element to have non-empty bounding box and no visibility:hidden. Note that element
without any content or with display:none has an empty bounding box and is not considered visible.'hidden' - wait for element to be either detached from DOM, or have an empty bounding box or
visibility:hidden. This is opposite to the 'visible' option.Optional timeout?: numberMaximum time in milliseconds, defaults to 30 seconds, pass 0 to disable timeout. The default value can be changed
by using the
browserContext.setDefaultTimeout(timeout)
or page.setDefaultTimeout(timeout) methods.
Generated using TypeDoc
Locators are the central piece of Playwright's auto-waiting and retry-ability. In a nutshell, locators represent a way to find element(s) on the page at any moment. Locator can be created with the page.locator(selector[, options]) method.
Learn more about locators.