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

核心原则

隐式等待覆盖 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)

推荐时长

环境	推荐值	说明
内网 / CI	10000 (10s)	网络稳定，无需长等
外网 / 生产	15000 (15s)	兼顾偶发网络波动
弱网测试	20000~30000	专项弱网场景

---

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

什么时候用

场景	原因	做法
大文件上传 / 导入	服务器处理耗时远超常规页面操作	self.is_visible(LOCATOR, timeout=60000)
长轮询 / 异步任务回调	后端处理完才刷新前端状态	page.locator(...).wait_for(state="visible", timeout=30000)
第三方服务跳转	OAuth / 支付等外部页面响应不可控	page.wait_for_url("**/callback**", timeout=30000)
首次冷启动	服务刚部署、首次请求慢	对首个导航操作单独加大 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") 是导航级等待，与元素级隐式等待互补，不冲突：

等待类型	作用层级	触发时机	受 set_default_timeout 控制
wait_for_load_state	导航 / 网络	页面跳转、AJAX 批量请求后	受 set_default_navigation_timeout 控制
隐式等待	元素	每次元素操作前	是

推荐模式：

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 参数供调用方覆盖