danielsuo117/velocitai/wait-strategy

等待策略 — 隐式等待为主，显式等待为辅

核心原则

隐式等待覆盖 99% 场景，显式等待仅用于已知的慢路径。

一、隐式等待（默认，全局生效）

什么是隐式等待

通过 page.set_default_timeout(ms) 在 page 创建后立即设置。此后该 page 上所有 Playwright 操作（click、fill、locator.wait_for、is_visible 等）自动等待元素就绪，超时前持续重试，无需逐个调用指定 timeout。

配置位置

隐式等待的超时时长统一声明在配置文件中（如 DEFAULT_TIMEOUT 常量），在 fixture 层注入到每个 page 实例：

# 配置文件
DEFAULT_TIMEOUT = 15000   # 15 秒，兼顾网络波动
# fixture 层（function 级 / class 级均需设置）
page = context.new_page()
page.set_default_timeout(DEFAULT_TIMEOUT)

推荐时长

二、显式等待（仅用于特殊场景）

什么时候用

使用方式

在调用处传入显式 timeout，覆盖隐式默认值：

# BasePage 封装方法支持 timeout 参数
def is_visible(self, locator, timeout=DEFAULT_TIMEOUT) -> bool:
    ...
# 用例中：仅对已知慢操作显式指定
def test_upload_large_file(self):
    self.page_obj.click_upload()
    assert self.page_obj.is_visible(
        self.page_obj.UPLOAD_SUCCESS_INDICATOR,
        timeout=60000   # 显式等待 60 秒，仅此一处
    ), "大文件上传超时"

禁止事项

• 禁止 `time.sleep()` 硬等待 — Playwright 的自动等待机制已覆盖，硬等待浪费时间且不可靠
• 禁止给每个操作都加显式 timeout — 这等于放弃了隐式等待的统一管理优势
• 禁止在 PageObject 方法内部硬编码超长 timeout — 超时值应由调用方（用例层）按场景决定

三、wait_for_load_state 与隐式等待的关系

page.wait_for_load_state("networkidle") 是导航级等待，与元素级隐式等待互补，不冲突：

推荐模式：

def click_navigate_to_target(self):
    self.click(self.TARGET_LINK)
    self.page.wait_for_load_state("networkidle")  # 等网络请求完成
    # 之后的 is_visible / click 等操作由隐式等待兜底

检查清单

• [ ] 全局 DEFAULT_TIMEOUT 已在配置文件统一声明
• [ ] 所有 page fixture（function 级 / class 级）均调用了 page.set_default_timeout()
• [ ] PageObject 业务方法中无 time.sleep()
• [ ] 显式 timeout 仅出现在已知慢路径的调用处，而非 PageObject 内部
• [ ] PageObject 的 is_visible() 等方法保留 timeout 参数供调用方覆盖