如何在Playwright中本地禁用toHaveScreenshot截图断言？

1. 环境变量条件跳过断言 #

直接在测试代码里判断运行环境，仅在CI环境执行截图断言：

test('组件渲染正常', async () => {
  const { container } = render(<TargetComponent />);
  
  // 仅CI环境触发截图校验
  if (process.env.CI) {
    await expect(container).toHaveScreenshot();
  }
});

也可以自定义本地环境变量（比如启动测试时加LOCAL_DEV=true），反向判断跳过：

if (!process.env.LOCAL_DEV) {
  await expect(container).toHaveScreenshot();
}

2. 自定义重写toHaveScreenshot匹配器 #

在测试框架的全局配置文件（如Jest的jest.setup.js）中重写匹配器，根据环境切换行为：

import { expect } from '@jest/globals';

expect.extend({
  async toHaveScreenshot(received, options) {
    // 本地环境直接返回断言成功
    if (!process.env.CI) {
      return {
        pass: true,
        message: () => '本地环境跳过截图校验'
      };
    }
    // CI环境调用原始匹配器逻辑
    const originalMatcher = expect.getState().matchers.toHaveScreenshot;
    return originalMatcher.call(this, received, options);
  }
});

注：Vitest等其他测试框架的写法类似，核心是通过环境判断决定是否执行原始校验逻辑。

3. Mock全局截图断言方法 #

用测试框架的Mock功能直接替换toHaveScreenshot，让本地环境下始终通过断言：

// 在测试文件或全局setup文件中
if (!process.env.CI) {
  jest.mock('@testing-library/react', () => {
    const original = jest.requireActual('@testing-library/react');
    return {
      ...original,
      toHaveScreenshot: () => Promise.resolve({ pass: true })
    };
  });
}

这种方式无需修改现有测试代码，一次性全局生效。

补充：为什么maxDiffPixelRatio=1无效？ #

这个参数是允许像素差异的比例，但部分测试库会强制校验基准截图的存在性，或者该参数的生效逻辑并非完全允许所有像素差异，因此直接跳过断言是更彻底的解决方案。

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