GitLab CI 视觉测试:将视觉测试集成到您的 GitLab 流水线

GitLab CI 视觉测试:将视觉测试集成到您的 GitLab 流水线

视觉测试(visual testing)是一种自动化验证方法,在两个版本之间比对 Web 界面的截图,以发现图形层面的回归(元素移位、颜色改变、组件溢出其容器)。

在 Delta-QA,我们每天都在使用 GitLab。我们的仓库、流水线、merge request、CI/CD:一切都运行在 GitLab 上。这不是默认的选择,而是经过深思熟虑的决定:这个平台原生提供集成的流水线、容器镜像仓库,以及端到端一致的 DevOps 理念。

当我们谈论 GitLab CI 中的视觉测试时,我们不是在复述前一天刚读过的文档。我们分享的是在实际使用中学到的东西。本文涵盖可用的方式、影响视觉测试的 GitLab CI 特性,以及如何得到一条可靠的视觉回归流水线。

一页读懂(定义、无代码自动化、工具选择表):自动化回归测试,无需代码。

还没准备好动您的 .gitlab-ci.yml? 先在流水线之外上手视觉测试:Delta-QA 以无代码方式比对您的页面,提供免费账户,无需绑定银行卡。免费使用 Delta-QA →

为什么 GitLab CI 很适合视觉测试

GitLab CI 有一些特性,使它特别适合视觉测试,而这些特性是 GitHub Actions 或 Jenkins 用户默认没有的。

原生 artifacts

GitLab CI 原生管理流水线 artifacts。视觉测试生成 HTML 报告、diff 图像或截图时,您把它们声明为 artifacts,就可以直接从 merge request 界面访问。无需外部服务来存储和查看结果。

这是一个被低估的优势。使用 GitHub Actions 时,您必须配置单独的 artifact 上传,或使用第三方服务才能让结果可访问。使用 GitLab,这是原生的。

评审环境

GitLab 提供 Review Apps:为每个 merge request 自动部署的临时环境。您的应用运行在专用环境中,可通过临时 URL 访问。这是视觉测试的理想环境:稳定、隔离,并且能代表生产环境。

自管 runner

GitLab 允许使用托管在您自己基础设施上的 runner。对视觉测试而言,这至关重要:您控制渲染环境(操作系统、字体、GPU),从而减少由环境差异引起的误报。我们使用配置固定的专用 runner,以保证截图的可复现性。

内置容器镜像仓库

每个 GitLab 项目都有一个容器镜像仓库。您可以在其中存放为视觉测试预先配置好的 Docker 镜像(带有合适的字体、合适的浏览器、合适的依赖),并把它作为测试作业的基础。这消除了不稳定的一大来源。

GitLab CI 中视觉测试的几种方式

GitLab CI 作业中的 Playwright

Playwright 是 CI 中视觉测试最稳健的开源工具。其原生的 toHaveScreenshot() 方法负责截图、比对和自动重试。

与 GitLab CI 的集成。 您在 .gitlab-ci.yml 中创建一个作业,使用 Playwright 官方 Docker 镜像,运行测试,并把结果作为 artifacts 发布。Playwright 的 HTML 报告可以直接在 GitLab 中查看。

关于 YAML 文件的确切结构,请问您的 AI 副驾(它对 GitLab CI 语法了如指掌,这几乎是它唯一不会(暂时)胡编乱造的东西)。更严肃地说,Playwright 官方针对 CI 环境的文档是您最好的参考。

做得好的方面。 Playwright 官方 Docker 镜像包含所有浏览器和必要的系统依赖。结合 GitLab 容器镜像仓库,您可以创建带有您自己的字体和特定配置的派生镜像。GitLab artifacts 让测试报告无需额外配置即可访问。

在 GitLab 语境下的局限。 基线必须在 CI 环境中生成,而不是本地。这是视觉测试的普遍规则,但 GitLab 让事情更容易:您可以手动触发一条流水线来重新生成基线。在 Git 中管理基线仍是一个挑战(二进制文件、合并冲突),不过 GitLab 原生集成了 LFS。

在 GitLab CI 中使用 Percy

Percy(BrowserStack)提供与 GitLab CI 的官方集成。Percy SDK 在您的流水线中捕获快照,并发送到 Percy 云端进行比对和评审。

好的方面。 Percy 会自动检测 GitLab 的分支和 merge request。结果会作为外部状态显示在您的 MR 上。跨浏览器由云端处理。

局限。 按快照计费仍是个问题。而且您给流水线增加了一个外部依赖:如果 Percy 不可用,您的 check 就会一直处于等待状态。对于恰恰因为想掌控自己的基础设施而选择了 GitLab 的团队,这种外部依赖可能与其理念相悖。

GitLab CI 中的 BackstopJS

