原生 Frame

原生 API 目录 · 手册目录

方法与属性索引

• add_script_tag
• add_style_tag
• check
• child_frames
• click
• content
• dblclick
• dispatch_event
• drag_and_drop
• eval_on_selector
• eval_on_selector_all
• evaluate
• evaluate_handle
• expect_navigation
• fill
• focus
• frame_element
• frame_locator
• get_attribute
• get_by_alt_text
• get_by_label
• get_by_placeholder
• get_by_role
• get_by_test_id
• get_by_text
• get_by_title
• goto
• hover
• inner_html
• inner_text
• input_value
• is_checked
• is_detached
• is_disabled
• is_editable
• is_enabled
• is_hidden
• is_visible
• locator
• name
• on
• once
• page
• parent_frame
• press
• query_selector
• query_selector_all
• remove_listener
• select_option
• set_checked
• set_content
• set_input_files
• tap
• text_content
• title
• type
• uncheck
• url
• wait_for_function
• wait_for_load_state
• wait_for_selector
• wait_for_timeout
• wait_for_url
• webmcp

add_script_tag

同步

def add_script_tag(self, *, content: Optional[str] = None, path: Union[pathlib.Path, str, NoneType] = None, type: Optional[str] = None, url: Optional[str] = None) -> 'ElementHandle'

Frame.add_script_tag

Returns the added tag when the script's onload fires or when the script content was injected into frame.

Adds a <script> tag into the page with the desired url or content.

Parameters

Returns

ElementHandle

异步

async def add_script_tag(self, *, content: Optional[str] = None, path: Union[pathlib.Path, str, NoneType] = None, type: Optional[str] = None, url: Optional[str] = None) -> 'ElementHandle'

Frame.add_script_tag

Returns the added tag when the script's onload fires or when the script content was injected into frame.

Adds a <script> tag into the page with the desired url or content.

Parameters

Returns

ElementHandle

add_style_tag

同步

def add_style_tag(self, *, content: Optional[str] = None, path: Union[pathlib.Path, str, NoneType] = None, url: Optional[str] = None) -> 'ElementHandle'

Frame.add_style_tag

Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.

Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content.

Parameters

Returns

ElementHandle

异步

async def add_style_tag(self, *, content: Optional[str] = None, path: Union[pathlib.Path, str, NoneType] = None, url: Optional[str] = None) -> 'ElementHandle'

Frame.add_style_tag

Returns the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.

Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content.

Parameters

Returns

ElementHandle

check

同步

