在GitLab CI/CD中用Playwright保存基准图并解决像素差异问题

问题梳理 #

• GitLab CI环境无法像本地那样将生成的基准图保存回代码仓库
• Windows本地生成的基准图传到Linux CI环境后，因浏览器跨系统渲染差异导致像素对比失败
• 不想通过maxDiffPixels、threshold这类放宽对比精度的参数妥协，要保证视觉测试的准确性

解决思路：统一在CI环境生成&复用基准图 #

所有基准图都在与测试完全一致的GitLab CI环境中生成，彻底消除跨系统渲染差异，同时解决CI无法保存基准图的问题。

1. 新增基准图生成的CI任务 #

在.gitlab-ci.yml中添加一个手动触发的任务，专门生成并提交基准图到专用分支，测试任务直接拉取该分支的基准图进行对比。

修改后的配置示例：

stages:
  - 生成基准图
  - uat

生成基准图:
  rules:
    - if: $CI_COMMIT_BRANCH == "master"
      when: manual # 仅手动触发执行
  stage: 生成基准图
  image: 
    name: mcr.microsoft.com/playwright:v1.41.1    
    pull_policy: [always, if-not-present]
  script:
    - npm ci # 安装固定版本依赖，保证环境一致
    # 生成/更新基准图
    - ENV=UAT npx playwright test --update-snapshots
    # 配置Git提交信息
    - git config --global user.name "GitLab CI机器人"
    - git config --global user.email "ci@yourcompany.com"
    # 切换到基准图专用分支，提交并推送
    - git checkout -b base-images || git checkout base-images
    - git add base-images/
    - git commit -m "从CI更新基准图"
    - git push https://gitlab-ci-token:$CI_JOB_TOKEN@$CI_REPOSITORY_URL base-images
  artifacts:
    paths:
      - base-images/
    expire_in: 30 days # 临时备份基准图

test-uat:
  rules:
      - if: $CI_PIPELINE_SOURCE == "trigger"
        when: always
      - if: $CI_PIPELINE_SOURCE != "trigger"
        when: manual
      - if: $CI_COMMIT_BRANCH == "master"  
  stage: uat
  image: 
    name: mcr.microsoft.com/playwright:v1.41.1    
    pull_policy: [always, if-not-present]
  allow_failure: false
  script:
      - npm ci
      # 拉取基准图分支的内容到本地
      - git fetch origin base-images
      - git checkout origin/base-images -- base-images/
      - ENV=UAT npx playwright test 
  artifacts:
    paths:  
      - playwright-report/
      - test-results/
      - results.xml/
    when: always
    expire_in: 120 days
    reports:
        junit: results.xml

2. 配置CI权限 #

确保CI能推送基准图分支：

• 进入项目「Settings」→「Repository」→「Protected branches」，放开base-images分支的保护规则，允许CI推送
• 确认项目CI/CD变量中的CI_JOB_TOKEN拥有足够权限（默认配置即可，除非手动修改过权限）

3. 替代方案：用CI制品共享基准图 #

如果不想将基准图提交到代码仓库，可以将其设置为永久保存的CI制品，测试任务直接依赖该制品：

生成基准图:
  # 其他配置与上述一致
  artifacts:
    paths:
      - base-images/
    expire_in: never # 永久保存，或设置长有效期如365天

test-uat:
  # 其他配置不变
  dependencies:
    - 生成基准图 # 自动下载基准图制品
  script:
      - npm ci
      - ENV=UAT npx playwright test 

关键注意事项 #

• 所有基准图必须从CI环境生成，禁止在本地生成后提交，彻底规避跨系统渲染差异
• 锁定Playwright版本和Docker镜像版本，避免版本更新带来的渲染逻辑变化
• 每次页面UI更新后，手动触发「生成基准图」任务更新基准图

内容的提问来源于stack exchange，提问作者tedtrain