BackstopJS 通过其官方 Docker 镜像在 GitLab CI 中运行。HTML 报告与 GitLab 的 artifacts 系统完全契合。

好的方面。 BackstopJS 的 HTML 报告是生态中最直观、最易读的之一。作为 GitLab artifact 发布后,可以直接在浏览器中从 MR 界面查看。基于 JSON 场景的配置清晰明确,且可纳入版本管理。

局限。 该项目经历过断断续续的维护期(投入之前请先查看其最近的活跃度)。对于复杂的应用,配置可能变得冗长,并且您需要手动处理对页面或组件的遍历。

GitLab CI 中的 Delta-QA:Vision SDK

Delta-QA 通过您的 Playwright 测试和 Vision SDK 进入 GitLab CI 流水线。

工作方式。 您把 API 密钥放入一个被屏蔽的 CI/CD 变量(DELTAQA_API_KEY),并在测试需要检查的页面中加入 vision.check()。作业照常运行 npx playwright test。对每个 check,Delta-QA 会像人眼那样将页面与其参考比较:它找出发生变化的元素,并在报告中指明。

有什么不同。 无需在仓库中存放基线:参考存放在您的 Delta-QA 空间中,每个分支一份;SDK 既不读取 git,也不读取 CI:由您作业中的一行把分支、基础分支和 commit 交给它。存在未判定的差异时作业失败,其日志会给出报告链接,报告会告诉您哪个元素发生了变化;您在那里判定"有意"或"缺陷"。给出同一个 commit 的测试构成同一个版本,即使分布在多个并行作业上也是如此。

以及无代码方式。 QA 团队在 Delta-QA 中录制的流程,在同一个空间中判定。该 SDK 支持 TypeScript 和 JavaScript 的 Playwright,运行于 Chromium;它目前先以抢先体验的方式提供,可从其页面申请访问权限。

在编写任何一个 CI 作业之前,先衡量视觉测试在您的页面上能发现什么。 Delta-QA 只需几次点击就能捕获并比对您的页面,提供免费账户,无需绑定银行卡。免费使用 Delta-QA →

视觉测试中需要了解的 GitLab CI 特性

缓存与 artifacts

这是很多人搞混的区别。GitLab CI 的缓存在同一项目的各条流水线之间共享(用于加速作业:npm 依赖、Playwright 浏览器)。Artifacts 则是某个特定作业的输出:测试报告、截图、diff。

对于视觉测试,用缓存存放浏览器和依赖,用 artifacts 存放测试结果。切勿缓存基线(它们必须存放在仓库里,才能与代码一起纳入版本管理)。

阶段与作业之间的依赖

GitLab CI 把作业组织成顺序的阶段(stages)。视觉测试必须位于在您的 Review App 部署之后执行的阶段。一种常见模式:

  1. build:编译应用
  2. deploy-review:部署 Review App
  3. test-visual:对 Review App 做视觉测试
  4. cleanup:删除该环境

GitLab CI 的 needs 指令可以在作业之间创建显式依赖,而无需依靠顺序阶段,这能加快您的流水线。

受保护的环境变量

云服务(Percy、Chromatic)的 API token 必须作为 CI/CD 变量存放在 GitLab 中。注意:受保护的变量只在受保护的分支上可用。如果您的功能分支没有被保护,使用云服务的视觉测试会悄无声息地失败:这是一个经典的陷阱。

时间和内存限制

视觉测试很吃资源。在无头浏览器中渲染页面会消耗内存,图像比对也需要时间。GitLab.com 的共享 runner 有时间限制(通常每个作业一小时)和内存限制。对于规模可观的视觉测试套件,建议使用资源专用的自管 runner。

构建稳健的视觉测试流水线

下面是我们基于自身经验推荐的做法。

从小处、有针对性地开始

不要第一天就对所有页面做视觉测试。找出最关键的五到十个页面(用户首先看到的页面,视觉回归对业务影响最大的页面)。然后再逐步扩大。

以 Review Apps 作为目标

与其在 CI 作业中启动本地服务器,不如部署一个 Review App 并对其进行测试。优点:环境稳定、可访问,并具有代表性。缺点:流水线要加上部署的时长。这个折中是值得的。

稳定您的渲染环境

创建一个专用于视觉测试的 Docker 镜像,存放在您的 GitLab 镜像仓库中。包含您的应用所用的字体、浏览器的精确版本以及所有系统依赖。对该镜像做版本管理。当渲染环境固定之后,误报会急剧下降。

从非阻塞模式开始

在最初的几周里,用 allow_failure: true 配置您的视觉测试作业。这能让团队在视觉测试不阻塞 merge request 的前提下熟悉结果。待建立信心、误报得到控制之后,再切换为阻塞模式。

聪明地通知

