原生 Locator

原生 API 目录 · 手册目录

方法与属性索引

• all
• all_inner_texts
• all_text_contents
• and_
• aria_snapshot
• blur
• bounding_box
• check
• clear
• click
• content_frame
• count
• dblclick
• describe
• description
• dispatch_event
• drag_to
• drop
• element_handle
• element_handles
• evaluate
• evaluate_all
• evaluate_handle
• fill
• filter
• first
• focus
• 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
• hide_highlight
• highlight
• hover
• inner_html
• inner_text
• input_value
• is_checked
• is_disabled
• is_editable
• is_enabled
• is_hidden
• is_visible
• last
• locator
• normalize
• nth
• on
• once
• or_
• page
• press
• press_sequentially
• remove_listener
• screenshot
• scroll_into_view_if_needed
• select_option
• select_text
• set_checked
• set_input_files
• tap
• text_content
• type
• uncheck
• visible
• wait_for
• wait_for_function
• within

all

同步

def all(self) -> List[ForwardRef('Locator')]

Locator.all

When the locator points to a list of elements, this returns an array of locators, pointing to their respective elements.

NOTE locator.all() does not wait for elements to match the locator, and instead immediately returns whatever is present in the page.

When the list of elements changes dynamically, locator.all() will produce unpredictable and flaky results.

When the list of elements is stable, but loaded dynamically, wait for the full list to finish loading before calling locator.all().

Usage

for li in page.get_by_role('listitem').all():
  li.click();

Returns

List[Locator]

异步

async def all(self) -> List[ForwardRef('Locator')]

Locator.all

When the locator points to a list of elements, this returns an array of locators, pointing to their respective elements.

NOTE locator.all() does not wait for elements to match the locator, and instead immediately returns whatever is present in the page.

When the list of elements changes dynamically, locator.all() will produce unpredictable and flaky results.

When the list of elements is stable, but loaded dynamically, wait for the full list to finish loading before calling locator.all().

Usage

for li in await page.get_by_role('listitem').all():
  await li.click();

Returns

List[Locator]

all_inner_texts

同步

def all_inner_texts(self) -> List[str]

Locator.all_inner_texts

Returns an array of node.innerText values for all matching nodes.

NOTE If you need to assert text on the page, prefer locator_assertions.to_have_text() with use_inner_text option to avoid flakiness. See assertions guide for more details.

Usage

texts = page.get_by_role("link").all_inner_texts()

Returns

List[str]

异步

async def all_inner_texts(self) -> List[str]

Locator.all_inner_texts

Returns an array of node.innerText values for all matching nodes.

NOTE If you need to assert text on the page, prefer locator_assertions.to_have_text() with use_inner_text option to avoid flakiness. See assertions guide for more details.

Usage

texts = await page.get_by_role("link").all_inner_texts()

Returns

List[str]

all_text_contents

同步

def all_text_contents(self) -> List[str]

Locator.all_text_contents

Returns an array of node.textContent values for all matching nodes.

NOTE If you need to assert text on the page, prefer locator_assertions.to_have_text() to avoid flakiness. See assertions guide for more details.

Usage

texts = page.get_by_role("link").all_text_contents()

Returns

List[str]

异步

async def all_text_contents(self) -> List[str]

Locator.all_text_contents

Returns an array of node.textContent values for all matching nodes.

NOTE If you need to assert text on the page, prefer locator_assertions.to_have_text() to avoid flakiness. See assertions guide for more details.

Usage

texts = await page.get_by_role("link").all_text_contents()

Returns

List[str]

and_

同步

def and_(self, locator: 'Locator') -> 'Locator'

Locator.and_

Creates a locator that matches both this locator and the argument locator.

Usage

The following example finds a button with a specific title.

button = page.get_by_role("button").and_(page.get_by_title("Subscribe"))

Parameters

Returns

Locator

异步

def and_(self, locator: 'Locator') -> 'Locator'

Locator.and_

Creates a locator that matches both this locator and the argument locator.

Usage

The following example finds a button with a specific title.

button = page.get_by_role("button").and_(page.get_by_title("Subscribe"))

Parameters

Returns

Locator

aria_snapshot

同步

