自动化测试 / 系统课时
建立测试交付规范
建立测试交付规范
Selenium 项目能运行并不等于能交付。接手者必须知道怎样启动、使用哪些配置、失败去哪里找证据、报告怎样归档,以及谁负责维护。本篇给出一套可直接落地的最小交付包和验收门槛。
学习目标
- 组织运行说明、配置样例、日志、JUnit 报告和失败证据。
- 用固定执行入口与运行清单记录版本、浏览器和并行度。
- 为选择器、隔离数据、失败重跑和临时跳过建立可检查的维护规则。
交付包必须回答六个问题
一个可接手的测试仓库至少要让新成员在 15 分钟内找到下面六类信息。目录名称可以不同,但职责不能缺失。
| 问题 | 推荐交付物 | 最低要求 |
|---|---|---|
| 怎么运行 | RUNBOOK.md、scripts/run-e2e.sh |
写清 Python 版本、浏览器、命令、无头模式和并行度 |
| 需要什么配置 | .env.example 或配置模板 |
只放变量名与安全示例,不提交真实密码、Token、Cookie |
| 这次跑了什么 | artifacts/run-manifest.json |
记录 commit、浏览器版本、Selenium 版本、worker 数和时间 |
| 测试为什么失败 | artifacts/pytest.log |
日志能关联到用例和运行批次 |
| 机器怎么判定结果 | artifacts/junit.xml |
CI 通过 JUnit 读取通过、失败、跳过数量 |
| 人怎么复核失败 | artifacts/failures/... |
至少保存截图;能采集时再附页面源码或浏览器日志 |

固化唯一的运行入口
不要让 README、CI YAML 和开发者本地各写一套 pytest 参数。把常用入口收敛到脚本中,脚本先创建产物目录,再输出 JUnit 与 pytest 日志。下面示例假设已安装 pytest-xdist,测试位于 tests/e2e,并把并行度作为位置参数,默认值为 2。
#!/usr/bin/env bash
set -uo pipefail
WORKERS="${1:-2}"
mkdir -p artifacts
python -m pytest tests/e2e \
-q \
-n "${WORKERS}" \
--junitxml=artifacts/junit.xml \
--log-file=artifacts/pytest.log \
--log-file-level=INFO
pytest_exit=$?
test -s artifacts/junit.xml && printf 'junit=ok
'
test -f artifacts/pytest.log && printf 'log=ok
'
printf 'pytest_exit=%s
' "$pytest_exit"
exit "$pytest_exit"保存为 scripts/run-e2e.sh 并赋予执行权限后运行:
chmod +x scripts/run-e2e.sh
./scripts/run-e2e.sh 2预期输出末尾至少包含以下三项;<CODE> 为 pytest 的真实退出码:
junit=ok
log=ok
pytest_exit=<CODE>如果 CI 需要 6 个 worker,只改为 ./scripts/run-e2e.sh 6,不要复制一份新的命令。RUNBOOK.md 还应明确示例项目采用的 Python 主次版本,例如 Python 3.12,以及 Chrome 的安装方式;升级版本时在同一个变更中更新 CI 镜像和运行清单。
用运行清单记录可复现条件
日志只能告诉你“发生了什么”,不能完整回答“在什么环境发生”。每次 CI 运行都应生成一份机器可读的 manifest。下面是字段示例,动态值由流水线在执行时填入。
{
"schemaVersion": "1.0",
"runId": "<ID>",
"commit": "<GIT_SHA>",
"python": "3.12",
"selenium": "<VERSION>",
"pytest": "<VERSION>",
"browser": "chrome",
"browserVersion": "<VERSION>",
"workers": 2,
"startedAt": "<TIME>",
"junit": "artifacts/junit.xml",
"log": "artifacts/pytest.log",
"failureEvidenceDir": "artifacts/failures"
}验证方法很直接:从任意一次失败构建下载产物后,应能在 manifest 中确定代码提交、浏览器版本和并行度,并能顺着 junit、log 和 failureEvidenceDir 找到对应证据。若这些文件名由 CI 随机生成,就应把真实路径写回 manifest,而不是依赖人工猜测。
失败证据必须和用例一一对应
截图统一按 run_id/worker/test_nodeid 分目录,避免并行用例互相覆盖。例如同一轮运行里,gw0 与 gw1 都有 test_login 时,不能都写成 artifacts/screenshot.png。推荐路径形态为 artifacts/failures/<RUN_ID>/<WORKER>/<TEST_ID>/screenshot.png。
证据采集要遵守两个边界。第一,截图失败不能覆盖原始测试异常;浏览器会话已经崩溃时,采集函数应记录“无法截图”并保留原异常。第二,页面源码、Cookie、网络响应和控制台日志可能含敏感数据,归档前应做脱敏或直接禁止收集。真实密码、访问 Token 和会话 Cookie 不应进入 JUnit、pytest 日志或截图文件名。
把维护规则写成可检查的门槛
维护约定不要只写“保持稳定”。可以直接采用下面这组团队规则,并按项目风险调整数值:选择器优先使用稳定的 data-testid 或业务语义属性;新增测试必须能在无头模式执行;并行测试不得共享可变账号和下载目录;临时跳过必须绑定缺陷编号、责任人和到期日。
一个实用的交付验收表可以设为五项:全新环境按 RUNBOOK.md 能跑通;.env.example 不含秘密值;执行脚本同时生成 JUnit 与日志;失败用例有可定位到测试 ID 的证据目录;manifest 能还原 commit、Python、Selenium、浏览器和 worker 数。临时隔离用例建议设置不超过 14 天的到期日,过期后要么修复,要么重新评审原因,不能永久留在“以后再看”的状态。