📚 课程目录第4章快照回归测试的整体流程设计

快照回归测试的整体流程设计

做快照回归测试，说白了就是把每一次 CI 构建生成的页面、接口响应、DOM 结构等“拍个照片”，然后跟之前通过的基线比对。一旦对不上，说明代码改出问题了——要么是预期变化需要更新基线，要么就是引入了回归 bug。

我在好几个项目里踩过坑，最大的感受是：流程设计的好坏，直接决定你是花 5 分钟定位问题，还是花 5 天跟假告警死磕。

流程设计的核心思想

你想想看，快照回归不是简单的“通过/不通过”的判断题，它其实是一条质量流水线。我个人习惯把整个流程拆成三个大阶段：

准备阶段：搭好环境，准备好镜像和基线
执行阶段：跑测试，生成快照，做对比
分析阶段：判断差异是真是假，决定行动

这三个阶段缺一不可，而且每个阶段都有容易翻车的地方。下面我用一张图给你看全貌，然后再逐个拆解。

阶段一：准备环境与基线

这个阶段看似简单，但很多团队恰恰在这里出问题。我见过有人直接把生产环境的 Compose 文件拿过来用——结果测试跑了一小时，因为镜像太大、资源不够。

    关键点：Compose 文件必须精简。只包含被测服务和最小依赖（数据库、缓存等），别把监控、日志采集这些非必要服务带进来。

另一个容易忽略的是基线管理。快照基线一般是一个 JSON 或文本文件，存在项目仓库里。我建议用 git lfs 管理，不然每个版本都存一份全量快照，仓库体积会爆炸。

我的做法：每次更新基线时，在 commit message 里写明原因：“更新快照基线——因为前端按钮文案从‘提交’改为‘保存’”。这样回溯时能搞清楚每次变更的意图。

阶段二：执行快照测试

测试执行阶段是 CI 流水线的核心部分。我会让 Jenkins（或其他 CI 工具）先执行 docker compose up -d，然后等待服务健康检查通过，再开始跑测试。

这里有个常见的坑：服务启动顺序。我曾经在项目里遇到过数据库还没就绪，测试脚本就开始截图——结果页面上全是 502。后来我在 Compose 里加了 depends_on 加上健康检查，才彻底解决。

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:13
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 3s
      timeout: 2s
      retries: 5

执行快照测试的工具很多，比如 Jest snapshot、Playwright screenshot、BackstopJS 等。我个人偏好 Playwright，因为它能同时抓截图和 DOM 结构，方便后续对比。

测试脚本运行完后，会生成一份“新快照”。这时 CI 自动拿它跟“基线快照”做 diff。你想想看，这个 diff 不是简单的文件比对——它还涉及阈值判断。比如像素差异小于 0.1% 的可以忽略，只是反走样造成的。

注意：不要直接在全量差异上设置硬性通过/不通过。一定要先做“智能过滤”，排除动态元素（时间戳、随机 ID、CSRF 等）。否则你一天会被假告警烦死。

阶段三：差异分析与决策

差异报告出来后，人工介入是必要的。我习惯把报告分成三类：

差异类型	常见原因	处理方式
假阳性	动态内容、环境差异、字体缺失	调整过滤规则，重新测试
预期变更	需求变更、UI 改造	更新基线，关联需求单号
回归缺陷	代码 bug	修复代码，重新提交 CI

我记得有一次，团队成员看到快照差异就慌了，直接提了紧急修复单。结果排查了两小时，发现只是服务器时区设置不一样，导致时间显示差了 8 小时。从那以后，我们在测试环境强制统一时区和 locale，并在基线里提前标注好运行时参数。

如果是预期变更，那就更新基线。我建议用脚本自动更新，并带上对比日志，方便 code review 时确认。比如：

# 更新基线脚本（伪代码）
if diff $NEW_SNAPSHOT $BASELINE; then
    echo "一致，无需更新"
else
    echo "差异如下："
    diff $NEW_SNAPSHOT $BASELINE | head -20
    read -p "是否更新基线？(y/n) " -r
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        cp $NEW_SNAPSHOT $BASELINE
        git commit -m "chore: 更新快照基线"
    fi
fi

流程中的避坑指南

我总结了几条经验，你可以在自己的 CI 里直接套用：

并发问题：多个并行测试任务如果共享同一份基线，会导致竞争写入。我建议每个分支建独立基线副本，合并时再统一。
镜像缓存：每次构建 Compose 镜像时，别重新拉所有依赖。利用 Docker 的 layer cache，把 package.json 或 requirements.txt 单独复制，先装依赖后改代码。
快照目录清理：CI Worker 磁盘有限，记得定时清理过期的快照文件。我曾经一不留神攒了 10GB 的旧快照，把磁盘撑爆了。

    核心原则：快照回归不是“一次跑过就万事大吉”。它需要持续维护基线、持续过滤假阳性、持续优化流程。说白了，这是一项长期投资。

整体流程示例

最后给你一个能实际落地的流水线示例（Jenkinsfile 片段）：

pipeline {
    agent any
    stages {
        stage('准备环境') {
            steps {
                sh 'docker compose -f ci/docker-compose.test.yml pull'
            }
        }
        stage('启动服务') {
            steps {
                sh 'docker compose -f ci/docker-compose.test.yml up -d --build --wait'
            }
        }
        stage('运行快照测试') {
            steps {
                sh 'docker compose exec -T app npx jest --snapshot --ci'
            }
        }
        stage('比较快照') {
            steps {
                sh './scripts/compare-snapshots.sh'
            }
        }
        stage('报告与人工决策') {
            // 生成差异报告后，Jenkins 发邮件通知开发人员
            // 或直接暂停流水线等待输入
            input {
                message "快照回归存在差异，请检查报告并决定：更新基线 or 修复代码"
                ok "继续"
            }
        }
    }
}

你看，整体流程并不复杂，但每个环节都需要你根据自己项目的实际情况去微调。我曾经花了一周时间才把一套快照回归流水线调通，但之后它每个月帮我提前拦住了至少 3 个肉眼看不出来的 UI 回归 bug。嗯，这个投入很值。