自动等待

简介

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

例如，对于 Locator.ClickAsync()，Playwright 将确保：

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

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

操作	[可见的]	[稳定的]	[接收事件]	[启用的]	[可编辑的]
Locator.CheckAsync()	是	是	是	是	-
Locator.ClickAsync()	是	是	是	是	-
Locator.DblClickAsync()	是	是	是	是	-
Locator.SetCheckedAsync()	是	是	是	是	-
Locator.TapAsync()	是	是	是	是	-
Locator.UncheckAsync()	是	是	是	是	-
Locator.HoverAsync()	是	是	是	-	-
Locator.DragToAsync()	是	是	是	-	-
Locator.ScreenshotAsync()	是	是	-	-	-
Locator.FillAsync()	是	-	-	是	是
Locator.ClearAsync()	是	-	-	是	是
Locator.SelectOptionAsync()	是	-	-	是	-
Locator.SelectTextAsync()	是	-	-	-	-
Locator.ScrollIntoViewIfNeededAsync()	-	是	-	-	-
Locator.BlurAsync()	-	-	-	-	-
Locator.DispatchEventAsync()	-	-	-	-	-
Locator.FocusAsync()	-	-	-	-	-
Locator.PressAsync()	-	-	-	-	-
Locator.PressSequentiallyAsync()	-	-	-	-	-
Locator.SetInputFilesAsync()	-	-	-	-	-

强制操作

像 Locator.ClickAsync() 这样的一些操作支持 force 选项，该选项会禁用非必要的可操作性检查，例如，向 Locator.ClickAsync() 方法传递真值 force，将不会检查目标元素是否实际接收到点击事件。

断言

Playwright 包含自动重试断言，通过等待条件满足来消除不稳定性，这与操作前的自动等待类似。

断言	描述
Expect(Locator).ToBeAttachedAsync()	元素已附加
Expect(Locator).ToBeCheckedAsync()	复选框已选中
Expect(Locator).ToBeDisabledAsync()	元素已禁用
Expect(Locator).ToBeEditableAsync()	元素可编辑
Expect(Locator).ToBeEmptyAsync()	容器为空
Expect(Locator).ToBeEnabledAsync()	元素已启用
Expect(Locator).ToBeFocusedAsync()	元素已聚焦
Expect(Locator).ToBeHiddenAsync()	元素不可见
Expect(Locator).ToBeInViewportAsync()	元素与视口相交
Expect(Locator).ToBeVisibleAsync()	元素可见
Expect(Locator).ToContainTextAsync()	元素包含文本
Expect(Locator).ToHaveAttributeAsync()	元素具有 DOM 属性
Expect(Locator).ToHaveClassAsync()	元素具有类属性
Expect(Locator).ToHaveCountAsync()	列表具有确切数量的子元素
Expect(Locator).ToHaveCSSAsync()	元素具有 CSS 属性
Expect(Locator).ToHaveIdAsync()	元素具有 ID
Expect(Locator).ToHaveJSPropertyAsync()	元素具有 JavaScript 属性
Expect(Locator).ToHaveTextAsync()	元素与文本匹配
Expect(Locator).ToHaveValueAsync()	输入框具有值
Expect(Locator).ToHaveValuesAsync()	选择框有选中的选项
Expect(Page).ToHaveTitleAsync()	页面具有标题
Expect(Page).ToHaveURLAsync()	页面具有 URL
Expect(Response).ToBeOKAsync()	响应具有正常状态码

在 断言指南 中了解更多信息。

可见

当元素具有非空的边界框且没有 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.ClickAsync()，Playwright 都会点击 “注册” 按钮：

• 页面正在检查用户名是否唯一，并且 “注册” 按钮处于禁用状态；
• 在与服务器进行检查后，禁用的 “注册” 按钮被另一个已启用的按钮替换。