自动化脚本怎么“证明自己成功了”：页面、接口与截图的三重校验

引子

自动化脚本最常见的错觉，是“脚本没报错，所以成功了”。但点击成功不代表提交成功，提交成功不代表业务生效，页面跳转也可能只是前端乐观更新。要证明一次操作真的完成，需要三重校验：页面状态、接口响应、可追溯证据。

一、页面校验：断言“业务结果”，不是“元素存在”

很多脚本止步于“按钮点到了”。正确的做法是等待并断言业务结果，例如成功提示、列表新增、状态标签变化：

expect(page.locator(".status-tag")).to_have_text("已完成")

要注意区分三类状态：

• 乐观更新：前端先改 UI，服务端稍后才落库；
• 异步审核：提交成功但状态为“审核中”，不代表最终完成；
• 延迟入账：第三方系统按批次同步，短时间内看到“未完成”是正常的。

因此页面断言要写清楚“在等哪一种状态”，并为异步场景设置合理的轮询上限，而不是无限等待。

二、接口校验：抓住关键响应

比起反复刷新页面，直接监听关键接口更可靠：

with page.expect_response(lambda r: "/api/submit" in r.url) as info:
    page.get_by_role("button", name="发布").click()

resp = info.value
assert resp.status == 200
body = resp.json()
assert body.get("code") in ("success", "HD.92300000")

接口校验的价值在于：

• 能拿到业务主键，例如文章 blogId、订单号，便于后续查询；
• 能区分“前端成功、后端失败”的假成功；
• 失败时能保留服务端错误码，定位效率远高于看页面。

一个细节：expect_response 要放在点击之前注册，否则响应可能在注册前就返回了。

三、截图与日志：让结果可追溯

断言通过只说明“此刻正确”，排查历史问题时还需要证据。建议至少保留：

• 操作前后的关键截图（含 URL 与时间）；
• 关键接口的状态码与响应片段；
• 业务主键（ID）落盘到结果文件。

page.screenshot(path=f"evidence/{step}.png", full_page=False)
json.dump({"id": blog_id, "status": 200}, open("result.json", "w"))

截图不要全页巨图，聚焦结果区域即可；命名带上步骤序号，便于回溯。

四、把“等待”设计成状态机

异步业务适合用状态机描述，而不是散落的 sleep：

PENDING = {"待提交", "审核中", "处理中"}
DONE = {"已完成", "已发布", "已入账"}

for _ in range(20):
    state = read_state(page)
    if state in DONE:
        return True
    if state not in PENDING:
        raise RuntimeError(f"异常状态: {state}")
    page.wait_for_timeout(15000)
return False

这样脚本对“延迟”有明确预期：既不会过早判失败，也不会无限卡死；出现异常状态时还能立即暴露问题。

五、常见反模式

1. 只看元素存在：元素在，业务未必成功；
2. 用固定 sleep 代替状态等待：本地能过，CI 随机失败；
3. 忽略接口返回值：HTTP 200 但 code 是业务失败；
4. 不留证据：出问题时无法判断是脚本错还是平台延迟；
5. 一次性判定：异步系统需要轮询，而不是瞬时结论。

六、小结

一次可信的自动化操作，应当同时满足：

• 页面出现明确的业务成功状态；
• 接口返回成功码与业务主键；
• 本地留存截图与结构化结果，可复查、可追溯。

把这三重校验固化成公共方法，脚本的可信度会显著提升：不仅“跑通了”，而且能说明“为什么算跑通”。