FrameLocator

FrameLocator表示页面中iframe的视图。它包含了足以检索iframe并在该iframe中定位元素的逻辑。FrameLocator可以通过locator.contentFrame()、page.frameLocator()或locator.frameLocator()方法创建。

const locator = page.locator('#my-frame').contentFrame().getByText('Submit');
await locator.click();

严格性

Frame定位器是严格的。这意味着如果多个元素匹配给定的选择器，对frame定位器的所有操作都会抛出异常。

// Throws if there are several frames in DOM:
await page.locator('.result-frame').contentFrame().getByRole('button').click();

// Works because we explicitly tell locator to pick the first frame:
await page.locator('.result-frame').contentFrame().first().getByRole('button').click();

将定位器转换为框架定位器

如果您有一个指向iframe的Locator对象，可以使用locator.contentFrame()将其转换为FrameLocator。

将FrameLocator转换为Locator

如果您有一个FrameLocator对象，可以通过frameLocator.owner()将其转换为指向相同iframe的Locator。

方法​

frameLocator​

在使用iframe时，您可以创建一个框架定位器，该定位器将进入iframe并允许选择该iframe中的元素。

用法

frameLocator.frameLocator(selector);

参数

• selector string#

  解析DOM元素时使用的选择器。

返回

• FrameLocator#

getByAltText​

允许通过元素的alt文本来定位元素。

用法

例如，这个方法将通过alt文本"Playwright logo"找到图片：

<img alt='Playwright logo'>

await page.getByAltText('Playwright logo').click();

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

getByLabel​

允许通过关联<label>或aria-labelledby元素的文本内容，或者通过aria-label属性来定位输入元素。

用法

例如，这个方法将在以下DOM中通过标签"Username"和"Password"找到输入框：

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

await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

getByPlaceholder​

允许通过占位文本来定位输入元素。

用法

例如，考虑以下DOM结构。

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

您可以通过占位符文本定位后填写输入框：

await page
    .getByPlaceholder('name@example.com')
    .fill('playwright@microsoft.com');

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

getByRole​

允许通过元素的ARIA角色、ARIA属性和可访问名称来定位元素。

用法

考虑以下DOM结构。

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

您可以通过元素的隐式角色来定位每个元素：

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/i }).click();

参数

• role "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" | "meter" | "menu" | "menubar" | "menuitem" | "menuitemcheckbox" | "menuitemradio" | "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"#

  必需的aria角色。

• options Object (可选)

  • checked boolean (可选)#

    通常由aria-checked或原生<input type=checkbox>控件设置的属性。

    了解更多关于aria-checked的信息。

  • disabled boolean (可选)#

    通常由aria-disabled或disabled设置的属性。

    注意

    与大多数其他属性不同，disabled会通过DOM层次结构继承。了解更多关于aria-disabled的信息。

  • exact boolean (可选) 添加于: v1.28#

    是否精确匹配name: 区分大小写且需完全匹配整个字符串。默认为 false。当name是正则表达式时此参数会被忽略。请注意精确匹配仍会去除首尾空格。

  • expanded boolean (可选)#

    通常由aria-expanded设置的属性。

    了解更多关于aria-expanded的信息。

  • includeHidden boolean (可选)#

    控制是否匹配隐藏元素的选项。默认情况下，角色选择器仅匹配非隐藏元素，如ARIA定义的那样。

    了解更多关于aria-hidden的信息。

  • level number (可选)#

    一个数字属性，通常出现在heading、listitem、row、treeitem等角色中，对于<h1>-<h6>元素有默认值。

    了解更多关于aria-level的信息。

  • name string | RegExp (可选)#

    用于匹配accessible name的选项。默认情况下匹配不区分大小写并搜索子字符串，使用exact来控制此行为。

    了解更多关于accessible name的信息。

  • pressed boolean (可选)#

    通常由aria-pressed设置的属性。

    了解更多关于aria-pressed的信息。

  • selected boolean (可选)#

    通常由aria-selected设置的属性。

    了解更多关于aria-selected的信息。

返回

• 定位器#

详情

角色选择器不能替代无障碍审计和合规性测试，而是提供关于ARIA指南的早期反馈。

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.

getByTestId​

通过测试ID定位元素。

用法

考虑以下DOM结构。

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

您可以通过元素的测试ID来定位它：

await page.getByTestId('directions').click();

