自动等待

简介

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

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

• 定位器解析为恰好一个元素
• 元素 可见
• 元素 稳定，即没有动画或动画完成
• 元素 接收事件，即没有被其他元素遮挡
• 元素 启用

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

操作	可见	稳定	接收事件	启用	可编辑
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()	元素具有类属性
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()	响应具有 OK 状态

在 断言指南 中了解详情。

可见

当元素具有非空边界框且没有计算出的 visibility:hidden 样式时，则认为该元素可见。

请注意，根据此定义

• 大小为零的元素 不被 视为可见。
• 具有 display:none 的元素 不被 视为可见。
• 具有 opacity:0 的元素 被 视为可见。

稳定

当元素至少在两个连续的动画帧中保持相同的边界框时，则认为该元素稳定。

启用

除非元素是 <button>、<select>、<input> 或 <textarea> 且具有 disabled 属性，否则认为该元素已启用。

可编辑

当元素 已启用 且没有设置 readonly 属性时，则认为该元素可编辑。

接收事件

当元素是操作点处指针事件的命中目标时，则认为该元素接收指针事件。例如，当在点 (10;10) 处点击时，Playwright 会检查是否有其他元素（通常是覆盖层）会在 (10;10) 处捕获点击事件。

例如，假设 Playwright 会无论何时调用 locator.click() 都会点击 注册 按钮

• 页面正在检查用户名是否唯一，并且 注册 按钮已禁用；
• 在与服务器检查后，已禁用的 注册 按钮被替换为另一个现在已启用的按钮。