def check(self, selector: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.check

This method checks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
3. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
4. Scroll the element into view if needed.
5. Use page.mouse to click in the center of the element.
6. Ensure that the element is now checked. If not, this method throws.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

异步

async def check(self, selector: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.check

This method checks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Ensure that matched element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
3. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
4. Scroll the element into view if needed.
5. Use page.mouse to click in the center of the element.
6. Ensure that the element is now checked. If not, this method throws.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

child_frames

属性，直接读取；异步入口也不加 await。

Frame.child_frames: typing.List[ForwardRef('Frame')]

Frame.child_frames

Returns

List[Frame]

click

同步

def click(self, selector: str, *, button: Optional[Literal['left', 'middle', 'right']] = None, click_count: Optional[int] = None, delay: Optional[float] = None, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.click

This method clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to click in the center of the element, or the specified position.
5. Wait for initiated navigations to either succeed or fail, unless no_wait_after option is set.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

异步

async def click(self, selector: str, *, button: Optional[Literal['left', 'middle', 'right']] = None, click_count: Optional[int] = None, delay: Optional[float] = None, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.click

This method clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to click in the center of the element, or the specified position.
5. Wait for initiated navigations to either succeed or fail, unless no_wait_after option is set.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

content

同步

def content(self, *, include_shadow: Optional[bool] = None) -> str

Frame.content

Gets the full HTML contents of the frame, including the doctype.

Parameters

Returns

str

异步

async def content(self, *, include_shadow: Optional[bool] = None) -> str

Frame.content

Gets the full HTML contents of the frame, including the doctype.

Parameters

Returns

str

dblclick

同步

def dblclick(self, selector: str, *, button: Optional[Literal['left', 'middle', 'right']] = None, delay: Optional[float] = None, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.dblclick

This method double clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to double click in the center of the element, or the specified position. if the first click of the dblclick() triggers a navigation event, this method will throw.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

NOTE frame.dblclick() dispatches two click events and a single dblclick event.

Parameters

异步

async def dblclick(self, selector: str, *, button: Optional[Literal['left', 'middle', 'right']] = None, delay: Optional[float] = None, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.dblclick

This method double clicks an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to double click in the center of the element, or the specified position. if the first click of the dblclick() triggers a navigation event, this method will throw.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

NOTE frame.dblclick() dispatches two click events and a single dblclick event.

Parameters

dispatch_event

同步

def dispatch_event(self, selector: str, type: str, event_init: Optional[Dict] = None, *, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Frame.dispatch_event

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

frame.dispatch_event("button#submit", "click")

Under the hood, it creates an instance of an event based on the given type, initializes it with event_init properties and dispatches it on the element. Events are composed, cancelable and bubble by default.

Since event_init is event-specific, please refer to the events documentation for the lists of initial properties:

• DeviceMotionEvent
• DeviceOrientationEvent
• DragEvent
• Event
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• WheelEvent

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 data_transfer in chromium and firefox
data_transfer = frame.evaluate_handle("new DataTransfer()")
frame.dispatch_event("#source", "dragstart", { "dataTransfer": data_transfer })

Parameters

异步

async def dispatch_event(self, selector: str, type: str, event_init: Optional[Dict] = None, *, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Frame.dispatch_event

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 frame.dispatch_event("button#submit", "click")

Under the hood, it creates an instance of an event based on the given type, initializes it with event_init properties and dispatches it on the element. Events are composed, cancelable and bubble by default.

Since event_init is event-specific, please refer to the events documentation for the lists of initial properties:

• DeviceMotionEvent
• DeviceOrientationEvent
• DragEvent
• Event
• FocusEvent
• KeyboardEvent
• MouseEvent
• PointerEvent
• TouchEvent
• WheelEvent

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 data_transfer in chromium and firefox
data_transfer = await frame.evaluate_handle("new DataTransfer()")
await frame.dispatch_event("#source", "dragstart", { "dataTransfer": data_transfer })

Parameters

drag_and_drop

同步

def drag_and_drop(self, source: str, target: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, scroll: Optional[Literal['auto', 'none']] = None, source_position: Optional[patchright._impl._api_structures.Position] = None, steps: Optional[int] = None, strict: Optional[bool] = None, target_position: Optional[patchright._impl._api_structures.Position] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.drag_and_drop

Parameters

异步

async def drag_and_drop(self, source: str, target: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, scroll: Optional[Literal['auto', 'none']] = None, source_position: Optional[patchright._impl._api_structures.Position] = None, steps: Optional[int] = None, strict: Optional[bool] = None, target_position: Optional[patchright._impl._api_structures.Position] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.drag_and_drop

Parameters

eval_on_selector

同步

def eval_on_selector(self, selector: str, expression: str, arg: Optional[Any] = None, *, strict: Optional[bool] = None) -> Any

Frame.eval_on_selector

Returns the return value of expression.

The method finds an element matching the specified selector within the frame and passes it as a first argument to expression. If no elements match the selector, the method throws an error.

If expression returns a [Promise], then frame.eval_on_selector() would wait for the promise to resolve and return its value.

Usage

search_value = frame.eval_on_selector("#search", "el => el.value")
preload_href = frame.eval_on_selector("link[rel=preload]", "el => el.href")
html = frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello")

Parameters

Returns

Any

异步

async def eval_on_selector(self, selector: str, expression: str, arg: Optional[Any] = None, *, strict: Optional[bool] = None) -> Any

Frame.eval_on_selector

Returns the return value of expression.

The method finds an element matching the specified selector within the frame and passes it as a first argument to expression. If no elements match the selector, the method throws an error.

If expression returns a [Promise], then frame.eval_on_selector() would wait for the promise to resolve and return its value.

Usage

search_value = await frame.eval_on_selector("#search", "el => el.value")
preload_href = await frame.eval_on_selector("link[rel=preload]", "el => el.href")
html = await frame.eval_on_selector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello")

Parameters

Returns

Any

eval_on_selector_all

同步

def eval_on_selector_all(self, selector: str, expression: str, arg: Optional[Any] = None) -> Any

Frame.eval_on_selector_all

Returns the return value of expression.

The method finds all elements matching the specified selector within the frame and passes an array of matched elements as a first argument to expression.

If expression returns a [Promise], then frame.eval_on_selector_all() would wait for the promise to resolve and return its value.

Usage

divs_counts = frame.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10)

Parameters

Returns

Any

异步

async def eval_on_selector_all(self, selector: str, expression: str, arg: Optional[Any] = None) -> Any

Frame.eval_on_selector_all

Returns the return value of expression.

The method finds all elements matching the specified selector within the frame and passes an array of matched elements as a first argument to expression.

If expression returns a [Promise], then frame.eval_on_selector_all() would wait for the promise to resolve and return its value.

Usage

divs_counts = await frame.eval_on_selector_all("div", "(divs, min) => divs.length >= min", 10)

Parameters

Returns

Any

evaluate

同步

def evaluate(self, expression: str, arg: Optional[Any] = None, *, isolated_context: Optional[bool] = True) -> Any

Frame.evaluate

Returns the return value of expression.

If the function passed to the frame.evaluate() returns a [Promise], then frame.evaluate() would wait for the promise to resolve and return its value.

If the function passed to the frame.evaluate() returns a non-[Serializable] value, then frame.evaluate() returns undefined. Playwright also supports transferring some additional values that are not serializable by JSON: -0, NaN, Infinity, -Infinity.

Usage

result = frame.evaluate("([x, y]) => Promise.resolve(x * y)", [7, 8])
print(result) # prints "56"

A string can also be passed in instead of a function.

print(frame.evaluate("1 + 2")) # prints "3"
x = 10
print(frame.evaluate(f"1 + {x}")) # prints "11"

ElementHandle instances can be passed as an argument to the frame.evaluate():

body_handle = frame.evaluate_handle("document.body")
html = frame.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
body_handle.dispose()

Parameters

Returns

Any

异步

async def evaluate(self, expression: str, arg: Optional[Any] = None, *, isolated_context: Optional[bool] = True) -> Any

Frame.evaluate

Returns the return value of expression.

If the function passed to the frame.evaluate() returns a [Promise], then frame.evaluate() would wait for the promise to resolve and return its value.

If the function passed to the frame.evaluate() returns a non-[Serializable] value, then frame.evaluate() returns undefined. Playwright also supports transferring some additional values that are not serializable by JSON: -0, NaN, Infinity, -Infinity.

Usage

result = await frame.evaluate("([x, y]) => Promise.resolve(x * y)", [7, 8])
print(result) # prints "56"

A string can also be passed in instead of a function.

print(await frame.evaluate("1 + 2")) # prints "3"
x = 10
print(await frame.evaluate(f"1 + {x}")) # prints "11"

ElementHandle instances can be passed as an argument to the frame.evaluate():

body_handle = await frame.evaluate_handle("document.body")
html = await frame.evaluate("([body, suffix]) => body.innerHTML + suffix", [body_handle, "hello"])
await body_handle.dispose()

Parameters

Returns

Any

evaluate_handle

同步

def evaluate_handle(self, expression: str, arg: Optional[Any] = None, *, isolated_context: Optional[bool] = True) -> 'JSHandle'

Frame.evaluate_handle

Returns the return value of expression as a JSHandle.

The only difference between frame.evaluate() and frame.evaluate_handle() is that frame.evaluate_handle() returns JSHandle.

If the function, passed to the frame.evaluate_handle(), returns a [Promise], then frame.evaluate_handle() would wait for the promise to resolve and return its value.

Usage

a_window_handle = frame.evaluate_handle("Promise.resolve(window)")
a_window_handle # handle for the window object.

A string can also be passed in instead of a function.

a_handle = frame.evaluate_handle("document") # handle for the "document"

JSHandle instances can be passed as an argument to the frame.evaluate_handle():

a_handle = frame.evaluate_handle("document.body")
result_handle = frame.evaluate_handle("body => body.innerHTML", a_handle)
print(result_handle.json_value())
result_handle.dispose()

Parameters

Returns

JSHandle

异步

async def evaluate_handle(self, expression: str, arg: Optional[Any] = None, *, isolated_context: Optional[bool] = True) -> 'JSHandle'

Frame.evaluate_handle

Returns the return value of expression as a JSHandle.

The only difference between frame.evaluate() and frame.evaluate_handle() is that frame.evaluate_handle() returns JSHandle.

If the function, passed to the frame.evaluate_handle(), returns a [Promise], then frame.evaluate_handle() would wait for the promise to resolve and return its value.

Usage

a_window_handle = await frame.evaluate_handle("Promise.resolve(window)")
a_window_handle # handle for the window object.

A string can also be passed in instead of a function.

a_handle = await frame.evaluate_handle("document") # handle for the "document"

JSHandle instances can be passed as an argument to the frame.evaluate_handle():

a_handle = await frame.evaluate_handle("document.body")
result_handle = await frame.evaluate_handle("body => body.innerHTML", a_handle)
print(await result_handle.json_value())
await result_handle.dispose()

Parameters

Returns

JSHandle

expect_navigation

同步

def expect_navigation(self, *, timeout: Union[float, datetime.timedelta, NoneType] = None, url: Union[str, Pattern[str], Callable[[str], bool], NoneType] = None, wait_until: Optional[Literal['commit', 'domcontentloaded', 'load', 'networkidle']] = None) -> patchright._impl._sync_base.EventContextManager[ForwardRef('Response')]

Frame.expect_navigation

Waits for the frame navigation and returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with null.

Usage

This method waits for the frame to navigate to a new URL. It is useful for when you run code which will indirectly cause the frame to navigate. Consider this example:

with frame.expect_navigation():
    frame.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
# Resolves after navigation has finished

NOTE Usage of the History API to change the URL is considered a navigation.

Parameters

Returns

EventContextManager[Response]

异步

def expect_navigation(self, *, timeout: Union[float, datetime.timedelta, NoneType] = None, url: Union[str, Pattern[str], Callable[[str], bool], NoneType] = None, wait_until: Optional[Literal['commit', 'domcontentloaded', 'load', 'networkidle']] = None) -> patchright._impl._async_base.AsyncEventContextManager[ForwardRef('Response')]

Frame.expect_navigation

Waits for the frame navigation and returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with null.

Usage

This method waits for the frame to navigate to a new URL. It is useful for when you run code which will indirectly cause the frame to navigate. Consider this example:

async with frame.expect_navigation():
    await frame.click("a.delayed-navigation") # clicking the link will indirectly cause a navigation
# Resolves after navigation has finished

NOTE Usage of the History API to change the URL is considered a navigation.

Parameters

Returns

EventContextManager[Response]

fill

同步

def fill(self, selector: str, value: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Frame.fill

This method waits for an element matching selector, 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.press_sequentially().

Parameters

异步

async def fill(self, selector: str, value: str, *, force: Optional[bool] = None, no_wait_after: Optional[bool] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Frame.fill

This method waits for an element matching selector, 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.press_sequentially().

Parameters

focus

同步

def focus(self, selector: str, *, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Frame.focus

This method fetches an element with selector and focuses it. If there's no element matching selector, the method waits until a matching element appears in the DOM.

Parameters

异步

async def focus(self, selector: str, *, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Frame.focus

This method fetches an element with selector and focuses it. If there's no element matching selector, the method waits until a matching element appears in the DOM.

Parameters

frame_element

同步

def frame_element(self) -> 'ElementHandle'

Frame.frame_element

Returns the frame or iframe element handle which corresponds to this frame.

This is an inverse of element_handle.content_frame(). Note that returned handle actually belongs to the parent frame.

This method throws an error if the frame has been detached before frameElement() returns.

Usage

frame_element = frame.frame_element()
content_frame = frame_element.content_frame()
assert frame == content_frame

Returns

ElementHandle

异步

async def frame_element(self) -> 'ElementHandle'

Frame.frame_element

Returns the frame or iframe element handle which corresponds to this frame.

This is an inverse of element_handle.content_frame(). Note that returned handle actually belongs to the parent frame.

This method throws an error if the frame has been detached before frameElement() returns.

Usage

frame_element = await frame.frame_element()
content_frame = await frame_element.content_frame()
assert frame == content_frame

Returns

ElementHandle

frame_locator

同步

def frame_locator(self, selector: Optional[str] = None) -> 'FrameLocator'

Frame.frame_locator

When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in that iframe.

When called without selector, the search starts in this frame or in any of the iframes inside it, so that you don't need to locate each iframe first. Note that the rest of the locator is resolved inside a single frame, just like any other locator. If it matches elements inside multiple frames, an error is thrown.

Usage

Following snippet locates element with text "Submit" in the iframe with id my-frame, like <iframe id="my-frame">:

locator = frame.frame_locator("#my-iframe").get_by_text("Submit")
locator.click()

Following snippet locates a button, either in the frame or in one of the iframes inside it:

locator = frame.frame_locator().get_by_role("button")
locator.click()

Parameters

Returns

FrameLocator

异步

def frame_locator(self, selector: Optional[str] = None) -> 'FrameLocator'

Frame.frame_locator

When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in that iframe.

When called without selector, the search starts in this frame or in any of the iframes inside it, so that you don't need to locate each iframe first. Note that the rest of the locator is resolved inside a single frame, just like any other locator. If it matches elements inside multiple frames, an error is thrown.

Usage

Following snippet locates element with text "Submit" in the iframe with id my-frame, like <iframe id="my-frame">:

locator = frame.frame_locator("#my-iframe").get_by_text("Submit")
await locator.click()

Following snippet locates a button, either in the frame or in one of the iframes inside it:

locator = frame.frame_locator().get_by_role("button")
await locator.click()

Parameters

Returns

FrameLocator

get_attribute

同步

def get_attribute(self, selector: str, name: str, *, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> Optional[str]

Frame.get_attribute

Returns element attribute value.

Parameters

Returns

Union[str, None]

异步

async def get_attribute(self, selector: str, name: str, *, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> Optional[str]

Frame.get_attribute

Returns element attribute value.

Parameters

Returns

Union[str, None]

get_by_alt_text

同步

def get_by_alt_text(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_alt_text

Allows locating elements by their alt text.

Usage

For example, this method will find the image by alt text "Playwright logo":

<img alt='Playwright logo'>

page.get_by_alt_text("Playwright logo").click()

Parameters

Returns

Locator

异步

def get_by_alt_text(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_alt_text

Allows locating elements by their alt text.

Usage

For example, this method will find the image by alt text "Playwright logo":

<img alt='Playwright logo'>

await page.get_by_alt_text("Playwright logo").click()

Parameters

Returns

Locator

get_by_label

同步

def get_by_label(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_label

Allows locating input elements by the text of the associated <label> or aria-labelledby element, or by the aria-label attribute.

Usage

For example, this method will find inputs by label "Username" and "Password" in the following DOM:

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

page.get_by_label("Username").fill("john")
page.get_by_label("Password").fill("secret")

Parameters

Returns

Locator

异步

def get_by_label(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_label

Allows locating input elements by the text of the associated <label> or aria-labelledby element, or by the aria-label attribute.

Usage

For example, this method will find inputs by label "Username" and "Password" in the following DOM:

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

await page.get_by_label("Username").fill("john")
await page.get_by_label("Password").fill("secret")

Parameters

Returns

Locator

get_by_placeholder

同步

def get_by_placeholder(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_placeholder

Allows locating input elements by the placeholder text.

Usage

For example, consider the following DOM structure.

<input type="email" placeholder="name@example.com" />

You can fill the input after locating it by the placeholder text:

page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

Parameters

Returns

Locator

异步

def get_by_placeholder(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_placeholder

Allows locating input elements by the placeholder text.

Usage

For example, consider the following DOM structure.

<input type="email" placeholder="name@example.com" />

You can fill the input after locating it by the placeholder text:

await page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

Parameters

Returns

Locator

get_by_role

同步

def get_by_role(self, role: Literal['alert', 'alertdialog', 'application', 'article', 'banner', 'blockquote', 'button', 'caption', 'cell', 'checkbox', 'code', 'columnheader', 'combobox', 'complementary', 'contentinfo', 'definition', 'deletion', 'dialog', 'directory', 'document', 'emphasis', 'feed', 'figure', 'form', 'generic', 'grid', 'gridcell', 'group', 'heading', 'img', 'insertion', 'link', 'list', 'listbox', 'listitem', 'log', 'main', 'marquee', 'math', 'menu', 'menubar', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'meter', 'navigation', 'none', 'note', 'option', 'paragraph', 'presentation', 'progressbar', 'radio', 'radiogroup', 'region', 'row', 'rowgroup', 'rowheader', 'scrollbar', 'search', 'searchbox', 'separator', 'slider', 'spinbutton', 'status', 'strong', 'subscript', 'superscript', 'switch', 'tab', 'table', 'tablist', 'tabpanel', 'term', 'textbox', 'time', 'timer', 'toolbar', 'tooltip', 'tree', 'treegrid', 'treeitem'], *, checked: Optional[bool] = None, description: Union[str, Pattern[str], NoneType] = None, disabled: Optional[bool] = None, exact: Optional[bool] = None, expanded: Optional[bool] = None, include_hidden: Optional[bool] = None, level: Optional[int] = None, name: Union[str, Pattern[str], NoneType] = None, pressed: Optional[bool] = None, selected: Optional[bool] = None) -> 'Locator'

Frame.get_by_role

Allows locating elements by their ARIA role, ARIA attributes and accessible name.

Usage

Consider the following DOM structure.

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

You can locate each element by its implicit role:

expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

page.get_by_role("checkbox", name="Subscribe").check()

page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click()

Details

Role selector does not replace accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.

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.

Parameters

Returns

Locator

异步

def get_by_role(self, role: Literal['alert', 'alertdialog', 'application', 'article', 'banner', 'blockquote', 'button', 'caption', 'cell', 'checkbox', 'code', 'columnheader', 'combobox', 'complementary', 'contentinfo', 'definition', 'deletion', 'dialog', 'directory', 'document', 'emphasis', 'feed', 'figure', 'form', 'generic', 'grid', 'gridcell', 'group', 'heading', 'img', 'insertion', 'link', 'list', 'listbox', 'listitem', 'log', 'main', 'marquee', 'math', 'menu', 'menubar', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'meter', 'navigation', 'none', 'note', 'option', 'paragraph', 'presentation', 'progressbar', 'radio', 'radiogroup', 'region', 'row', 'rowgroup', 'rowheader', 'scrollbar', 'search', 'searchbox', 'separator', 'slider', 'spinbutton', 'status', 'strong', 'subscript', 'superscript', 'switch', 'tab', 'table', 'tablist', 'tabpanel', 'term', 'textbox', 'time', 'timer', 'toolbar', 'tooltip', 'tree', 'treegrid', 'treeitem'], *, checked: Optional[bool] = None, description: Union[str, Pattern[str], NoneType] = None, disabled: Optional[bool] = None, exact: Optional[bool] = None, expanded: Optional[bool] = None, include_hidden: Optional[bool] = None, level: Optional[int] = None, name: Union[str, Pattern[str], NoneType] = None, pressed: Optional[bool] = None, selected: Optional[bool] = None) -> 'Locator'

Frame.get_by_role

Allows locating elements by their ARIA role, ARIA attributes and accessible name.

Usage

Consider the following DOM structure.

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

You can locate each element by its implicit role:

await expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

await page.get_by_role("checkbox", name="Subscribe").check()

await page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click()

Details

Role selector does not replace accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.

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.

Parameters

Returns

Locator

get_by_test_id

同步

def get_by_test_id(self, test_id: Union[str, Pattern[str]]) -> 'Locator'

Frame.get_by_test_id

Locate element by the test id.

Usage

Consider the following DOM structure.

<button data-testid="directions">Itinéraire</button>

You can locate the element by its test id:

page.get_by_test_id("directions").click()

Details

By default, the data-testid attribute is used as a test id. Use selectors.set_test_id_attribute() to configure a different test id attribute if necessary.

Parameters

Returns

Locator

异步

def get_by_test_id(self, test_id: Union[str, Pattern[str]]) -> 'Locator'

Frame.get_by_test_id

Locate element by the test id.

Usage

Consider the following DOM structure.

<button data-testid="directions">Itinéraire</button>

You can locate the element by its test id:

await page.get_by_test_id("directions").click()

Details

By default, the data-testid attribute is used as a test id. Use selectors.set_test_id_attribute() to configure a different test id attribute if necessary.

Parameters

Returns

Locator

get_by_text

同步

def get_by_text(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_text

Allows locating elements that contain given text.

See also locator.filter() that allows to match by another criteria, like an accessible role, and then filter by the text content.

Usage

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.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

Details

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.

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">.

Parameters

Returns

Locator

异步

def get_by_text(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_text

Allows locating elements that contain given text.

See also locator.filter() that allows to match by another criteria, like an accessible role, and then filter by the text content.

Usage

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.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

Details

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.

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">.

Parameters

Returns

Locator

get_by_title

同步

def get_by_title(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_title

Allows locating elements by their title attribute.

Usage

Consider the following DOM structure.

<span title='Issues count'>25 issues</span>

You can check the issues count after locating it by the title text:

expect(page.get_by_title("Issues count")).to_have_text("25 issues")

Parameters

Returns

Locator

异步

def get_by_title(self, text: Union[str, Pattern[str]], *, exact: Optional[bool] = None) -> 'Locator'

Frame.get_by_title

Allows locating elements by their title attribute.

Usage

Consider the following DOM structure.

<span title='Issues count'>25 issues</span>

You can check the issues count after locating it by the title text:

await expect(page.get_by_title("Issues count")).to_have_text("25 issues")

Parameters

Returns

Locator

goto

同步

def goto(self, url: str, *, referer: Optional[str] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, wait_until: Optional[Literal['commit', 'domcontentloaded', 'load', 'networkidle']] = None) -> Optional[ForwardRef('Response')]

Frame.goto

Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.

The method will throw an error if:

• there's an SSL error (e.g. in case of self-signed certificates).
• target URL is invalid.
• the timeout is exceeded during navigation.
• the remote server does not respond or is unreachable.
• the main resource failed to load.

The method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling response.status.

NOTE The method either throws an error or returns a main resource response. The only exceptions are navigation to about:blank or navigation to the same URL with a different hash, which would succeed and return null.

NOTE Headless mode doesn't support navigation to a PDF document. See the upstream issue.

Parameters

Returns

Union[Response, None]

异步

async def goto(self, url: str, *, referer: Optional[str] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, wait_until: Optional[Literal['commit', 'domcontentloaded', 'load', 'networkidle']] = None) -> Optional[ForwardRef('Response')]

Frame.goto

Returns the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.

The method will throw an error if:

• there's an SSL error (e.g. in case of self-signed certificates).
• target URL is invalid.
• the timeout is exceeded during navigation.
• the remote server does not respond or is unreachable.
• the main resource failed to load.

The method will not throw an error when any valid HTTP status code is returned by the remote server, including 404 "Not Found" and 500 "Internal Server Error". The status code for such responses can be retrieved by calling response.status.

NOTE The method either throws an error or returns a main resource response. The only exceptions are navigation to about:blank or navigation to the same URL with a different hash, which would succeed and return null.

NOTE Headless mode doesn't support navigation to a PDF document. See the upstream issue.

Parameters

Returns

Union[Response, None]

hover

同步

def hover(self, selector: str, *, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.hover

This method hovers over an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to hover over the center of the element, or the specified position.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

异步

async def hover(self, selector: str, *, force: Optional[bool] = None, modifiers: Optional[Sequence[Literal['Alt', 'Control', 'ControlOrMeta', 'Meta', 'Shift']]] = None, no_wait_after: Optional[bool] = None, position: Optional[patchright._impl._api_structures.Position] = None, scroll: Optional[Literal['auto', 'none']] = None, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Frame.hover

This method hovers over an element matching selector by performing the following steps:

1. Find an element matching selector. If there is none, wait until a matching element is attached to the DOM.
2. Wait for actionability checks on the matched element, unless force option is set. If the element is detached during the checks, the whole action is retried.
3. Scroll the element into view if needed.
4. Use page.mouse to hover over the center of the element, or the specified position.

When all steps combined have not finished during the specified timeout, this method throws a TimeoutError. Passing zero timeout disables this.

Parameters

inner_html

同步

def inner_html(self, selector: str, *, strict: Optional[bool] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> str