GitLab CI/CD 中的视觉测试是在 .gitlab-ci.yml 定义的 pipeline 中集成自动化的截图捕获和比较步骤，利用 artifacts 存储截图、利用 environments 为结果提供上下文，以便在 merge request 被接受之前检测任何视觉回归。
GitLab CI/CD 是 GitHub Actions 的直接竞争对手。如果你为技术栈选择了 GitLab——数百万团队已经这样做了——你就拥有了一个强大的原生 CI/CD 系统，与你的代码管理器深度集成。而这个系统拥有使其特别适合视觉测试的功能。
然而，有多少 .gitlab-ci.yml 文件包含视觉验证步骤？非常少。大多数只是构建、功能测试代码然后部署。应用的外观——用户真正看到的——只在手动验证时才被检查，如果有人检查的话。
我们的立场：GitLab CI 非常适合视觉测试，得益于其 artifacts 和 environments。 这两个经常被低估的功能提供了存储截图、比较分支间结果以及为回归提供上下文的理想基础设施。如果你使用 GitLab 但没有进行视觉测试，你正在浪费 pipeline 的潜力。
目录
- GitLab CI 为视觉测试提供了什么特别之处
- 视觉盲区 Pipeline 的问题
- 在 .gitlab-ci.yml 中配置视觉测试
- 利用 Artifacts 存储截图
- 将 Environments 作为比较上下文
- 与 Merge Requests 的集成
- No-Code 方法：从根本上简化配置
- 常见陷阱和解决方案
- 常见问题
- 结论
GitLab CI 为视觉测试提供了什么特别之处
GitLab CI 拥有其竞争对手没有的功能——或者没有做得那么好。对于视觉测试，其中三个特别有价值。
Artifacts：你的截图库
GitLab CI 中的 artifacts 允许你保存 job 产生的文件，并在 pipeline 执行后使其可访问。对于视觉测试，这正是你所需要的。
每次 pipeline 执行都会产生截图。这些截图必须保留，原因有二。首先，让团队在测试失败时可以查看。其次，作为未来比较的基准。
GitLab artifacts 提供精细的保留管理。你可以保留最近七天的截图，或主分支保留三十天。你可以直接从 GitLab 界面下载，或通过内置的 artifact 浏览器查看。
Environments：为截图提供上下文
GitLab environments 允许你将部署与命名的上下文关联（staging、production、review/feature-xyz）。对于视觉测试，这意味着每张截图都绑定到特定的 environment。
当你将 feature 分支部署到 review environment 时，捕获的截图与该 environment 关联。你可以将 review environment 的截图与 staging 或 production environment 的截图进行比较。这是很少有 CI/CD 系统原生提供的可追溯性级别。
内置的 artifact 浏览器
GitLab 在 web 界面中直接提供文件浏览器来浏览 artifacts。对于视觉测试，这意味着你的团队可以查看截图、视觉差异和比较报告，而无需离开 GitLab。无需打开第三方工具。无需跟随外部链接。一切都在同一个生态系统中。
视觉盲区 Pipeline 的问题
让我们回顾事实。典型的 GitLab CI pipeline 执行以下阶段：lint、单元测试、集成测试、build、deploy。五个阶段。零视觉验证。
这个 pipeline 能告诉你函数是否返回了错误的结果。它无法告诉你首页的一半是否被错误定位的组件遮挡。
现实生活中会发生这样的事。开发者修改了一个共享的 CSS 文件。更改很小：调整组件的 margin。Pipeline 通过了。Merge request 被一个只读了 diff 而没有可视化渲染的 reviewer 批准了。合并完成。
三天后，客户报告定价页面在手机上无法阅读。修改的 margin 在六个其他页面使用的 flexbox 布局上产生了级联效应。没有人看到，因为没有人去看——无论是人还是 pipeline。
自动化视觉测试是这个问题的系统性解决方案。 不是更仔细的代码审查。不是更严格的手动 QA。而是 pipeline 中的自动化测试，比较前后图像并标记任何差异。
在 .gitlab-ci.yml 中配置视觉测试
在 GitLab CI 中配置视觉测试 pipeline 遵循明确的分步逻辑。以下是 .gitlab-ci.yml 文件的概念结构。
Pipeline 结构
你的 pipeline 必须按以下顺序包含这些阶段。
Build 阶段。 编译你的应用并使其准备就绪。这可能已经在你的 pipeline 中了。
视觉测试阶段。 这是新阶段。它启动本地服务器、捕获截图、与基准比较并生成报告。此阶段必须在 build 之后运行，其结果必须存储为 artifacts。
Deploy 阶段。 只有在所有测试——包括视觉测试——通过时才运行。
视觉测试 job 的依赖
视觉测试 job 需要 headless 浏览器来捕获截图。在 GitLab CI 中，你有两个选择。使用已包含 Chromium 的 Docker 镜像（如官方 Playwright 镜像），或在 job 中通过 before_script 命令安装 Chromium。
Docker 镜像更可取。它可复现、快速（无需每次运行都安装）且保证固定的浏览器版本。
存储结果
视觉测试 job 必须产生几种类型的文件作为 artifacts。本次运行中捕获的截图。显示检测到差异的视觉差异。总结结果的 HTML 或 JSON 报告。
配置适当的保留策略。主分支的截图应保留更长时间（用作基准）。Feature 分支的截图只需保留几天。
阻止条件
视觉测试 job 必须配置为阻止性 job。如果检测到未批准的差异，pipeline 必须失败。没有警告。没有"continue on failure"。明确的失败以阻止合并。
利用 Artifacts 存储截图
GitLab CI artifacts 是你视觉测试策略的支柱。以下是如何充分利用它们。
以可读的方式组织 artifacts
在 artifacts 中将截图组织成清晰的树状结构。为每个测试页面创建一个文件夹，包含基准截图、当前截图和差异。根目录的 HTML 报告允许在结果间导航。
这种结构方便 reviewer 查看。当测试失败时，reviewer 打开 artifact 浏览器，导航到受影响的页面，立即看到差异。
使用 artifacts 作为基准
主分支的 artifacts 可以作为 feature 分支比较的基准。GitLab CI 允许通过 API 从特定分支的特定 job 下载 artifacts。
具体来说，你的 feature 分支的视觉测试 job 首先从主分支上最后一次成功 pipeline 的 artifacts 中下载基准截图。然后捕获 feature 分支的截图。比较两组截图。将结果存储为当前 pipeline 的 artifacts。
智能管理保留期
GitLab artifacts 有可配置的保留期。对于视觉测试，两级策略效果很好。主分支 artifacts 保留 30 天（或更长）。作为稳定基准。Feature 分支 artifacts 保留 7 天，足够处理 merge request。
将 Environments 作为比较上下文
GitLab environments 为你的视觉测试增加了额外维度。它们允许你将每组截图绑定到部署上下文。
Review apps 作为测试场地
如果你使用 GitLab 的 review apps（每个 feature 分支的临时部署），你拥有每个分支的唯一 URL。视觉测试可以直接从此 URL 捕获截图，提供比 CI 中本地服务器更真实的渲染。
优势是双重的。渲染是真实环境的渲染（不是开发服务器）。Review app 的 URL 对整个团队可访问，便于作为自动测试补充的手动验证。
在 environments 间比较
Environments 允许你在上下文间比较截图。你可以将 feature 分支的 review app 与 staging environment 比较。或将 staging 与 production 比较以检测视觉漂移。
这种跨 environment 比较能力是 GitLab CI 用于视觉测试的主要优势。它不仅能检测分支引入的回归，还能检测环境间累积的漂移。
与 Merge Requests 的集成
视觉测试只有在结果可见且可操作时才有价值。与 GitLab merge requests 的集成是理想的载体。
Merge request widgets
GitLab 直接在 merge request 上显示 pipeline 结果。视觉测试 job 的状态出现在 check 列表中。点击可查看 job 日志和 artifacts。
自动评论
配置你的 pipeline 在检测到视觉差异时自动在 merge request 上发表评论。此评论应包含摘要（受影响的页面数量、变更严重程度）和 artifacts 中完整报告的链接。
批准预期变更
当视觉变更是有意的（重新设计、颜色变更）时，必须有批准变更和更新基准的机制。在 GitLab 中，这可以通过 pipeline 中按钮触发的手动 job 来完成。开发者或 QA 查看差异，确认它们是预期的，然后触发基准更新。
No-Code 方法：从根本上简化配置
上述所有方法都可行，但需要在配置和维护方面进行大量投入。No-code 方法大幅降低了这种复杂性。
使用 Delta-QA 这样的工具，集成到 GitLab CI 只需添加一个用项目参数调用工具的 job。工具负责 headless 浏览器、捕获、比较、基准管理和报告。
你不需要管理包含 Chromium 的 Docker 镜像。不需要编写捕获脚本。不需要实现比较系统。不需要构建 HTML 报告。
主要优势不是初始的简单性——而是长期维护。 手工制作的视觉测试 pipeline 需要持续维护：更新浏览器、调整阈值、在 UI 变化时修复捕获脚本。No-code 工具吸收了这种复杂性。
你的 .gitlab-ci.yml 文件保持整洁。Pipeline 保持快速。团队可以专注于重要的事：分析结果并决定变更是否符合预期。
常见陷阱和解决方案
大型 Docker 镜像陷阱
包含 headless 浏览器的 Docker 镜像很大（通常超过 1 GB）。如果每次运行都下载，会给 pipeline 增加数分钟。使用带缓存的私有 Docker registry，或在共享 runner 上使用预安装的镜像。
屏幕分辨率陷阱
GitLab CI runner 没有物理屏幕。Headless 浏览器使用虚拟 framebuffer。此 framebuffer 的分辨率必须与你的测试 viewport 匹配。如果你以 1920x1080 捕获但 framebuffer 配置为 1024x768，你会得到被截断或调整大小的截图。
异步内容陷阱
现代应用异步加载内容。在开发中响应 200 毫秒的 API 在 CI 中可能需要 2000 毫秒（不同的网络、共享资源）。等待所有网络调用完成且内容渲染后再捕获。
长期分支基准管理陷阱
如果 feature 分支持续数周，主分支的基准可能已经演变。比较时，你检测到的差异来自 main 的演变，而不是你的分支。解决方案是定期将分支 rebase 到 main，或在每次运行时下载最新的基准。
常见问题
GitLab CI 中视觉测试应该使用哪个 Docker 镜像？
官方 Playwright 镜像（mcr.microsoft.com/playwright）是绝佳选择。它们包含 Chromium、Firefox 和 WebKit，以及所有必要的系统依赖。如果你只使用 Chromium，可以使用基于 Alpine 的更轻量的 Puppeteer 镜像。对于 Delta-QA 这样的 no-code 工具，Docker 镜像是提供的且针对此用途优化的。
截图 artifacts 应该保留多长时间？
对于主分支，至少保留 artifacts 30 天。它们作为所有比较的基准。对于 feature 分支，7 天通常足够——足以处理和合并 merge request。根据你的开发节奏进行调整。开发周期较长的团队需要更长的保留期。
视觉测试能在 GitLab.com 的共享 runner 上工作吗？
能。GitLab.com 的共享 runner（SaaS）支持视觉测试。它们使用能运行 headless 浏览器的 Docker 虚拟机。但是，性能可能因共享 runner 的负载而异。如果稳定性和速度至关重要，专用或自托管的 runner 提供更好的控制。
如何处理 GitLab CI 和开发机器之间的渲染差异？
你的本地机器和 CI runner 之间的渲染差异是不可避免的。安装的字体、浏览器版本和 framebuffer 分辨率各不相同。规则很简单：永远不要将本地截图与 CI 截图进行比较。基准必须始终在与测试截图相同的环境中生成。如果你的基准在 CI 中，你的比较就在 CI 中进行。
能在 GitLab CI 中并行化截图捕获吗？
当然可以，对于有很多页面需要测试的项目，这是推荐的。GitLab CI 通过配置中的 parallel 关键字支持并行化。你可以将页面分配到同时运行的多个 job 中。每个 job 捕获页面子集并将截图存储为 artifacts。最终 job 聚合结果。这种方法将捕获时间除以并行 job 的数量。
GitLab CI 中的视觉测试支持 monorepo 吗？
支持，但需要特定配置。在 monorepo 中，你可能有多个前端应用。使用 GitLab CI rules 仅在相关应用的文件被修改时触发视觉测试。每个应用可以有自己的基准集和视觉测试 job。Artifacts 必须按应用组织以避免冲突。
结论
GitLab CI/CD 拥有原生功能——artifacts、environments、review apps、artifact 浏览器——使其成为非常适合视觉测试的平台。这不是巧合。这是架构上的汇聚：视觉测试需要存储文件、比较上下文并使结果可访问。GitLab 原生地做到了所有这些。
如果你使用 GitLab 而你的 pipeline 不检查应用的外观，你正在低估你的工具。你有基础设施。你只是缺少这一步。
将视觉测试添加到你的 GitLab CI pipeline 不是数字化转型项目。它是 .gitlab-ci.yml 文件中的一个 stage、一组初始基准和一个变更审批流程。使用 Delta-QA 这样的 no-code 工具，更加简单：几分钟完成集成，每个 merge request 自动受到视觉回归保护。
你的用户看到你的应用。你的 pipeline 也应该看到它。