参数

• testId string | RegExp#

  用于定位元素的ID。

返回

• 定位器#

详情

默认情况下，data-testid属性被用作测试ID。如有需要，可使用selectors.setTestIdAttribute()来配置不同的测试ID属性。

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

getByText​

允许定位包含给定文本的元素。

另请参阅locator.filter()，它允许通过其他条件（如可访问角色）进行匹配，然后按文本内容进行筛选。

用法

考虑以下DOM结构：

<div>Hello <span>world</span></div>
<div>Hello</div>

您可以通过文本子字符串、精确字符串或正则表达式进行定位：

// Matches <span>
page.getByText('world');

// Matches first <div>
page.getByText('Hello world');

// Matches second <div>
page.getByText('Hello', { exact: true });

// Matches both <div>s
page.getByText(/Hello/);

// Matches second <div>
page.getByText(/^hello$/i);

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

详情

按文本匹配时总是会规范化空白字符，即使是精确匹配。例如，它会将多个空格转换为一个，将换行符转换为空格，并忽略开头和结尾的空白字符。

类型为button和submit的输入元素是通过它们的value值而非文本内容来匹配的。例如，通过文本"Log in"定位会匹配到<input type=button value="Log in">。

getByTitle​

允许通过元素的title属性来定位元素。

用法

考虑以下DOM结构。

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

您可以通过标题文本定位后检查问题数量：

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

参数

• text string | RegExp#

  用于定位元素的文本。

• options Object (可选)

  • exact boolean (可选)#

    是否查找完全匹配：区分大小写且全字符串匹配。默认为false。使用正则表达式定位时忽略此选项。请注意完全匹配仍会去除空白字符。

返回

• 定位器#

定位器​

该方法在定位器的子树中查找与指定选择器匹配的元素。它还接受过滤选项，类似于locator.filter()方法。

了解更多关于定位器的信息。

用法

frameLocator.locator(selectorOrLocator);
frameLocator.locator(selectorOrLocator, options);

参数

• selectorOrLocator string | Locator#

  用于解析DOM元素时使用的选择器或定位器。

• options Object (可选)

  • has Locator (可选)#

    将方法的结果范围缩小到包含匹配此相对定位器的元素。例如，article 包含 text=Playwright 会匹配 <article><div>Playwright</div></article>。

    内部定位器必须相对于外部定位器，并且从外部定位器匹配开始查询，而不是文档根目录。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到包含 div 的 content。但是，查找包含 article div 的 content 会失败，因为内部定位器必须是相对的，不应使用 content 之外的任何元素。

    请注意，外部和内部定位器必须属于同一框架。内部定位器不得包含 FrameLocator。

  • hasNot Locator (可选) 新增于: v1.33#

    匹配不包含符合内部定位器元素的元素。内部定位器会针对外部元素进行查询。例如，article元素不包含div时，会匹配<article><span>Playwright</span></article>。

    请注意外部和内部定位器必须属于同一个框架。内部定位器不能包含FrameLocator。

  • hasNotText string | RegExp (可选) 添加于: v1.33#

    匹配内部某处不包含指定文本的元素，可能在子元素或后代元素中。当传入string时，匹配不区分大小写并搜索子字符串。

  • hasText string | RegExp (可选)#

    匹配内部某处包含指定文本的元素，可能在子元素或后代元素中。当传入string时，匹配不区分大小写并搜索子字符串。例如，"Playwright"会匹配<article><div>Playwright</div></article>。

返回

• 定位器#

所有者​

返回一个Locator对象，指向与此帧定位器相同的iframe。

当您已获得某个FrameLocator对象，并稍后需要与iframe元素进行交互时，此功能非常有用。

对于反向操作，使用 locator.contentFrame()。

用法

const frameLocator = page.locator('iframe[name="embedded"]').contentFrame();
// ...
const locator = frameLocator.owner();
await expect(locator).toBeVisible();

返回

• 定位器#

已弃用​

第一个​

返回定位器到第一个匹配的框架。

用法

frameLocator.first();

返回

• FrameLocator#

最后​

返回定位器到最后一个匹配的框架。

用法

frameLocator.last();

返回

• FrameLocator#

第n个​

返回定位器到第n个匹配的帧。它是基于零的，nth(0)选择第一个帧。

用法

frameLocator.nth(index);

参数

• index number#

返回

• FrameLocator#