Page is one tab of the session. browser.page is the tab the session opened
on; browser.new_page() opens another.
None means the page’s default from
set_default_timeout(), or without one: 30,000 for
navigation and page waits (at most 120,000), and 5,000 for locators and the
selector shortcuts (at most 60,000).
Navigation
page.goto()
Navigate and return once the new document reaches wait_until.
| Parameter | Type | Default | Description |
|---|---|---|---|
url | str | required | An http, https, data or blob URL, or about:blank. |
wait_until | str | "load" | Playwright’s load states: "domcontentloaded" (the HTML is parsed), "load" (the load event fired) or "networkidle" (no network activity for 500 ms after load). |
timeout | float | None | 30000 | Milliseconds, at most 120,000. |
referer | str | None | None | Accepted for compatibility and ignored. |
NavigationError when Chrome can’t load the page (the message names
the network error, such as net::ERR_NAME_NOT_RESOLVED); InvalidArgsError for
another URL scheme (file:, chrome:, javascript:).
page.reload(), page.go_back(), page.go_forward()
page.back() and page.forward() are the same as go_back() and go_forward().
page.wait_for_load_state()
Wait until the current document reaches state: "domcontentloaded",
"load" or "networkidle". Returns at once if it already has.
page.wait_for_url()
Wait until the page’s URL matches, then until the page reaches wait_until.
| Parameter | Type | Default | Description |
|---|---|---|---|
url | str | re.Pattern | Callable[[str], bool] | required | An exact URL, a glob such as "**/checkout/*", a regular expression, or a function that takes the URL. |
wait_until | str | "load" | Load state to wait for after the URL matches. |
timeout | float | None | 30000 | Milliseconds. |
TimeoutError naming the last URL seen.
page.wait_for_timeout()
Sleep for timeout milliseconds. Prefer waiting for something specific.
Page info
page.url
The current URL. A property, as in Playwright.
Returns str.
page.title()
The document’s title. A method, as in Playwright.
Returns str.
page.content()
The page’s full HTML, doctype included.
Returns str.
page.target_id
The tab’s DCP target id. None means the session’s current tab.
Returns str | None.
Scripts
Scripts run in an isolated world by default: they share the page’s DOM, but not its JavaScript globals, and the page can’t see them. Passworld="main" to
run in the page’s own context, for example to read window.myApp.
page.evaluate()
Run JavaScript in the page and return its result.
| Parameter | Type | Default | Description |
|---|---|---|---|
expression | str | required | An expression ("document.title"), a function called with arg ("x => x * 2"), or a function body ("return location.href"). A returned promise is awaited. |
arg | Any | none | One JSON value passed to the function. Pass a list to send several: "([a, b]) => a + b", [1, 2]. |
world | str | None | "isolated" | "isolated" or "main". |
timeout | float | None | 30000 | Milliseconds. |
EvaluationError when the script throws (with its stack);
InvalidArgsError for a result larger than 1 MiB.
page.wait_for_function()
Run expression until it returns something truthy, and return that value.
| Parameter | Type | Default | Description |
|---|---|---|---|
polling | float | str | "raf" | "raf" runs it every animation frame; a number is an interval in milliseconds. |
expression, arg, world and timeout are as on evaluate.
page.set_content()
Replace the page’s document with html and wait for it to load.
page.eval_on_selector() and page.eval_on_selector_all()
Playwright’s $eval and $$eval: page.locator(selector).evaluate(expression, arg)
and .evaluate_all(expression, arg).
page.add_init_script()
Not available on browser sessions yet. Raises UnsupportedError.
Locators
page.locator()
Elements matching a Playwright selector string: CSS, text=, xpath= or
//..., >> chains, :has-text(), :visible and the rest.
locator.filter() does.
Returns Locator.
page.get_by_role()
Elements by accessibility role and accessible name. The most robust way to find
something.
| Parameter | Type | Default | Description |
|---|---|---|---|
role | str | required | An ARIA role: "button", "link", "textbox", "checkbox", "heading"… |
name | str | re.Pattern | None | None | The accessible name: a case-insensitive substring unless exact, or a regular expression. |
exact | bool | False | Match name exactly. |
checked, disabled, selected, expanded, pressed | bool | None | None | Require that state. |
level | int | None | None | Heading level. |
include_hidden | bool | None | None | Also match hidden elements. |
Locator.
page.get_by_text() and the other get_by_* methods
text is a string (a case-insensitive substring unless exact=True) or a
regular expression. get_by_test_id matches data-testid.
get_by_text also takes strategy="vision": the text is then read off a
screenshot (OCR), which finds text drawn on a canvas or inside an image. See
How a locator resolves.
Returns Locator.
page.get_by_query()
The element a plain description names, such as "the add to cart button for the blue shirt", picked by a model.
| Parameter | Type | Default | Description |
|---|---|---|---|
query | str | required | What the element is, in plain words. |
strategy | str | None | None | "vision" finds the spot on a screenshot instead of among the page’s elements. |
model | str | None | None | "decision" (the default), "llm", or a model name. See below. |
Locator.
How a locator resolves
get_by_query, get_by_text and locator.with_options()
take strategy and model. On a computer or a phone, strategy also takes
"accessibility", the accessibility tree only.
strategy | What finds the element |
|---|---|
None or "auto" | The page’s DOM. A query goes to a model that picks among the elements. |
"dom" | The DOM only. |
"vision" | A screenshot: OCR for text, a vision model for a query. Use it for canvas, images and video. The action then clicks or types at that point on the screen. |
model | Use it for |
|---|---|
None or "decision" | Most queries. A small, fast model that answers with the number of the element it picks, in well under a second. |
"llm" | Long or subtle descriptions the fast model gets wrong. A general model, slower and more expensive. |
A model name, such as "anthropic/claude-sonnet-5" | Pinning one model. |
page.wait_for_selector()
Wait for selector to reach state: "attached", "detached", "visible" or "hidden".
Locator, or None for "hidden" and "detached".
Selector shortcuts
Each takes a selector string first and does what the same method does onpage.locator(selector), with the same keyword arguments. They keep older
Playwright scripts running; new code reads better with locators.
| Shortcut | Same as |
|---|---|
page.click(selector, **options) | locator.click(**options) |
page.dblclick(selector, **options) | locator.dblclick(**options) |
page.tap(selector, **options) | locator.click(**options) |
page.fill(selector, value, **options) | locator.fill(value, **options) |
page.type(selector, text, **options) | locator.press_sequentially(text, **options) |
page.press(selector, key, **options) | locator.press(key, **options) |
page.hover(selector, **options) | locator.hover(**options) |
page.focus(selector, **options) | locator.focus(**options) |
page.check(selector), uncheck, set_checked(selector, checked) | locator.check() and so on |
page.select_option(selector, value=None, **options) | locator.select_option(value, **options) |
page.dispatch_event(selector, type, event_init=None) | locator.dispatch_event(type, event_init) |
page.drag_and_drop(source, target, **options) | page.locator(source).drag_to(page.locator(target)) |
page.inner_text(selector), inner_html, text_content, input_value, get_attribute(selector, name) | the same reads |
page.is_visible(selector), is_hidden, is_enabled, is_disabled, is_editable, is_checked | the same checks |
Dialogs
A page dialog is analert, confirm, prompt or beforeunload. With no
listener, alert, confirm and prompt are dismissed and beforeunload is
accepted, as in Playwright, so a dialog never blocks your script.
page.on(), page.once(), page.remove_listener()
Listen for "dialog". While a listener is registered, the page holds each
dialog open until a listener calls dialog.accept() or dialog.dismiss().
DialogOpenError. Once the last listener is removed, the defaults apply again.
Raises UnsupportedError for any event other than "dialog".
Dialog
What a listener receives, and what expect_event("dialog") returns.
| Member | Type | Description |
|---|---|---|
type | str | "alert", "confirm", "prompt" or "beforeunload". |
message | str | The dialog’s text. |
default_value | str | A prompt’s default text. |
url | str | The page that opened it. |
state | str | "open", "accepted" or "dismissed". A dialog the default already answered says how. |
page | Page | The page it belongs to. |
accept(prompt_text=None) | None | Accept it, typing prompt_text into a prompt. |
dismiss() | None | Dismiss it. |
InvalidArgsError.
Downloads
page.expect_download()
Wait for the download that the code inside the block starts. The block ends
once the download has finished. There is no save dialog.
| Parameter | Type | Default | Description |
|---|---|---|---|
timeout | float | None | 30000 | Milliseconds to wait, at most 120,000. |
value is a Download once
the block ends. Raises TimeoutError when no download finishes in time.
Download
The file is in the session’s machine until you copy it here.
| Member | Type | Description |
|---|---|---|
url | str | Where it was downloaded from. |
suggested_filename | str | The file name the site gave it. |
size_bytes | int | Its size. |
page | Page | The page that started it. |
failure() | str | None | Why it failed, or None when it finished. |
save_as(path) | None | Copy the file to path on your machine. |
path() | Path | Copy it to a temporary folder on your machine (once) and return that path. |
save_as() and path() raise NavigationError for a failed download.
Events
page.expect_event() and page.wait_for_event()
Wait for a "dialog" (a Dialog) or a "download" (a
Download). expect_event watches for one that the code inside
its block causes. wait_for_event waits for the next one.
"dialog" listener, the default has already answered the dialog by
the time you get it; its state says how.
page.expect_popup() waits for the tab that the code in the block opens, from
a target=_blank link or window.open, and returns its Page:
Frames
Locators on a page look in its main frame. To reach inside an<iframe>, use
frame_locator(), or get a Frame from frames or frame(). Cross-origin
frames work too.
page.frame_locator()
The frame an <iframe> element shows. selector is a CSS selector for the
<iframe>. If the page replaces the <iframe>, the next call finds it again.
FrameLocator. The <iframe> is found
on first use, waiting for it like any locator. Raises TimeoutError then
when no element matches, and InvalidArgsError when the selector isn’t CSS or
the element isn’t an <iframe> or <frame>.
page.frames, page.main_frame, page.frame()
frame() returns the first frame whose name attribute is name, or whose
URL matches url (a glob, a regular expression or a function, as
wait_for_url takes), or None.
Returns list[Frame], Frame, or Frame | None.
Frame and FrameLocator
A Frame has the page’s locator builders and evaluate, scoped to the frame.
A FrameLocator has the same members.
| Member | Description |
|---|---|
locator(), every get_by_*() | Elements inside the frame, as on Page. |
evaluate(expression, arg=..., *, world=None, timeout=None) | Run a script in the frame. |
frame_locator(selector) | An <iframe> inside this frame. |
name, url | The frame’s name attribute and URL when it was listed. |
page | The page the frame belongs to. |
parent_frame, child_frames | The frames around it. |
is_detached() | Whether the frame is gone from the page. |
owner | FrameLocator only: the <iframe> element as a Locator. |
aria_snapshot() and get_text()
read the main frame only.
Uploads
page.set_input_files()
page.locator(selector).set_input_files(files).
Screenshots and structure
page.screenshot()
A PNG of the viewport, or a JPEG. A tab other than the current one is brought
to the front first, since only the visible tab is on screen.
| Parameter | Type | Default | Description |
|---|---|---|---|
path | str | None | None | Also write the image to this file. |
full_page | bool | False | Not available yet: True raises UnsupportedError. |
type | str | "png" | "png" or "jpeg". |
quality | int | None | 80 for JPEG | JPEG quality from 1 to 100. Only with type="jpeg". |
bytes. Raises ValueError for another type, or a quality
with PNG.
page.observe()
The tab as it looks: every piece of text OCR reads off a screenshot, and every
icon, each with its box. Useful on canvas pages and anything else the DOM
doesn’t describe. The tab is brought to the front first.
| Parameter | Type | Default | Description |
|---|---|---|---|
ocr_engine | str | "free" | "free" or "premium". Premium reads harder screens. |
Screen. Its
boxes are in the coordinates page.mouse.click() takes.
page.aria_snapshot()
The page’s accessibility tree as Playwright’s YAML aria snapshot: one line per
element with its role, accessible name and state.
| Parameter | Type | Default | Description |
|---|---|---|---|
timeout | float | None | 5000 | Milliseconds. |
refs | bool | False | Tag every element a pointer can reach with [ref=eN], and include hidden elements. Act on one with page.get_by_ref(). |
compact | bool | False | Drop unnamed wrapper elements that carry no name, text or state. Often a fifth of the lines or more. |
max_chars | int | None | 20000 | Most characters to return, up to 200,000. |
offset | int | 0 | Characters to skip first, to read on from a cut snapshot. |
get_by_role(role, name=...) matches. Password and
one-time-code fields read [redacted]. A snapshot longer than max_chars is
cut at a line, and its last line is a marker naming the offset to read on
from. To read one region, use page.locator(...).aria_snapshot(). Only the
main frame is read.
Returns str.
page.get_by_ref()
The element a [ref=eN] in aria_snapshot(refs=True) names.
page.locator("aria-ref=eN") is the same, as in Playwright.
StaleNodeError; take a new snapshot.
Returns Locator.
page.get_text()
The page’s visible text as near-markdown, for reading: headings as #, links
as [text](url), list items as - , table rows as cells joined with |.
Hidden content, scripts and form field values are left out. Only the main
frame is read.
| Parameter | Type | Default | Description |
|---|---|---|---|
timeout | float | None | 5000 | Milliseconds. |
max_chars | int | None | 20000 | Most characters to return, up to 200,000. |
offset | int | 0 | Characters to skip first. |
str.
page.read_text()
get_text() with its paging, so you know whether there is more.
TextPage with text (str), total_chars (int) and
next_offset (int | None, where the rest starts; None at the end).
Viewport and tabs
page.set_viewport_size()
Resize the browser so the page’s viewport is {"width", "height"} CSS pixels.
A size larger than the session’s screen is clamped. The session has one window,
so every tab shares the size.
page.viewport_size
Returns {"width": int, "height": int}.
page.bring_to_front()
Make this tab the session’s current tab.
page.close() and page.is_closed()
Close this tab, and whether it has been closed.
page.context
Returns BrowserContext.
page.keyboard and page.mouse
See Keyboard and Mouse.
page.set_default_timeout()
The timeout, in milliseconds, for every call on this page that waits and isn’t
given its own timeout: navigation, load waits, scripts, and the page’s
locators (in its frames too). A locator call waits at most 60,000 ms, so a
longer default is cut to that for locators. 0 restores the defaults: 5,000
for locators, 30,000 for navigation.
expect() assertions keep their own default; see expect.
page.set_default_navigation_timeout()
The timeout, in milliseconds, for navigation and load waits on this page
(goto, reload, go_back, go_forward, set_content,
wait_for_load_state). It takes precedence over set_default_timeout() for
them.