自动化测试 / 系统课时
建立测试交付规范
建立测试交付规范
自动化测试能否长期使用,取决于别人是否能在没有口头说明的情况下复现运行、知道该配置什么、失败后去哪里取证,并清楚谁负责修复。交付规范的目标不是写更多文档,而是把运行入口、环境契约、失败证据和维护边界固定下来。
学习目标
- 定义一套最小但完整的 Playwright 测试交付物
- 固化可复现的运行入口、环境变量要求和失败证据
- 建立报告、测试数据与维护责任的长期约定
把交付物定义成明确契约
一套可接手的 Playwright 项目,至少要让接手者回答四个问题:怎么运行、需要什么环境、失败后看什么证据、谁维护什么。推荐把这些信息放在仓库中,与测试代码一起版本化,而不是散落在聊天记录或个人笔记里。
| 交付项 | 最低要求 |
|---|---|
| 运行说明 | 安装命令、执行命令、常用筛选方式 |
| 环境配置 | 必需变量、来源、是否敏感、缺失时行为 |
| 失败证据 | trace、失败截图、视频或日志的保留策略 |
| 测试报告 | 报告格式、产物目录、CI 中的保存位置 |
| 维护约定 | 目录边界、测试数据所有权、失败处理责任 |
规范越具体,CI 失败时越少依赖“找原作者问一下”。
用配置固定失败证据
下面给出一个完整的 playwright.config.ts。它要求必须提供 BASE_URL,同时把失败截图、失败视频、trace 和 HTML 报告的输出位置固定下来。
import { defineConfig } from '@playwright/test';
const baseURL = process.env.BASE_URL;
if (!baseURL) {
throw new Error('BASE_URL is required');
}
export default defineConfig({
testDir: './tests',
use: {
baseURL,
trace: 'retain-on-failure',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
reporter: [
['line'],
['html', { outputFolder: 'playwright-report', open: 'never' }],
],
outputDir: 'test-results',
});这个配置的生效行为是:缺少 BASE_URL 时测试在启动阶段直接失败;测试失败后,运行证据进入 test-results,HTML 报告写入 playwright-report。CI 应把这两个目录作为流水线产物保存,而不是只保留控制台日志。
固化唯一的标准运行入口
运行说明中不要只写“执行 Playwright”。应给出从干净工作区开始的标准命令,并明确 CI 与本地是否使用同一入口。若团队使用 Playwright 支持的 Linux CI runner,一个常见基线可以写成:
npm ci
npx playwright install --with-deps
: "${BASE_URL:?BASE_URL is required}"
npx playwright test预期输出:
<VALUE> passed (<TIME>)<VALUE> 和 <TIME> 取决于实际测试集。若执行失败,交付规范应要求同时收集 test-results 和 playwright-report,这样接手者能从同一份证据继续定位,而不是重新猜测失败现场。
约定环境变量和测试数据边界
环境变量应按“名称、用途、是否敏感、缺失时行为”登记。必需变量最好在配置加载阶段就失败,避免测试运行到中途才出现难以理解的空值错误。
测试数据也要声明所有权。可以重复创建的数据应由测试自己准备并清理;共享账号、固定订单号、公共文件等资源则必须注明是否允许并发使用。若数据只能串行访问,就应在规范中直接写明,不要把约束藏在某个测试实现里。
报告和维护责任必须可追溯
测试报告不是“跑完看看绿不绿”,而是一次可审计的交付结果。CI 至少要保留执行结果、HTML 报告和失败证据,并给产物设置与团队排障周期匹配的保存时间。
维护约定还应说明:目录由谁负责、失败由谁首查、业务变更后谁更新断言、长期跳过的测试何时必须清理。对不稳定测试,应该记录负责人和修复条件,不能把无限期 test.skip 当成最终方案。
当一个新成员只根据仓库里的运行说明和配置,就能在干净环境中启动测试、找到失败证据并知道下一步联系谁,这套测试才算真正完成交付。