自动等待
介绍
¥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.click()，Playwright 将确保：
¥For example, for locator.click(), Playwright will ensure that:
-
定位器解析为一个元素
¥locator resolves to exactly one element
-
元素是 可见的
¥element is Visible
-
元素是 稳定的，如未设置动画或已完成的动画
¥element is Stable, as in not animating or completed animation
-
元素 接收事件，因为没有被其他元素遮挡
¥element Receives Events, as in not obscured by other elements
-
元素是 启用
¥element is Enabled
以下是针对每个操作执行的可操作性检查的完整列表：
¥Here is the complete list of actionability checks performed for each action:
| 行动 | [Visible] | [Stable] | [Receives Events] | [Enabled] | [Editable] |
|---|---|---|---|---|---|
| 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() | * | * | * | * | * |
强制行动
¥Forcing actions
某些操作（例如 locator.click()）支持 force 选项，该选项禁用非必要的可操作性检查，例如将 true force 传递到 locator.click() 方法将不会检查目标元素是否实际接收点击事件。
¥Some actions like locator.click() support force option that disables non-essential actionability checks, for example passing truthy force to locator.click() 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.
| 断言 | 描述 |
|---|---|
| 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 |
在 断言指南 中了解更多信息。
¥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:
-
零大小的元素不被视为可见。
¥Elements of zero size are not considered visible.
-
具有
display:none的元素不被视为可见。¥Elements with
display:noneare not considered visible. -
具有
opacity:0的元素被视为可见。¥Elements with
opacity:0are considered visible.
稳定的
¥Stable
当元素在至少两个连续的动画帧中保持相同的边界框时，该元素被认为是稳定的。
¥Element is considered stable when it has maintained the same bounding box for at least two consecutive animation frames.
启用
¥Enabled
元素被视为已启用，除非它是具有 disabled 属性的 <button>、<select>、<input> 或 <textarea>。
¥Element is considered enabled unless it is a <button>, <select>, <input> or <textarea> with a disabled property.
可编辑
¥Editable
当元素为 enabled 并且未设置 readonly 属性时，该元素被视为可编辑。
¥Element is considered editable when it is enabled and does not have readonly property set.
接收事件
¥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.click() 调用，Playwright 都会单击 Sign Up 按钮：
¥For example, consider a scenario where Playwright will click Sign Up button regardless of when the locator.click() call was made:
-
页面正在检查用户名是否唯一且
Sign Up按钮已禁用；¥page is checking that user name is unique and
Sign Upbutton is disabled; -
与服务器检查后，禁用的
Sign Up按钮被替换为现在启用的另一个按钮。¥after checking with the server, the disabled
Sign Upbutton is replaced with another one that is now enabled.