How actions wait
Every action waits, inside the session, until its element is ready:- Resolve. The locator must match exactly one element. If it matches none yet, the session keeps looking.
- Wait until actionable. The element is visible, stable (the same box on two checks in a row), enabled (for click, fill, check and select) and editable (for fill). An element partly outside the viewport is scrolled to the middle.
- Act with real operating-system input. The pointer goes to the element’s center, or to
position.
set_default_timeout(), and at most
60,000. Running out raises TimeoutError naming the check that failed.
Strictness. Actions and single-element reads fail when the locator matches
more than one element: TimeoutError at once, with a message saying how many
matched. Narrow it with first, last, nth() or filter(). count(),
all(), all_inner_texts(), all_text_contents() and evaluate_all() work on
every match.
Narrowing
locator.first, locator.last, locator.nth()
The first match, the last match, or the match at index (zero-based; -1 is the last).
Locator.
locator.filter()
Narrow the matches by text, by an element inside them, or by visibility.
| Parameter | Type | Default | Description |
|---|---|---|---|
has_text | str | re.Pattern | None | None | Keep matches containing this text, case-insensitively. |
has_not_text | str | re.Pattern | None | None | Drop matches containing it. |
has | Locator | None | None | Keep matches that contain an element this locator finds. |
has_not | Locator | None | None | Drop matches that contain one. It must be a locator made from a selector string, such as page.locator(".badge"). |
visible | bool | None | None | Keep only visible (True) or only hidden (False) matches. |
Locator.
locator.locator() and locator.get_by_*()
Find elements inside this locator’s element. locator() takes a selector
string or another Locator, plus the filter() keywords except visible; the
get_by_* methods take what they take on Page.
locator.get_by_query() finds the element a description names inside this one,
as page.get_by_query() does on the page.
locator.with_options()
This locator with its resolver picked, for every later call.
strategy and model are as described in
How a locator resolves. ocr_engine is
"free" or "premium", for strategy="vision". With no arguments it returns
the same locator.
locator.and_() and locator.or_()
Elements that match both locators, or either.
locator.all()
One locator per current match, in document order. Doesn’t wait.
Returns list[Locator].
Actions
locator.click()
| Parameter | Type | Default | Description |
|---|---|---|---|
button | str | None | "left" | "left", "right" or "middle". |
click_count | int | None | 1 | 2 for a double click. |
modifiers | list[str] | None | None | Keys held during the click: "Control", "Shift", "Alt". |
position | dict | None | center | {"x", "y"} in CSS pixels from the element’s top-left. |
force | bool | False | Skip every actionability check except having a box. |
trial | bool | False | Run the checks without clicking. |
timeout | float | None | 5000 | Milliseconds. |
locator.dblclick(), locator.tap()
dblclick(**options) is click(click_count=2, **options). tap(**options) is
click(**options): browser sessions take mouse input.
locator.hover()
locator.fill() and locator.clear()
Focus the element, select everything in it, delete it, and type value.
clear() is fill("").
locator.press_sequentially()
Focus the element, then type text one key at a time without clearing it.
locator.type() is the same.
| Parameter | Type | Default | Description |
|---|---|---|---|
delay | float | None | None | Milliseconds between keys. |
locator.press()
Focus the element and press a key or chord, such as "Enter" or "Control+a".
See Keyboard for key names.
locator.check(), locator.uncheck(), locator.set_checked()
Click only when the state differs, then confirm it changed.
locator.select_option()
Select options of a <select> by value or visible label, and fire input and change.
| Parameter | Type | Default | Description |
|---|---|---|---|
value | str | list[str] | None | None | Option values. |
label | str | list[str] | None | None | Option labels. |
list[str]: the values now selected.
locator.focus(), locator.blur(), locator.scroll_into_view_if_needed()
Focus or blur the element by script, or scroll it into view.
locator.drag_to()
Press on this element, move to target, and release there, with the real mouse.
| Parameter | Type | Default | Description |
|---|---|---|---|
target | Locator | required | Where to drop. |
source_position, target_position | dict | None | centers | {"x", "y"} from each element’s top-left. |
locator.dispatch_event()
Dispatch a DOM event on the element by script. It is not real input, so it is not a click.
locator.set_input_files()
Choose files for an <input type="file">, as Playwright does.
| Parameter | Type | Default | Description |
|---|---|---|---|
files | str | Path | dict | list | required | A local path, a payload {"name", "mimeType", "buffer"} with buffer as bytes, or a list of either. [] clears the input. |
timeout | float | None | 5000 | Milliseconds to wait for the input. |
name). Characters Windows doesn’t allow in a
file name become _. A second file with the same name in one call is
renamed, such as notes (2).txt. Each file can be up to 32 MiB. A hidden input works, as in
Playwright.
ValueError for a payload without name or buffer; TypeError
for anything else that isn’t a path or a payload; OSError when a local path
can’t be read.
page.set_input_files(selector, files) is the same on page.locator(selector).
locator.screenshot()
Not available yet. Raises UnsupportedError. For a picture of an element,
use page.screenshot() with locator.bounding_box().
Reads
locator.inner_text(), text_content(), inner_html(), input_value()
input_value reads an <input>, <textarea> or <select>.
locator.get_attribute()
str | None: None when the attribute is absent.
locator.all_inner_texts() and locator.all_text_contents()
Every match’s text, in document order. Doesn’t wait.
Returns list[str].
locator.count()
How many elements match now. Doesn’t wait.
Returns int.
locator.bounding_box()
{"x", "y", "width", "height"} in the page’s CSS pixels from the
viewport’s top-left, or None when the element isn’t rendered.
locator.aria_snapshot()
The element’s accessibility tree as Playwright’s YAML aria snapshot. See
page.aria_snapshot().
Returns str.
States
locator.is_visible() and locator.is_hidden()
Whether the element is visible (or hidden) now. They don’t wait: no match counts as hidden.
Returns bool.
locator.is_enabled(), is_disabled(), is_editable(), is_checked(), is_focused()
Wait until the element is attached, then answer.
bool. Raises UnsupportedError from is_checked() when the
element isn’t a checkbox or radio button.
locator.wait_for()
Wait until the locator is "attached", "detached", "visible" or "hidden".
Scripts
locator.evaluate()
Run expression with the element as its first argument and arg as its second.
world="main"; see
page.evaluate().
EvaluationError when the script throws.
locator.evaluate_all()
Run expression once, with a list of every match as its first argument and
arg as its second, and return its result, as Playwright does. It doesn’t wait
for matches: with none, the list is empty.
| Parameter | Type | Default | Description |
|---|---|---|---|
expression | str | required | A function that takes the list of elements. |
arg | Any | none | One JSON value passed as the second argument. |
world | str | None | "isolated" | "isolated" or "main"; see page.evaluate(). |
EvaluationError when the script throws.