A Page is one tab of the session. browser.page is the tab the session opened on; browser.new_page() opens another.
page.goto("https://example.com")
page.get_by_role("link", name="Learn more").click()
page.wait_for_url("**/domains/**")
Timeouts are milliseconds. 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).

page.goto()

Navigate and return once the new document reaches wait_until.
page.goto(url, *, wait_until="load", timeout=None, referer=None)
ParameterTypeDefaultDescription
urlstrrequiredAn http, https, data or blob URL, or about:blank.
wait_untilstr"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).
timeoutfloat | None30000Milliseconds, at most 120,000.
refererstr | NoneNoneAccepted for compatibility and ignored.
A page that answers with an error status (404, 500) still loads. Raises 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.reload(*, wait_until="load", timeout=None)
page.go_back(*, wait_until="load", timeout=None)
page.go_forward(*, wait_until="load", timeout=None)
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_load_state(state="load", *, timeout=None)

page.wait_for_url()

Wait until the page’s URL matches, then until the page reaches wait_until.
page.wait_for_url(url, *, wait_until="load", timeout=None)
ParameterTypeDefaultDescription
urlstr | re.Pattern | Callable[[str], bool]requiredAn exact URL, a glob such as "**/checkout/*", a regular expression, or a function that takes the URL.
wait_untilstr"load"Load state to wait for after the URL matches.
timeoutfloat | None30000Milliseconds.
Raises TimeoutError naming the last URL seen.

page.wait_for_timeout()

Sleep for timeout milliseconds. Prefer waiting for something specific.
page.wait_for_timeout(timeout)

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. Pass world="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.
page.evaluate(expression, arg=..., *, world=None, timeout=None)
ParameterTypeDefaultDescription
expressionstrrequiredAn expression ("document.title"), a function called with arg ("x => x * 2"), or a function body ("return location.href"). A returned promise is awaited.
argAnynoneOne JSON value passed to the function. Pass a list to send several: "([a, b]) => a + b", [1, 2].
worldstr | None"isolated""isolated" or "main".
timeoutfloat | None30000Milliseconds.
Returns the result as Python values. It must be JSON: a DOM node or a function can’t come back, so return the data you need. Raises EvaluationError when the script throws (with its stack); InvalidArgsError for a result larger than 1 MiB.
page.evaluate("document.title")
page.evaluate("() => [...document.links].map(a => a.href)")
page.evaluate("n => window.items.slice(0, n)", 10, world="main")

page.wait_for_function()

