自动等待机制

简介

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

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

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

操作	可见	稳定	接收事件	启用	可编辑
locator.check()	是	是	是	是	-
locator.click()	是	是	是	是	-
locator.dblclick()	是	是	是	是	-
locator.setChecked()	是	是	是	是	-
locator.tap()	是	是	是	是	-
locator.uncheck()	是	是	是	是	-
locator.hover()	是	是	是	-	-
locator.dragTo()	是	是	是	-	-
locator.screenshot()	是	是	-	-	-
locator.fill()	是	-	-	是	是
locator.clear()	是	-	-	是	是
locator.selectOption()	是	-	-	是	-
locator.selectText()	是	-	-	-	-
locator.scrollIntoViewIfNeeded()	-	是	-	-	-
locator.blur()	-	-	-	-	-
locator.dispatchEvent()	-	-	-	-	-
locator.focus()	-	-	-	-	-
locator.press()	-	-	-	-	-
locator.pressSequentially()	-	-	-	-	-
locator.setInputFiles()	-	-	-	-	-

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

Playwright 包含自动重试的断言机制，通过等待直到条件满足来消除不稳定性，类似于操作前的自动等待功能。

断言	描述
expect(locator).toBeAttached()	元素已附加
expect(locator).toBeChecked()	复选框已选中
expect(locator).toBeDisabled()	元素已禁用
expect(locator).toBeEditable()	元素可编辑
expect(locator).toBeEmpty()	容器为空
expect(locator).toBeEnabled()	元素已启用
expect(locator).toBeFocused()	元素已聚焦
expect(locator).toBeHidden()	元素不可见
expect(locator).toBeInViewport()	元素与视口相交
expect(locator).toBeVisible()	元素可见
expect(locator).toContainText()	元素包含文本
expect(locator).toHaveAttribute()	元素具有 DOM 属性
expect(locator).toHaveClass()	元素具有类属性
expect(locator).toHaveCount()	列表具有指定数量的子元素
expect(locator).toHaveCSS()	元素具有 CSS 属性
expect(locator).toHaveId()	元素具有 ID
expect(locator).toHaveJSProperty()	元素具有 JavaScript 属性
expect(locator).toHaveText()	元素匹配文本
expect(locator).toHaveValue()	输入框具有值
expect(locator).toHaveValues()	选择框具有选中的选项
expect(page).toHaveTitle()	页面具有标题
expect(page).toHaveURL()	页面具有 URL
expect(response).toBeOK()	响应状态为 OK

了解更多请参阅断言指南。

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

请注意以下定义：

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

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

以下情况元素会被视为禁用：

是带有 [disabled] 属性的 <button>、<select>、<input>、<textarea>、<option> 或 <optgroup>
作为带有 [disabled] 属性的 <fieldset> 组成部分的上述表单元素
是具有 [aria-disabled=true] 属性的元素的子级

当元素处于启用状态且非只读时，该元素被视为可编辑。

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

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

举例说明，以下场景中无论何时调用 locator.click()，Playwright 都会点击 注册 按钮：