原生 FrameLocator

原生 API 目录 · 手册目录

方法与属性索引

• first
• frame_locator
• get_by_alt_text
• get_by_label
• get_by_placeholder
• get_by_role
• get_by_test_id
• get_by_text
• get_by_title
• last
• locator
• nth
• on
• once
• owner
• remove_listener

first

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

FrameLocator.first: FrameLocator

FrameLocator.first

Returns locator to the first matching frame.

Returns

FrameLocator

frame_locator

同步

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

FrameLocator.frame_locator

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

Parameters

Returns

FrameLocator

异步

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

FrameLocator.frame_locator

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

Parameters

Returns

FrameLocator

get_by_alt_text

同步

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

last

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

FrameLocator.last: FrameLocator

FrameLocator.last

Returns locator to the last matching frame.

Returns

FrameLocator

locator

同步

def locator(self, selector_or_locator: Union[str, ForwardRef('Locator')], *, 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) -> 'Locator'

FrameLocator.locator

The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to locator.filter() method.

Learn more about locators.

Parameters

Returns

Locator

异步

def locator(self, selector_or_locator: Union[str, ForwardRef('Locator')], *, 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) -> 'Locator'

FrameLocator.locator

The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to locator.filter() method.

Learn more about locators.

Parameters

Returns

Locator

nth

同步

def nth(self, index: int) -> 'FrameLocator'

FrameLocator.nth

Returns locator to the n-th matching frame. It's zero based, nth(0) selects the first frame.

Parameters

Returns

FrameLocator

异步

def nth(self, index: int) -> 'FrameLocator'

FrameLocator.nth

Returns locator to the n-th matching frame. It's zero based, nth(0) selects the first frame.

Parameters

Returns

FrameLocator

on

同步

def on(self, event: Any, f: Any) -> None

Registers the function f to the event name event.

异步

def on(self, event: Any, f: Any) -> None

Registers the function f to the event name event.

once

同步

def once(self, event: Any, f: Any) -> None

The same as self.on, except that the listener is automatically removed after being called.

异步

def once(self, event: Any, f: Any) -> None

The same as self.on, except that the listener is automatically removed after being called.

owner

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

FrameLocator.owner: Locator

FrameLocator.owner

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

Useful when you have a FrameLocator object obtained somewhere, and later on would like to interact with the iframe element.

For a reverse operation, use locator.content_frame.

Usage

frame_locator = page.locator("iframe[name=\"embedded\"]").content_frame
# ...
locator = frame_locator.owner
expect(locator).to_be_visible()

Returns

Locator

remove_listener

同步

def remove_listener(self, event: Any, f: Any) -> None

Removes the function f from event.

异步

def remove_listener(self, event: Any, f: Any) -> None

Removes the function f from event.