def aria_snapshot(self, *, boxes: Optional[bool] = None, depth: Optional[int] = None, mode: Optional[Literal['ai', 'default']] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> str

Locator.aria_snapshot

Captures the aria snapshot of the given element. Read more about aria snapshots and locator_assertions.to_match_aria_snapshot() for the corresponding assertion.

Usage

page.get_by_role("link").aria_snapshot()

Details

This method captures the aria snapshot of the given element. The snapshot is a string that represents the state of the element and its children. The snapshot can be used to assert the state of the element in the test, or to compare it to state in the future.

The ARIA snapshot is represented using YAML markup language:

• The keys of the objects are the roles and optional accessible names of the elements.
• The values are either text content or an array of child elements.
• Generic static text can be represented with the text key.

Below is the HTML markup and the respective ARIA snapshot:

<ul aria-label="Links">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
<ul>

- list "Links":
  - listitem:
    - link "Home"
  - listitem:
    - link "About"

An AI-optimized snapshot, controlled by mode, is different from a default snapshot:

1. Includes element references [ref=e2]. 2. Does not wait for an element matching the locator, and throws when no elements match. 3. Includes snapshots of <iframe>s inside the target.

Parameters

Returns

str

异步

async def aria_snapshot(self, *, boxes: Optional[bool] = None, depth: Optional[int] = None, mode: Optional[Literal['ai', 'default']] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> str

Locator.aria_snapshot

Captures the aria snapshot of the given element. Read more about aria snapshots and locator_assertions.to_match_aria_snapshot() for the corresponding assertion.

Usage

await page.get_by_role("link").aria_snapshot()

Details

This method captures the aria snapshot of the given element. The snapshot is a string that represents the state of the element and its children. The snapshot can be used to assert the state of the element in the test, or to compare it to state in the future.

The ARIA snapshot is represented using YAML markup language:

• The keys of the objects are the roles and optional accessible names of the elements.
• The values are either text content or an array of child elements.
• Generic static text can be represented with the text key.

Below is the HTML markup and the respective ARIA snapshot:

<ul aria-label="Links">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
<ul>

- list "Links":
  - listitem:
    - link "Home"
  - listitem:
    - link "About"

An AI-optimized snapshot, controlled by mode, is different from a default snapshot:

1. Includes element references [ref=e2]. 2. Does not wait for an element matching the locator, and throws when no elements match. 3. Includes snapshots of <iframe>s inside the target.

Parameters

Returns

str

blur

同步

def blur(self, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Locator.blur

Calls blur on the element.

Parameters

异步

async def blur(self, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Locator.blur

Calls blur on the element.

Parameters

bounding_box

同步

def bounding_box(self, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> Optional[patchright._impl._api_structures.FloatRect]

Locator.bounding_box

This method returns the bounding box of the element matching the locator, 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.

Details

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

box = page.get_by_role("button").bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

Parameters

Returns

Union[{x: float, y: float, width: float, height: float}, None]

异步

async def bounding_box(self, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> Optional[patchright._impl._api_structures.FloatRect]

Locator.bounding_box

This method returns the bounding box of the element matching the locator, 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.

Details

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

box = await page.get_by_role("button").bounding_box()
await page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

Parameters

Returns

Union[{x: float, y: float, width: float, height: float}, None]

check

同步

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

Locator.check

Ensure that checkbox or radio element is checked.

Details

Performs the following steps:

1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
2. Wait for actionability checks on the element, unless force option is set.
3. Scroll the element into view if needed.
4. Use page.mouse to click in the center of the element.
5. Ensure that the element is now checked. If not, this method throws.

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.

Usage

page.get_by_role("checkbox").check()

Parameters

异步

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

Locator.check

Ensure that checkbox or radio element is checked.

Details

Performs the following steps:

1. Ensure that element is a checkbox or a radio input. If not, this method throws. If the element is already checked, this method returns immediately.
2. Wait for actionability checks on the element, unless force option is set.
3. Scroll the element into view if needed.
4. Use page.mouse to click in the center of the element.
5. Ensure that the element is now checked. If not, this method throws.

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.

Usage

await page.get_by_role("checkbox").check()

Parameters

clear

同步

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

Locator.clear

Clear the input field.

Details

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.

Usage

page.get_by_role("textbox").clear()

Parameters

异步

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

Locator.clear

Clear the input field.

Details

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.

Usage

await page.get_by_role("textbox").clear()

Parameters

click

同步

def click(self, *, 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, steps: Optional[int] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Locator.click

Click an element.

Details

This method clicks the element by performing the following steps:

1. Wait for actionability checks on the element, unless force option is set.
2. Scroll the element into view if needed.
3. Use page.mouse to click in the center of the element, or the specified position.
4. Wait for initiated navigations to either succeed or fail, unless no_wait_after 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.

Usage

Click a button:

page.get_by_role("button").click()

Shift-right-click at a specific position on a canvas:

page.locator("canvas").click(
    button="right", modifiers=["Shift"], position={"x": 23, "y": 32}
)

Parameters

异步

async def click(self, *, 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, steps: Optional[int] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Locator.click

Click an element.

Details

This method clicks the element by performing the following steps:

1. Wait for actionability checks on the element, unless force option is set.
2. Scroll the element into view if needed.
3. Use page.mouse to click in the center of the element, or the specified position.
4. Wait for initiated navigations to either succeed or fail, unless no_wait_after 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.

Usage

Click a button:

await page.get_by_role("button").click()

Shift-right-click at a specific position on a canvas:

await page.locator("canvas").click(
    button="right", modifiers=["Shift"], position={"x": 23, "y": 32}
)

Parameters

content_frame

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

Locator.content_frame: FrameLocator

Locator.content_frame

Returns a FrameLocator object pointing to the same iframe as this locator.

Useful when you have a Locator object obtained somewhere, and later on would like to interact with the content inside the frame.

For a reverse operation, use frame_locator.owner.

Usage

locator = page.locator("iframe[name=\"embedded\"]")
# ...
frame_locator = locator.content_frame
frame_locator.get_by_role("button").click()

Returns

FrameLocator

count

同步

def count(self) -> int

Locator.count

Returns the number of elements matching the locator.

NOTE If you need to assert the number of elements on the page, prefer locator_assertions.to_have_count() to avoid flakiness. See assertions guide for more details.

Usage

count = page.get_by_role("listitem").count()

Returns

int

异步

async def count(self) -> int

Locator.count

Returns the number of elements matching the locator.

NOTE If you need to assert the number of elements on the page, prefer locator_assertions.to_have_count() to avoid flakiness. See assertions guide for more details.

Usage

count = await page.get_by_role("listitem").count()

Returns

int

dblclick

同步

def dblclick(self, *, 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, steps: Optional[int] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Locator.dblclick

Double-click an element.

Details

This method double clicks the element by performing the following steps:

1. Wait for actionability checks on the element, unless force option is set.
2. Scroll the element into view if needed.
3. Use page.mouse to double click in the center of the element, or the specified position.

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.

Parameters

异步

async def dblclick(self, *, 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, steps: Optional[int] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Locator.dblclick

Double-click an element.

Details

This method double clicks the element by performing the following steps:

1. Wait for actionability checks on the element, unless force option is set.
2. Scroll the element into view if needed.
3. Use page.mouse to double click in the center of the element, or the specified position.

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.

Parameters

describe

同步

def describe(self, description: str) -> 'Locator'

Locator.describe

Describes the locator, description is used in the trace viewer and reports. Returns the locator pointing to the same element.

Usage

button = page.get_by_test_id("btn-sub").describe("Subscribe button")
button.click()

Parameters

Returns

Locator

异步

def describe(self, description: str) -> 'Locator'

Locator.describe

Describes the locator, description is used in the trace viewer and reports. Returns the locator pointing to the same element.

Usage

button = page.get_by_test_id("btn-sub").describe("Subscribe button")
await button.click()

Parameters

Returns

Locator

description

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

Locator.description: typing.Optional[str]

Locator.description

Returns locator description previously set with locator.describe(). Returns null if no custom description has been set.

Usage

button = page.get_by_role("button").describe("Subscribe button")
print(button.description())  # "Subscribe button"

input = page.get_by_role("textbox")
print(input.description())  # None

Returns

Union[str, None]

dispatch_event

同步

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

Locator.dispatch_event

Programmatically dispatch an event on the matching element.

Usage

locator.dispatch_event("click")

Details

The snippet above 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().

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:

data_transfer = page.evaluate_handle("new DataTransfer()")
locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

Parameters

异步

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

Locator.dispatch_event

Programmatically dispatch an event on the matching element.

Usage

await locator.dispatch_event("click")

Details

The snippet above 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().

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:

data_transfer = await page.evaluate_handle("new DataTransfer()")
await locator.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

Parameters

drag_to

同步

def drag_to(self, target: 'Locator', *, 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, target_position: Optional[patchright._impl._api_structures.Position] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Locator.drag_to

Drag the source element towards the target element and drop it.

Details

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

source = page.locator("#source")
target = page.locator("#target")

source.drag_to(target)
# or specify exact positions relative to the top-left corners of the elements:
source.drag_to(
  target,
  source_position={"x": 34, "y": 7},
  target_position={"x": 10, "y": 20}
)

Parameters

异步

async def drag_to(self, target: 'Locator', *, 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, target_position: Optional[patchright._impl._api_structures.Position] = None, timeout: Union[float, datetime.timedelta, NoneType] = None, trial: Optional[bool] = None) -> None

Locator.drag_to

Drag the source element towards the target element and drop it.

Details

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

source = page.locator("#source")
target = page.locator("#target")

await source.drag_to(target)
# or specify exact positions relative to the top-left corners of the elements:
await source.drag_to(
  target,
  source_position={"x": 34, "y": 7},
  target_position={"x": 10, "y": 20}
)

Parameters

drop

同步

def drop(self, payload: patchright._impl._api_structures.DropPayload, *, position: Optional[patchright._impl._api_structures.Position] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Locator.drop

Simulate an external drag-and-drop of files or clipboard-like data onto this locator.

Details

Dispatches the native dragenter, dragover, and drop events at the center of the target element with a synthetic [DataTransfer] carrying the provided files and/or data entries. Works cross-browser by constructing the [DataTransfer] in the page context.

If the target element's dragover listener does not call preventDefault(), the target is considered to have rejected the drop: Playwright dispatches dragleave and this method throws.

Usage

Drop a file buffer onto an upload area:

Drop plain text and a URL together:

Parameters

异步

async def drop(self, payload: patchright._impl._api_structures.DropPayload, *, position: Optional[patchright._impl._api_structures.Position] = None, timeout: Union[float, datetime.timedelta, NoneType] = None) -> None

Locator.drop

Simulate an external drag-and-drop of files or clipboard-like data onto this locator.

Details

Dispatches the native dragenter, dragover, and drop events at the center of the target element with a synthetic [DataTransfer] carrying the provided files and/or data entries. Works cross-browser by constructing the [DataTransfer] in the page context.

If the target element's dragover listener does not call preventDefault(), the target is considered to have rejected the drop: Playwright dispatches dragleave and this method throws.

Usage

Drop a file buffer onto an upload area:

Drop plain text and a URL together:

Parameters

element_handle

同步

def element_handle(self, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> 'ElementHandle'

Locator.element_handle

Resolves given locator to the first matching DOM element. If there are no matching elements, waits for one. If multiple elements match the locator, throws.

Parameters

Returns

ElementHandle

异步

async def element_handle(self, *, timeout: Union[float, datetime.timedelta, NoneType] = None) -> 'ElementHandle'

Locator.element_handle

Resolves given locator to the first matching DOM element. If there are no matching elements, waits for one. If multiple elements match the locator, throws.

Parameters

Returns

ElementHandle

element_handles

同步

def element_handles(self) -> List[ForwardRef('ElementHandle')]

Locator.element_handles

Resolves given locator to all matching DOM elements. If there are no matching elements, returns an empty list.

Returns

List[ElementHandle]

异步

async def element_handles(self) -> List[ForwardRef('ElementHandle')]

Locator.element_handles

Resolves given locator to all matching DOM elements. If there are no matching elements, returns an empty list.

Returns

List[ElementHandle]

evaluate

同步

def evaluate(self, expression: str, arg: Optional[Any] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None, isolated_context: Optional[bool] = True) -> Any

Locator.evaluate

Execute JavaScript code in the page, taking the matching element as an argument.

Details

Returns the return value of expression, called with the matching element as a first argument, and arg as a second argument.

If expression returns a [Promise], this method will wait for the promise to resolve and return its value.

If expression throws or rejects, this method throws.

Usage

Passing argument to expression:

result = page.get_by_testid("myId").evaluate("(element, [x, y]) => element.textContent + ' ' + x * y", [7, 8])
print(result) # prints "myId text 56"

Parameters

Returns

Any

异步

async def evaluate(self, expression: str, arg: Optional[Any] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None, isolated_context: Optional[bool] = True) -> Any

Locator.evaluate

Execute JavaScript code in the page, taking the matching element as an argument.

Details

Returns the return value of expression, called with the matching element as a first argument, and arg as a second argument.

If expression returns a [Promise], this method will wait for the promise to resolve and return its value.

If expression throws or rejects, this method throws.

Usage

Passing argument to expression:

result = await page.get_by_testid("myId").evaluate("(element, [x, y]) => element.textContent + ' ' + x * y", [7, 8])
print(result) # prints "myId text 56"

Parameters

Returns

Any

evaluate_all

同步

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

Locator.evaluate_all

Execute JavaScript code in the page, taking all matching elements as an argument.

Details

Returns the return value of expression, called with an array of all matching elements as a first argument, and arg as a second argument.

If expression returns a [Promise], this method will wait for the promise to resolve and return its value.

If expression throws or rejects, this method throws.

Usage

locator = page.locator("div")
more_than_ten = locator.evaluate_all("(divs, min) => divs.length > min", 10)

Parameters

Returns

Any

异步

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

Locator.evaluate_all

Execute JavaScript code in the page, taking all matching elements as an argument.

Details

Returns the return value of expression, called with an array of all matching elements as a first argument, and arg as a second argument.

If expression returns a [Promise], this method will wait for the promise to resolve and return its value.

If expression throws or rejects, this method throws.

Usage

locator = page.locator("div")
more_than_ten = await locator.evaluate_all("(divs, min) => divs.length > min", 10)

Parameters

Returns

Any

evaluate_handle

同步

def evaluate_handle(self, expression: str, arg: Optional[Any] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None, isolated_context: Optional[bool] = True) -> 'JSHandle'

Locator.evaluate_handle

Execute JavaScript code in the page, taking the matching element as an argument, and return a JSHandle with the result.

Details

Returns the return value of expression as aJSHandle, called with the matching element as a first argument, and arg as a second argument.

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

If expression returns a [Promise], this method will wait for the promise to resolve and return its value.

If expression throws or rejects, this method throws.

See page.evaluate_handle() for more details.

Parameters

Returns

JSHandle

异步

async def evaluate_handle(self, expression: str, arg: Optional[Any] = None, *, timeout: Union[float, datetime.timedelta, NoneType] = None, isolated_context: Optional[bool] = True) -> 'JSHandle'

Locator.evaluate_handle

Execute JavaScript code in the page, taking the matching element as an argument, and return a JSHandle with the result.

Details

Returns the return value of expression as aJSHandle, called with the matching element as a first argument, and arg as a second argument.

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

If expression returns a [Promise], this method will wait for the promise to resolve and return its value.

If expression throws or rejects, this method throws.

See page.evaluate_handle() for more details.

Parameters

Returns

JSHandle

fill

同步

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

Locator.fill

Set a value to the input field.

Usage

page.get_by_role("textbox").fill("example value")

Details

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.press_sequentially().

Parameters

异步

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

Locator.fill

Set a value to the input field.

Usage

await page.get_by_role("textbox").fill("example value")

Details

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.press_sequentially().

Parameters

filter

同步

def filter(self, *, has: Optional[ForwardRef('Locator')] = None, has_not: Optional[ForwardRef('Locator')] = None, has_not_text: Union[str, Pattern[str], NoneType] = None, has_text: Union[str, Pattern[str], NoneType] = None, visible: Optional[bool] = None) -> 'Locator'

Locator.filter

This method narrows existing locator according to the options, for example filters by text. It can be chained to filter multiple times.

Usage

row_locator = page.locator("tr")
# ...
row_locator.filter(has_text="text in column 1").filter(
    has=page.get_by_role("button", name="column 2 button")
).screenshot()

Parameters

Returns

Locator

异步

def filter(self, *, has: Optional[ForwardRef('Locator')] = None, has_not: Optional[ForwardRef('Locator')] = None, has_not_text: Union[str, Pattern[str], NoneType] = None, has_text: Union[str, Pattern[str], NoneType] = None, visible: Optional[bool] = None) -> 'Locator'

Locator.filter

This method narrows existing locator according to the options, for example filters by text. It can be chained to filter multiple times.

Usage

row_locator = page.locator("tr")
# ...
await row_locator.filter(has_text="text in column 1").filter(
    has=page.get_by_role("button", name="column 2 button")
).screenshot()

Parameters

Returns

Locator

first

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

Locator.first: Locator

Locator.first

Returns locator to the first matching element.

Returns

Locator

focus

同步

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

Locator.focus

Calls focus on the matching element.

Parameters

异步

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

Locator.focus

Calls focus on the matching element.

Parameters

frame_locator

同步

def frame_locator(self, selector: str) -> 'FrameLocator'

Locator.frame_locator

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

Usage

locator = page.frame_locator("iframe").get_by_text("Submit")
locator.click()

Parameters

Returns

FrameLocator

异步

def frame_locator(self, selector: str) -> 'FrameLocator'

Locator.frame_locator

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

Usage

locator = page.frame_locator("iframe").get_by_text("Submit")
await locator.click()

Parameters

Returns

FrameLocator

get_attribute

同步

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

Locator.get_attribute

Returns the matching element's attribute value.

NOTE If you need to assert an element's attribute, prefer locator_assertions.to_have_attribute() to avoid flakiness. See assertions guide for more details.

Parameters

Returns

Union[str, None]

异步

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

Locator.get_attribute

Returns the matching element's attribute value.

NOTE If you need to assert an element's attribute, prefer locator_assertions.to_have_attribute() to avoid flakiness. See assertions guide for more details.

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'

Locator.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'

Locator.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'

Locator.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'

Locator.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'

Locator.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'

Locator.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'

Locator.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'

Locator.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'

Locator.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'

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