使用cypress-image-diff-js的Cypress测试在GitHub Actions中失败求助

我之前也碰到过一模一样的问题，本地Mac测试正常但Ubuntu环境的GitHub Actions一直失败，试过你列的那些方法后，最终靠这几个关键步骤解决了问题：

• 统一浏览器环境与渲染参数
  GitHub Actions的ubuntu-latest默认Chrome无头模式和本地带界面的Chrome在渲染逻辑上有差异，还可能存在版本不一致的情况。

  1. 在CI的yml文件中安装稳定版Chrome：

     - name: 安装稳定版Chrome
       run: sudo apt-get update && sudo apt-get install -y google-chrome-stable
     

  2. 在cypress.config.js中配置Chrome启动参数，消除环境渲染差异：

     e2e: {
       setupNodeEvents(on, config) {
         on('before:browser:launch', (browser = {}, launchOptions) => {
           if (browser.name === 'chrome' && browser.isHeadless) {
             launchOptions.args.push('--disable-gpu');
             launchOptions.args.push('--no-sandbox');
             launchOptions.args.push('--disable-dev-shm-usage');
             launchOptions.args.push('--force-device-scale-factor=1');
           }
           return launchOptions;
         });
         // 注册cypress-image-diff-js插件
         require('cypress-image-diff-js/dist/plugin')(on, config);
         return config;
       },
       viewportWidth: 1000,
       viewportHeight: 660
     }
     

• 在CI环境中生成并提交基准图
  本地Mac的Retina屏和Ubuntu普通屏幕的字体渲染、像素密度差异极大，本地生成的基准图在CI中必然不匹配。直接在GitHub Actions中生成基准图：

  1. 临时修改CI脚本，运行生成基准图的命令：

     - name: 生成基准图
       run: npx cypress run --env type=base
     

  2. 将生成的cypress-visual-screenshots/base目录下的所有文件提交到代码仓库，后续CI测试就用这套基准图做对比。

• 确保页面完全渲染再执行截图
  除了增加超时，还要针对动态资源做针对性等待：

  beforeEach(() => {
    cy.viewport(1000, 660);
    cy.visit('/your-target-page');
    // 等待页面完全加载完成
    cy.document().its('readyState').should('eq', 'complete');
    // 等待关键图片、动态元素渲染完成
    cy.get('.key-image').should('be.visible');
    // 可选：等待自定义字体加载（通过检查元素字体样式确认）
    cy.get('body').should('have.css', 'font-family', 'Your-Custom-Font');
  });
  

• 调整差异阈值忽略细微渲染差异
  不同环境的细微像素差异可以通过插件配置忽略，在插件注册时设置：

  require('cypress-image-diff-js/dist/plugin')(on, config, {
    snapshotDiffThreshold: 0.02, // 允许0.02%的像素差异，可根据实际情况调整
    failOnSnapshotDiff: true
  });
  

按这些步骤配置后，我的cypress-image-diff-js测试在GitHub Actions的ubuntu-latest环境中就能稳定通过了。

内容的提问来源于stack exchange，提问作者Noor Yeaser Khan