Run expression until it returns something truthy, and return that value.
page.wait_for_function(expression, arg=..., *, polling="raf", timeout=None, world=None)
ParameterTypeDefaultDescription
pollingfloat | 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.set_content(html, *, wait_until="load", timeout=None)

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.eval_on_selector(selector, expression, arg=...)
page.eval_on_selector_all(selector, 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.
page.locator(selector, *, has_text=None, has_not_text=None, has=None, has_not=None)
The keyword arguments narrow the matches as locator.filter() does. Returns Locator.

page.get_by_role()

Elements by accessibility role and accessible name. The most robust way to find something.
page.get_by_role(role, *, name=None, exact=False, checked=None, disabled=None,
                 selected=None, expanded=None, pressed=None, level=None, include_hidden=None)
ParameterTypeDefaultDescription
rolestrrequiredAn ARIA role: "button", "link", "textbox", "checkbox", "heading"…
namestr | re.Pattern | NoneNoneThe accessible name: a case-insensitive substring unless exact, or a regular expression.
exactboolFalseMatch name exactly.
checked, disabled, selected, expanded, pressedbool | NoneNoneRequire that state.
levelint | NoneNoneHeading level.
include_hiddenbool | NoneNoneAlso match hidden elements.
Returns Locator.

page.get_by_text() and the other get_by_* methods

page.get_by_text(text, *, exact=False, strategy=None, model=None, ocr_engine=None)
page.get_by_label(text, *, exact=False)
page.get_by_placeholder(text, *, exact=False)
page.get_by_alt_text(text, *, exact=False)
page.get_by_title(text, *, exact=False)
page.get_by_test_id(test_id)
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.
page.get_by_query(query, *, strategy=None, model=None)
ParameterTypeDefaultDescription
querystrrequiredWhat the element is, in plain words.
strategystr | NoneNone"vision" finds the spot on a screenshot instead of among the page’s elements.
modelstr | NoneNone"decision" (the default), "llm", or a model name. See below.
page.get_by_query("the add to cart button for the blue shirt").click()
page.get_by_query("the newsletter email field").fill("me@example.com")
By default the model chooses among the page’s real elements: every action then runs on that element, with the same waits and checks as any other locator. The model sees each candidate’s role, name and value, the text just before it and the card or row it sits in, so “the add to cart button for the blue shirt” picks the right one of several identical buttons. It also sees the page’s URL and title and the last few actions, so a query can lean on what just happened. The query is resolved again on every action, like any locator. When no element fits the description, the model says so rather than guess, and the locator matches nothing. Returns 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.
strategyWhat 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.
modelUse 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.
Model calls are billed to the session’s organization and show in the session’s telemetry.

page.wait_for_selector()

Wait for selector to reach state: "attached", "detached", "visible" or "hidden".
page.wait_for_selector(selector, *, state="visible", timeout=None)
Returns Locator, or None for "hidden" and "detached".

Selector shortcuts

Each takes a selector string first and does what the same method does on page.locator(selector), with the same keyword arguments. They keep older Playwright scripts running; new code reads better with locators.
ShortcutSame 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_checkedthe same checks

Dialogs

A page dialog is an alert, 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().
page.on("dialog", handler)
page.once("dialog", handler)            # the next dialog only
page.remove_listener("dialog", handler) # page.off() is the same
def answer(dialog):
    print(dialog.type, dialog.message)
    dialog.accept()

page.on("dialog", answer)
page.get_by_role("button", name="Delete").click()
page.get_by_text("Deleted").wait_for()   # answer() runs here
The listener runs at your next call on the page after the action that opened the dialog, not the moment it opens. That call then runs as normal. A listener that answers neither way leaves the dialog open, and that call raises 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.
MemberTypeDescription
typestr"alert", "confirm", "prompt" or "beforeunload".
messagestrThe dialog’s text.
default_valuestrA prompt’s default text.
urlstrThe page that opened it.
statestr"open", "accepted" or "dismissed". A dialog the default already answered says how.
pagePageThe page it belongs to.
accept(prompt_text=None)NoneAccept it, typing prompt_text into a prompt.
dismiss()NoneDismiss it.
Answering a dialog that is already answered raises 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.
with page.expect_download() as info:
    page.get_by_role("button", name="Export CSV").click()
download = info.value
download.save_as("export.csv")
page.expect_download(*, timeout=None)
ParameterTypeDefaultDescription
timeoutfloat | None30000Milliseconds to wait, at most 120,000.
Returns a context manager whose 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.
MemberTypeDescription
urlstrWhere it was downloaded from.
suggested_filenamestrThe file name the site gave it.
size_bytesintIts size.
pagePageThe page that started it.
failure()str | NoneWhy it failed, or None when it finished.
save_as(path)NoneCopy the file to path on your machine.
path()PathCopy 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.
with page.expect_event("dialog") as info:
    page.get_by_role("button", name="Delete").click()
print(info.value.message)

dialog = page.wait_for_event("dialog", timeout=10_000)
page.expect_event(event, *, timeout=None)
page.wait_for_event(event, *, timeout=None)
With no "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:
with page.expect_popup() as info:
    page.get_by_role("link", name="Open in new tab").click()
popup = info.value
popup.wait_for_load_state()
Input is real, so acting on a tab, the opener or the popup, brings it to the front first.

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.
pay = page.frame_locator("iframe[title='Checkout']")
pay.get_by_label("Card number").fill("4242 4242 4242 4242")
pay.get_by_role("button", name="Pay").click()

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.
page.frame_locator(selector)
Returns 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()

page.frames                    # every frame, parents before children
page.main_frame                # the top-level frame
page.frame(name=None, *, url=None)
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.
MemberDescription
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, urlThe frame’s name attribute and URL when it was listed.
pageThe page the frame belongs to.
parent_frame, child_framesThe frames around it.
is_detached()Whether the frame is gone from the page.
ownerFrameLocator only: the <iframe> element as a Locator.
A frame has no navigation of its own, and aria_snapshot() and get_text() read the main frame only.

Uploads

page.set_input_files()

page.set_input_files(selector, files, **options)
Same as 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.
page.screenshot(*, path=None, full_page=False, type="png", quality=None)
ParameterTypeDefaultDescription
pathstr | NoneNoneAlso write the image to this file.
full_pageboolFalseNot available yet: True raises UnsupportedError.
typestr"png""png" or "jpeg".
qualityint | None80 for JPEGJPEG quality from 1 to 100. Only with type="jpeg".
Returns 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.
page.observe(*, ocr_engine="free")
ParameterTypeDefaultDescription
ocr_enginestr"free""free" or "premium". Premium reads harder screens.
Returns Screen. Its boxes are in the coordinates page.mouse.click() takes.
screen = page.observe()
hit = screen.find_text("Total")
if hit:
    page.mouse.click(hit.center["x"], hit.center["y"])

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.
page.aria_snapshot(*, timeout=None, refs=False, compact=False, max_chars=None, offset=0)
ParameterTypeDefaultDescription
timeoutfloat | None5000Milliseconds.
refsboolFalseTag every element a pointer can reach with [ref=eN], and include hidden elements. Act on one with page.get_by_ref().
compactboolFalseDrop unnamed wrapper elements that carry no name, text or state. Often a fifth of the lines or more.
max_charsint | None20000Most characters to return, up to 200,000.
offsetint0Characters to skip first, to read on from a cut snapshot.
- heading "Sign in" [level=1]
- textbox "Email": ada@example.com
- textbox "Password": "[redacted]"
- checkbox "Remember me" [checked]
- button "Sign in"
The names are exactly what 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.
page.aria_snapshot(refs=True)       # ... - button "Sign in" [ref=e14]
page.get_by_ref("e14").click()
A ref names its element while it stays on the page. Once the element is gone, calls on it raise 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.
page.get_text(*, timeout=None, max_chars=None, offset=0)
ParameterTypeDefaultDescription
timeoutfloat | None5000Milliseconds.
max_charsint | None20000Most characters to return, up to 200,000.
offsetint0Characters to skip first.
Returns str.

page.read_text()

get_text() with its paging, so you know whether there is more.
page.read_text(*, timeout=None, max_chars=None, offset=0)
Returns a TextPage with text (str), total_chars (int) and next_offset (int | None, where the rest starts; None at the end).
part = page.read_text()
text = part.text
while part.next_offset is not None:
    part = page.read_text(offset=part.next_offset)
    text += part.text

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.set_viewport_size({"width": 1280, "height": 800})

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.
page.set_default_timeout(timeout)
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.
page.set_default_navigation_timeout(timeout)