自动等待

说明

Playwright 会在执行操作前对元素进行一系列可操作性检查，以确保这些操作能按预期进行。它会自动等待所有相关检查通过，然后才执行请求的操作。如果在给定的 timeout 内所需的检查未通过，则操作将失败并抛出 TimeoutError。

例如，对于 locator.click()，Playwright 将确保：

• 定位器只解析到一个元素
• 元素是[可见的]
• 元素是[稳定的]，即没有动画或动画已结束
• 元素[接收事件]，即不被其他元素遮挡
• 元素是[可用的]

以下是每种操作执行的可操作性检查完整列表：

操作	Visible	Stable	Receives Events	Enabled	Editable
locator.check()	是	是	是	是	-
locator.click()	是	是	是	是	-
locator.dblclick()	是	是	是	是	-
locator.set_checked()	是	是	是	是	-
locator.tap()	是	是	是	是	-
locator.uncheck()	是	是	是	是	-
locator.hover()	是	是	是	-	-
locator.drag_to()	是	是	是	-	-
locator.screenshot()	是	是	-	-	-
locator.fill()	是	-	-	是	是
locator.clear()	是	-	-	是	是
locator.select_option()	是	-	-	是	-
locator.select_text()	是	-	-	-	-
locator.scroll_into_view_if_needed()	-	是	-	-	-
locator.blur()	-	-	-	-	-
locator.dispatch_event()	-	-	-	-	-
locator.focus()	-	-	-	-	-
locator.press()	-	-	-	-	-
locator.press_sequentially()	-	-	-	-	-
locator.set_input_files()	-	-	-	-	-

强制执行操作

某些操作如 locator.click() 支持 force 选项，可以禁用非必要的可操作性检查。例如，向 locator.click() 方法传递为真值的 force 将不会检查目标元素是否实际接收点击事件。

断言

Playwright 包含了具有自动重试功能的断言，它通过等待直到条件满足来消除测试波动，与操作前的自动等待机制类似。

断言	描述
expect(locator).to_be_attached()	元素已附加
expect(locator).to_be_checked()	复选框已勾选
expect(locator).to_be_disabled()	元素不可用
expect(locator).to_be_editable()	元素可编辑
expect(locator).to_be_empty()	容器为空
expect(locator).to_be_enabled()	元素可用
expect(locator).to_be_focused()	元素已聚焦
expect(locator).to_be_hidden()	元素不可见
expect(locator).to_be_in_viewport()	元素与视口相交
expect(locator).to_be_visible()	元素可见
expect(locator).to_contain_text()	元素包含文本
expect(locator).to_have_attribute()	元素有 DOM 属性
expect(locator).to_have_class()	元素有 class 属性
expect(locator).to_have_count()	列表有确切的子元素数量
expect(locator).to_have_css()	元素有 CSS 属性
expect(locator).to_have_id()	元素有 ID
expect(locator).to_have_js_property()	元素有 JavaScript 属性
expect(locator).to_have_text()	元素匹配文本
expect(locator).to_have_value()	输入框有值
expect(locator).to_have_values()	选择框选项已选中
expect(page).to_have_title()	页面有标题
expect(page).to_have_url()	页面有 URL
expect(response).to_be_ok()	响应状态正常

更多内容请参阅 断言指南。

可见

当元素有非空边界框且计算样式中没有 visibility:hidden 时，该元素被视为可见。

请注意根据此定义：

• 零大小的元素不视为可见。
• 设置了 display:none 的元素不视为可见。
• 设置了 opacity:0 的元素是可视的。

稳定

当元素至少维持两个连续动画帧相同的边界框时，该元素被视为稳定。

可用

当元素未被禁用时，该元素被视为可用。

元素在以下情况下被视为不可用：

• 它是一个带有 [disabled] 属性的 <button>、<select>、<input>、<textarea>、<option> 或 <optgroup>；
• 它是一个位于带有 [disabled] 属性的 <fieldset> 中的 <button>、<select>、<input>、<textarea>、<option> 或 <optgroup>；
• 它是带有 [aria-disabled=true] 属性的元素的后代。

可编辑

当元素是[可用]的并且不是只读的，该元素被视为可编辑。

元素在以下情况下被视为只读：

• 它是一个带有 [readonly] 属性的 <select>、<input> 或 <textarea>；
• 它有一个 [aria-readonly=true] 属性和一个支持它的 ARIA 角色。

接收事件

当某个元素是在指定动作点接收指针事件的目标时，该元素被认为接收事件。例如，当点击 (10;10) 这个点时，Playwright 会检查是否有其他元素（通常是覆盖层）将在 (10;10) 接收点击。

例如，考虑这样一个场景：无论何时调用 locator.click()，Playwright 都会点击 注册 按钮：

• 页面正在检查用户名是否唯一，此时 注册 按钮被禁用；
• 与服务器核对后，禁用的 注册 按钮被替换为新的可用按钮。