FrameLocator
FrameLocator 表示页面上 iframe
的视图。它捕获了足够的逻辑来检索 iframe
并在该 iframe 中定位元素。FrameLocator 可以使用 Locator.contentFrame()、Page.frameLocator() 或 Locator.frameLocator() 方法创建。
Locator locator = page.locator("#my-frame").contentFrame().getByText("Submit");
locator.click();
严格性
帧定位器是严格的。这意味着如果一个给定的选择器匹配多个元素,所有对帧定位器的操作都将抛出错误。
// Throws if there are several frames in DOM:
page.locator(".result-frame").contentFrame().getByRole(AriaRole.BUTTON).click();
// Works because we explicitly tell locator to pick the first frame:
page.locator(".result-frame").first().contentFrame().getByRole(AriaRole.BUTTON).click();
将 Locator 转换为 FrameLocator
如果您有一个指向 iframe
的 Locator 对象,可以使用 Locator.contentFrame() 将其转换为 FrameLocator。
将 FrameLocator 转换为 Locator
如果您有一个 FrameLocator 对象,可以使用 FrameLocator.owner() 将其转换为指向同一 iframe
的 Locator。
方法
frameLocator
新增于: v1.17使用 iframe 时,您可以创建一个框架定位器,它将进入 iframe 并允许选择 iframe 中的元素。
用法
FrameLocator.frameLocator(selector);
参数
返回
getByAltText
新增于:v1.27允许根据元素的 alt 文本定位元素。
用法
例如,此方法将通过 alt 文本“Playwright logo”找到图像
<img alt='Playwright logo'>
page.getByAltText("Playwright logo").click();
参数
-
用于定位元素的文本。
-
options
FrameLocator.GetByAltTextOptions
(可选)
返回
getByLabel
新增于:v1.27允许通过关联的 <label>
或 aria-labelledby
元素的文本或 aria-label
属性来定位输入元素。
用法
例如,此方法将在以下 DOM 中通过标签“用户名”和“密码”找到输入
<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
page.getByLabel("Username").fill("john");
page.getByLabel("Password").fill("secret");
参数
-
用于定位元素的文本。
-
options
FrameLocator.GetByLabelOptions
(可选)
返回
getByPlaceholder
新增于:v1.27允许通过占位符文本定位输入元素。
用法
例如,考虑以下 DOM 结构。
<input type="email" placeholder="name@example.com" />
您可以按占位符文本定位输入框后填充它
page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");
参数
-
用于定位元素的文本。
-
options
FrameLocator.GetByPlaceholderOptions
(可选)
返回
getByRole
新增于:v1.27允许根据元素的 ARIA 角色、ARIA 属性 和 可访问名称 定位元素。
用法
考虑以下 DOM 结构。
<h3>Sign up</h3>
<label>
<input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>
您可以通过其隐式角色定位每个元素
assertThat(page
.getByRole(AriaRole.HEADING,
new Page.GetByRoleOptions().setName("Sign up")))
.isVisible();
page.getByRole(AriaRole.CHECKBOX,
new Page.GetByRoleOptions().setName("Subscribe"))
.check();
page.getByRole(AriaRole.BUTTON,
new Page.GetByRoleOptions().setName(
Pattern.compile("submit", Pattern.CASE_INSENSITIVE)))
.click();
参数
-
role
enum AriaRole { 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
FrameLocator.GetByRoleOptions
(可选)-
通常由
aria-checked
或原生<input type=checkbox>
控件设置的属性。了解更多关于
aria-checked
的信息。 -
通常由
aria-disabled
或disabled
设置的属性。注意与大多数其他属性不同,
disabled
在 DOM 层次结构中是继承的。了解更多关于aria-disabled
的信息。 -
setExact
boolean (可选)新增于: v1.28#setName 是否完全匹配:区分大小写且完全匹配字符串。默认为 false。当 setName 是正则表达式时,忽略此项。请注意,完全匹配仍会修剪空白。
-
通常由
aria-expanded
设置的属性。了解更多关于
aria-expanded
的信息。 -
setIncludeHidden
boolean (可选)#控制是否匹配隐藏元素的选项。默认情况下,只有非隐藏元素(由 ARIA 定义)由角色选择器匹配。
了解更多关于
aria-hidden
的信息。 -
通常用于角色
heading
、listitem
、row
、treeitem
的数字属性,<h1>-<h6>
元素具有默认值。了解更多关于
aria-level
的信息。 -
setName
String | Pattern (可选)#匹配 可访问名称 的选项。默认情况下,匹配不区分大小写并搜索子字符串,使用 setExact 控制此行为。
了解更多关于 可访问名称 的信息。
-
通常由
aria-pressed
设置的属性。了解更多关于
aria-pressed
的信息。 -
通常由
aria-selected
设置的属性。了解更多关于
aria-selected
的信息。
-
返回
详情
角色选择器 不替代 可访问性审计和合规性测试,而是提供有关 ARIA 指南的早期反馈。
许多 HTML 元素都具有隐式 定义角色,该角色被角色选择器识别。您可以在 此处找到所有支持的角色。ARIA 指南**不建议**通过将 role
和/或 aria-*
属性设置为默认值来复制隐式角色和属性。
getByTestId
新增于:v1.27按测试 ID 定位元素。
用法
考虑以下 DOM 结构。
<button data-testid="directions">Itinéraire</button>
您可以通过其测试 ID 定位元素
page.getByTestId("directions").click();
参数
返回
详情
默认情况下,data-testid
属性用作测试 ID。如有必要,请使用 Selectors.setTestIdAttribute() 配置不同的测试 ID 属性。
getByText
新增于:v1.27允许定位包含给定文本的元素。
另请参阅 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", new Page.GetByTextOptions().setExact(true));
// Matches both <div>s
page.getByText(Pattern.compile("Hello"));
// Matches second <div>
page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE));
参数
-
用于定位元素的文本。
-
options
FrameLocator.GetByTextOptions
(可选)
返回
详情
按文本匹配始终会规范化空格,即使是精确匹配也是如此。例如,它会将多个空格转换为一个空格,将换行符转换为空格,并忽略前导和尾随空格。
类型为 button
和 submit
的输入元素通过其 value
而不是文本内容进行匹配。例如,通过文本 "登录"
定位匹配 <input type=button value="登录">
。
getByTitle
新增于:v1.27允许通过元素的 title 属性定位元素。
用法
考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
您可以通过 title 文本定位它后检查问题数量
assertThat(page.getByTitle("Issues count")).hasText("25 issues");
参数
-
用于定位元素的文本。
-
options
FrameLocator.GetByTitleOptions
(可选)
返回
locator
新增于: v1.17此方法在定位器的子树中查找与指定选择器匹配的元素。它还接受筛选选项,类似于 Locator.filter() 方法。
用法
FrameLocator.locator(selectorOrLocator);
FrameLocator.locator(selectorOrLocator, options);
参数
-
selectorOrLocator
String | Locator#用于解析 DOM 元素的选择器或定位器。
-
options
FrameLocator.LocatorOptions
(可选)-
将方法的结果缩小到那些包含与此相对定位器匹配的元素的元素。例如,包含
text=Playwright
的article
匹配<article><div>Playwright</div></article>
。内部定位器**必须相对于**外部定位器,并且从外部定位器匹配开始查询,而不是从文档根开始。例如,您可以在
<article><content><div>Playwright</div></content></article>
中找到包含div
的content
。但是,查找包含article div
的content
将失败,因为内部定位器必须是相对的,并且不应使用content
之外的任何元素。请注意,外部和内部定位器必须属于同一个框架。内部定位器不得包含 FrameLocator。
-
setHasNot
Locator (可选)新增于:v1.33#匹配不包含与内部定位器匹配的元素的元素。内部定位器针对外部定位器进行查询。例如,不包含
div
的article
匹配<article><span>Playwright</span></article>
。请注意,外部和内部定位器必须属于同一个框架。内部定位器不得包含 FrameLocator。
-
setHasNotText
String | Pattern (可选)新增于:v1.33#匹配不包含指定文本的元素,该文本可能在子元素或后代元素中。当传递 字符串 时,匹配不区分大小写并搜索子字符串。
-
setHasText
String | Pattern (可选)#匹配包含指定文本的元素,该文本可能在子元素或后代元素中。当传递 字符串 时,匹配不区分大小写并搜索子字符串。例如,
"Playwright"
匹配<article><div>Playwright</div></article>
。
-
返回
owner
新增于: v1.43返回一个 Locator 对象,指向与此框架定位器相同的 iframe
。
当您在某处获取了一个 FrameLocator 对象,之后希望与 iframe
元素进行交互时,此功能很有用。
对于反向操作,请使用 Locator.contentFrame()。
用法
FrameLocator frameLocator = page.locator("iframe[name=\"embedded\"]").contentFrame();
// ...
Locator locator = frameLocator.owner();
assertThat(locator).isVisible();
返回
已弃用
first
新增于: v1.17返回第一个匹配帧的定位器。
用法
FrameLocator.first();
返回
last
新增于: v1.17请改用 Locator.last() 后跟 Locator.contentFrame()。
返回最后一个匹配帧的定位器。
用法
FrameLocator.last();
返回
nth
新增于: v1.17请改用 Locator.nth() 后跟 Locator.contentFrame()。
返回第 n 个匹配帧的定位器。它是基于零的,`nth(0)` 选择第一个帧。
用法
FrameLocator.nth(index);
参数
返回