自动等待

简介

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 选项，该选项禁用非必要的可操作性检查。例如，将 truthy force 传递给 Locator.ClickAsync() 方法将不会检查目标元素是否实际接收到点击事件。

断言

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()	元素具有 class 属性
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()	响应具有 OK 状态

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

可见

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

请注意，根据此定义

• 零尺寸的元素 不被 认为是可见的。
• 具有 display:none 的元素 不被 认为是可见的。
• 具有 opacity:0 的元素 被 认为是可见的。

稳定

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

启用

当元素 未被禁用 时，则认为该元素是启用的。

当元素满足以下条件时，则被 禁用：

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

可编辑

当元素 被启用 且 不是只读 时，则认为该元素是可编辑的。

当元素满足以下条件时，则被 视为只读：

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

接收事件

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

例如，考虑一个场景，无论 Locator.ClickAsync() 调用何时发出，Playwright 都会点击 Sign Up 按钮

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