自动等待

介绍

🌐 Introduction

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

🌐 Playwright performs a range of actionability checks on the elements before making actions to ensure these actions behave as expected. It auto-waits for all the relevant checks to pass and only then performs the requested action. If the required checks do not pass within the given timeout, action fails with the TimeoutError.

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

🌐 For example, for Locator.ClickAsync(), Playwright will ensure that:

• 定位器解析为一个元素
• 元素是可见
• 元素是稳定的，即未在动画或动画已完成
• 元素接收事件，即未被其他元素遮挡
• 元素已启用

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

🌐 Here is the complete list of actionability checks performed for each action:

Action	Visible	Stable	Receives Events	Enabled	Editable
Locator.CheckAsync()	Yes	Yes	Yes	Yes	-
Locator.ClickAsync()	Yes	Yes	Yes	Yes	-
Locator.DblClickAsync()	Yes	Yes	Yes	Yes	-
Locator.SetCheckedAsync()	Yes	Yes	Yes	Yes	-
Locator.TapAsync()	Yes	Yes	Yes	Yes	-
Locator.UncheckAsync()	Yes	Yes	Yes	Yes	-
Locator.HoverAsync()	Yes	Yes	Yes	-	-
Locator.DragToAsync()	Yes	Yes	Yes	-	-
Locator.ScreenshotAsync()	Yes	Yes	-	-	-
Locator.FillAsync()	Yes	-	-	Yes	Yes
Locator.ClearAsync()	Yes	-	-	Yes	Yes
Locator.SelectOptionAsync()	Yes	-	-	Yes	-
Locator.SelectTextAsync()	Yes	-	-	-	-
Locator.ScrollIntoViewIfNeededAsync()	-	Yes	-	-	-
Locator.BlurAsync()	-	-	-	-	-
Locator.DispatchEventAsync()	-	-	-	-	-
Locator.FocusAsync()	-	-	-	-	-
Locator.PressAsync()	-	-	-	-	-
Locator.PressSequentiallyAsync()	-	-	-	-	-
Locator.SetInputFilesAsync()	-	-	-	-	-

强制行动

🌐 Forcing actions

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

🌐 Some actions like Locator.ClickAsync() support force option that disables non-essential actionability checks, for example passing truthy force to Locator.ClickAsync() method will not check that the target element actually receives click events.

断言

🌐 Assertions

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

🌐 Playwright includes auto-retrying assertions that remove flakiness by waiting until the condition is met, similarly to auto-waiting before actions.

Assertion	Description
Expect(Locator).ToBeAttachedAsync()	Element is attached
Expect(Locator).ToBeCheckedAsync()	Checkbox is checked
Expect(Locator).ToBeDisabledAsync()	Element is disabled
Expect(Locator).ToBeEditableAsync()	Element is editable
Expect(Locator).ToBeEmptyAsync()	Container is empty
Expect(Locator).ToBeEnabledAsync()	Element is enabled
Expect(Locator).ToBeFocusedAsync()	Element is focused
Expect(Locator).ToBeHiddenAsync()	Element is not visible
Expect(Locator).ToBeInViewportAsync()	Element intersects viewport
Expect(Locator).ToBeVisibleAsync()	Element is visible
Expect(Locator).ToContainTextAsync()	Element contains text
Expect(Locator).ToHaveAttributeAsync()	Element has a DOM attribute
Expect(Locator).ToHaveClassAsync()	Element has a class property
Expect(Locator).ToHaveCountAsync()	List has exact number of children
Expect(Locator).ToHaveCSSAsync()	Element has CSS property
Expect(Locator).ToHaveIdAsync()	Element has an ID
Expect(Locator).ToHaveJSPropertyAsync()	Element has a JavaScript property
Expect(Locator).ToHaveTextAsync()	Element matches text
Expect(Locator).ToHaveValueAsync()	Input has a value
Expect(Locator).ToHaveValuesAsync()	Select has options selected
Expect(Page).ToHaveTitleAsync()	Page has a title
Expect(Page).ToHaveURLAsync()	Page has a URL
Expect(Response).ToBeOKAsync()	Response has an OK status

在断言指南中了解更多。

🌐 Learn more in the assertions guide.

可见的

🌐 Visible

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

🌐 Element is considered visible when it has non-empty bounding box and does not have visibility:hidden computed style.

请注意，根据这个定义：

🌐 Note that according to this definition:

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

稳定的

🌐 Stable

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

🌐 Element is considered stable when it has maintained the same bounding box for at least two consecutive animation frames.

启用

🌐 Enabled

当元素没有被禁用时，认为它是可用的。

🌐 Element is considered enabled when it is not disabled.

当元素被禁用时：

🌐 Element is disabled when:

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

可编辑

🌐 Editable

当元素是[启用]且不是只读时，认为它是可编辑的。

🌐 Element is considered editable when it is enabled and is not readonly.

当元素为只读时：

🌐 Element is readonly when:

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

接收事件

🌐 Receives Events

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

🌐 Element is considered receiving pointer events when it is the hit target of the pointer event at the action point. For example, when clicking at the point (10;10), Playwright checks whether some other element (usually an overlay) will instead capture the click at (10;10).

例如，考虑这样一种情况：无论何时发出 Locator.ClickAsync() 调用，Playwright 都会点击 Sign Up 按钮：

🌐 For example, consider a scenario where Playwright will click Sign Up button regardless of when the Locator.ClickAsync() call was made:

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