GitLab CI 可以通过不同渠道(Slack、电子邮件、webhook)发送通知。请把视觉测试的通知配置为仅在失败时提醒,而不是在成功时。目的是在必要时引起注意,而不是用消息淹没团队。

把 artifacts 用作参考系统

GitLab artifacts 不只是用来发布报告:组织得当的话,它们会成为您参考策略的脊梁。有两项做法会带来差别。

以易读的方式组织 artifacts

不要把所有截图平铺堆放。建立清晰的目录结构:每个被测页面一个文件夹,里面放参考截图、当前截图和 diff。在根目录放一份 HTML 报告,用于在各项结果之间导航。测试失败时,评审者打开 GitLab 内置的 artifacts 浏览器,进入相关页面,无需离开界面就能立刻看到差异。

把 main 的 artifacts 用作参考

与其把基线存放在仓库中,您可以利用主分支上最近一次成功流水线的 artifacts 作为参考集。GitLab CI 允许通过其 API 下载特定分支上某个特定作业的 artifacts。

具体来说,您的功能分支的视觉测试作业首先从最近一次 main 流水线的 artifacts 中下载参考截图。然后它截取功能分支的截图,比对两组图像,并把自己的结果作为当前流水线的 artifacts 存储。没有任何二进制基线会污染您的 Git 历史。

两级保留策略

GitLab artifacts 的保留时长是可配置的,对于视觉测试,分为两档的策略效果不错:

  • 主分支:30 天(或更长)。 这些 artifacts 作为所有比对的稳定参考。
  • 功能分支:7 天。 足够 merge request 被处理并合并。

请根据您的节奏调整:周期较长的团队(分支存活数周)需要在 main 上有更长的保留期,并且应定期 rebase,或在每次运行时重新下载最新的参考,以避免与过期的基线比较。

常见问题

做视觉测试,GitLab CI 和 GitHub Actions 一样好吗?

仅就视觉测试而言,GitLab CI 有一些原生优势:内置 artifacts、Review Apps、容器镜像仓库和自管 runner。这些功能使得搭建稳定、可复现的视觉测试环境更容易。GitHub Actions 有自己丰富的 marketplace,但其中一些功能需要额外配置。

GitLab CI 中的视觉测试需要自管 runner 吗?

不是必须的,但强烈推荐。GitLab.com 的共享 runner 可以用,但其硬件配置不固定,可能带来渲染差异。配置固定(字体、浏览器、分辨率)的自管 runner 能消除这个误报来源,通常性能也更好。

如何在 GitLab 仓库中管理视觉测试基线?

如果使用 Playwright 或 BackstopJS,基线(PNG 文件)存放在您的仓库中。启用 GitLab LFS,避免二进制文件让您的 Git 历史膨胀。对于基线上的合并冲突,最简单的策略是接受来源分支的新基线,必要时重新生成。使用 Delta-QA 时,基线由工具管理,不会污染您的仓库。

能把 GitLab 的 Review Apps 用作视觉测试环境吗?

可以,这正是我们推荐的方式。Review App 为每个 merge request 提供稳定且隔离的环境。您的视觉测试作业等待 Review App 部署完成,在临时 URL 上截图,并与参考比对。这比在 CI 作业中即时启动的服务器更可靠。

GitLab CI 中的视觉测试适用于 monorepo 吗?

适用。GitLab CI 支持条件规则,只在前端文件被修改时才触发视觉测试。结合 only:changes 指令,您可以避免在只有后端变化时执行不必要的视觉测试。这对于在 monorepo 中保持流水线快速至关重要。

GitLab CI 视觉测试的最佳 Docker 镜像是什么?

Playwright 官方镜像(mcr.microsoft.com/playwright)是极好的起点。它包含浏览器和系统依赖。若要环境更稳定,可创建派生镜像,加入您应用的字体并固定精确版本。把它存放在您的 GitLab 项目的容器镜像仓库中,以便快速访问。

结论

GitLab CI 是一个天然适合视觉测试的平台。它的原生功能(artifacts、Review Apps、容器镜像仓库、自管 runner)解决了其他 CI 平台需要手动处理的问题。

但平台并不能包办一切。CI 中的视觉测试仍然是一项工程挑战:稳定渲染、管理基线、处理误报,以及构建一个对整个团队都行之有效的评审工作流。

如果您使用 GitLab,并希望在不引入测试脚本和手动基线管理之复杂性的前提下为流水线添加视觉测试,Delta-QA 的设计就是为了原生融入您的 GitLab CI 工作流。

准备好用视觉测试让您的 merge request 更可靠了吗? 在动您的 .gitlab-ci.yml 之前,先用 Delta-QA 发起您的第一次比对,免费,无需绑定银行卡。免费使用 Delta-QA →