FrameLocator
FrameLocator 表示页面上 iframe
的视图。它捕获了检索 iframe
并在该 iframe 中定位元素的充分逻辑。FrameLocator 可以使用 locator.content_frame、page.frame_locator() 或 locator.frame_locator() 方法创建。
- 同步
- 异步
locator = page.locator("my-frame").content_frame.get_by_text("Submit")
locator.click()
locator = page.locator("#my-frame").content_frame.get_by_text("Submit")
await locator.click()
严格性
Frame 定位器是严格的。这意味着如果给定选择器匹配到多个元素,则在 frame 定位器上的所有操作都将抛出异常。
- 同步
- 异步
# Throws if there are several frames in DOM:
page.locator('.result-frame').content_frame.get_by_role('button').click()
# Works because we explicitly tell locator to pick the first frame:
page.locator('.result-frame').first.content_frame.get_by_role('button').click()
# Throws if there are several frames in DOM:
await page.locator('.result-frame').content_frame.get_by_role('button').click()
# Works because we explicitly tell locator to pick the first frame:
await page.locator('.result-frame').first.content_frame.get_by_role('button').click()
将 Locator 转换为 FrameLocator
如果您有一个指向 iframe
的 Locator 对象,则可以使用 locator.content_frame 将其转换为 FrameLocator。
将 FrameLocator 转换为 Locator
如果您有一个 FrameLocator 对象,则可以使用 frame_locator.owner 将其转换为指向相同 iframe
的 Locator。
方法
frame_locator
添加于: v1.17当使用 iframe 时,您可以创建一个 frame 定位器,它将进入 iframe 并允许在该 iframe 中选择元素。
用法
frame_locator.frame_locator(selector)
参数
返回值
get_by_alt_text
添加于: v1.27允许通过元素的 alt 文本定位元素。
用法
例如,此方法将通过 alt 文本 "Playwright logo" 找到图像
<img alt='Playwright logo'>
- 同步
- 异步
page.get_by_alt_text("Playwright logo").click()
await page.get_by_alt_text("Playwright logo").click()
参数
-
用于定位元素的文本。
-
是否查找精确匹配项:区分大小写且全字符串匹配。默认为 false。当通过正则表达式定位时忽略。请注意,精确匹配仍然会去除空格。
返回值
get_by_label
添加于: v1.27允许通过关联的 <label>
或 aria-labelledby
元素的文本,或通过 aria-label
属性来定位输入元素。
用法
例如,此方法将在以下 DOM 中通过标签 "Username" 和 "Password" 找到输入框
<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")
await page.get_by_label("Username").fill("john")
await page.get_by_label("Password").fill("secret")
参数
-
用于定位元素的文本。
-
是否查找精确匹配项:区分大小写且全字符串匹配。默认为 false。当通过正则表达式定位时忽略。请注意,精确匹配仍然会去除空格。
返回值
get_by_placeholder
添加于: v1.27允许通过占位符文本定位输入元素。
用法
例如,考虑以下 DOM 结构。
<input type="email" placeholder="[email protected]" />
您可以在通过占位符文本定位输入框后填充它
- 同步
- 异步
page.get_by_placeholder("[email protected]").fill("[email protected]")
await page.get_by_placeholder("[email protected]").fill("[email protected]")
参数
-
用于定位元素的文本。
-
是否查找精确匹配项:区分大小写且全字符串匹配。默认为 false。当通过正则表达式定位时忽略。请注意,精确匹配仍然会去除空格。
返回值
get_by_role
添加于: v1.27允许通过元素的 ARIA 角色、ARIA 属性 和 可访问名称 定位元素。
用法
考虑以下 DOM 结构。
<h3>Sign up</h3>
<label>
<input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>
您可以根据每个元素的隐式角色定位它们
- 同步
- 异步
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()
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()
参数
-
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 角色。
-
通常由
aria-checked
或原生<input type=checkbox>
控件设置的属性。了解更多关于
aria-checked
。 -
通常由
aria-disabled
或disabled
设置的属性。注意与大多数其他属性不同,
disabled
是通过 DOM 层次结构继承的。了解更多关于aria-disabled
。 -
是否 name 精确匹配:区分大小写且全字符串匹配。默认为 false。当 name 是正则表达式时忽略。请注意,精确匹配仍然会去除空格。
-
通常由
aria-expanded
设置的属性。了解更多关于
aria-expanded
。 -
控制是否匹配隐藏元素的选项。默认情况下,角色选择器仅匹配非隐藏元素,如 ARIA 定义。
了解更多关于
aria-hidden
。 -
数字属性,通常用于角色
heading
、listitem
、row
、treeitem
,对于<h1>-<h6>
元素具有默认值。了解更多关于
aria-level
。 -
匹配可访问名称的选项。默认情况下,匹配不区分大小写并搜索子字符串,使用 exact 来控制此行为。
了解更多关于 可访问名称。
-
通常由
aria-pressed
设置的属性。了解更多关于
aria-pressed
。 -
通常由
aria-selected
设置的属性。了解更多关于
aria-selected
。
返回值
详情
角色选择器不能替代无障碍功能审核和一致性测试,而是提供关于 ARIA 指南的早期反馈。
许多 html 元素都有隐式定义的角色,角色选择器可以识别这些角色。您可以在此处找到所有支持的角色。ARIA 指南不建议通过将 role
和/或 aria-*
属性设置为默认值来复制隐式角色和属性。
get_by_test_id
添加于: v1.27通过测试 ID 定位元素。
用法
考虑以下 DOM 结构。
<button data-testid="directions">Itinéraire</button>
您可以通过元素的测试 ID 定位它
- 同步
- 异步
page.get_by_test_id("directions").click()
await page.get_by_test_id("directions").click()
参数
返回值
详情
默认情况下,data-testid
属性用作测试 ID。如有必要,使用 selectors.set_test_id_attribute() 配置不同的测试 ID 属性。
get_by_text
添加于: v1.27允许定位包含给定文本的元素。
另请参阅 locator.filter(),它允许按其他条件(如可访问角色)进行匹配,然后按文本内容进行筛选。
用法
考虑以下 DOM 结构
<div>Hello <span>world</span></div>
<div>Hello</div>
您可以按文本子字符串、精确字符串或正则表达式进行定位
- 同步
- 异步
# 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))
# 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))
参数
-
用于定位元素的文本。
-
是否查找精确匹配项:区分大小写且全字符串匹配。默认为 false。当通过正则表达式定位时忽略。请注意,精确匹配仍然会去除空格。
返回值
详情
按文本匹配始终会规范化空格,即使是精确匹配也是如此。例如,它将多个空格变成一个空格,将换行符变成空格,并忽略前导和尾随空格。
类型为 button
和 submit
的输入元素通过它们的 value
而不是文本内容进行匹配。例如,按文本 "Log in"
定位会匹配 <input type=button value="Log in">
。
get_by_title
添加于: v1.27允许通过元素的 title 属性定位元素。
用法
考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
您可以在通过标题文本定位问题计数后检查它
- 同步
- 异步
expect(page.get_by_title("Issues count")).to_have_text("25 issues")
await expect(page.get_by_title("Issues count")).to_have_text("25 issues")
参数
-
用于定位元素的文本。
-
是否查找精确匹配项:区分大小写且全字符串匹配。默认为 false。当通过正则表达式定位时忽略。请注意,精确匹配仍然会去除空格。
返回值
locator
添加于: v1.17该方法在定位器的子树中查找与指定选择器匹配的元素。它还接受过滤器选项,类似于 locator.filter() 方法。
用法
frame_locator.locator(selector_or_locator)
frame_locator.locator(selector_or_locator, **kwargs)
参数
-
selector_or_locator
str | Locator#用于解析 DOM 元素的选择器或定位器。
-
将方法的结果缩小到那些包含与此相对定位器匹配的元素的元素。 例如,包含
text=Playwright
的article
匹配<article><div>Playwright</div></article>
。内部定位器必须相对于外部定位器,并且从外部定位器匹配项开始查询,而不是文档根目录。 例如,您可以在
<article><content><div>Playwright</div></content></article>
中找到包含div
的content
。 但是,查找包含article div
的content
将失败,因为内部定位器必须是相对的,并且不应使用content
之外的任何元素。请注意,外部和内部定位器必须属于同一 frame。内部定位器不得包含 FrameLocator。
-
has_not
Locator (可选)添加于: v1.33#匹配不包含与内部定位器匹配的元素的元素。 内部定位器是针对外部定位器查询的。 例如,不包含
div
的article
匹配<article><span>Playwright</span></article>
。请注意,外部和内部定位器必须属于同一 frame。内部定位器不得包含 FrameLocator。
-
has_not_text
str | Pattern (可选)添加于: v1.33#匹配在内部某处(可能在子元素或后代元素中)不包含指定文本的元素。 当传递 [字符串] 时,匹配不区分大小写并搜索子字符串。
-
匹配在内部某处(可能在子元素或后代元素中)包含指定文本的元素。 当传递 [字符串] 时,匹配不区分大小写并搜索子字符串。 例如,
"Playwright"
匹配<article><div>Playwright</div></article>
。
返回值
属性
owner
添加于: v1.43返回一个 Locator 对象,该对象指向与此 frame 定位器相同的 iframe
。
当您在某处获得了一个 FrameLocator 对象,并且稍后想要与 iframe
元素交互时,此功能很有用。
对于反向操作,请使用 locator.content_frame。
用法
- 同步
- 异步
frame_locator = page.locator("iframe[name=\"embedded\"]").content_frame
# ...
locator = frame_locator.owner
expect(locator).to_be_visible()
frame_locator = page.locator("iframe[name=\"embedded\"]").content_frame
# ...
locator = frame_locator.owner
await expect(locator).to_be_visible()
返回值
已弃用
first
添加于: v1.17请改用 locator.first,后跟 locator.content_frame。
返回指向第一个匹配 frame 的定位器。
用法
frame_locator.first
返回值
last
添加于: v1.17请改用 locator.last,后跟 locator.content_frame。
返回指向最后一个匹配 frame 的定位器。
用法
frame_locator.last
返回值
nth
添加于: v1.17请改用 locator.nth(),后跟 locator.content_frame。
返回指向第 n 个匹配 frame 的定位器。它是从零开始的,nth(0)
选择第一个 frame。
用法
frame_locator.nth(index)
参数
返回值