使用Storybook背景插件时Jest快照出现随机颜色偏移问题求助

问题根源 #

• 这是Storybook依赖的无头浏览器截图工具（比如Puppeteer/Playwright）在渲染时的颜色处理差异问题。无头模式下浏览器的渲染引擎和正常浏览器的颜色空间转换、抗锯齿逻辑有细微区别，加上快照生成时的自动压缩，会把纯黑#000000转换成rgb(2,2,2)这类接近值。
• 另外，Webpack缓存或异步渲染时机不一致，会导致这种色差随机出现——每次测试时组件渲染的时序略有不同，最终生成的快照背景色就不一样。

解决办法 #

1. 强制覆盖背景样式优先级 #

直接在Story参数里给容器添加高优先级的内联样式，避免addon的背景设置被其他样式干扰：

export const smallDarkRadioButton = Template.bind({})
smallDarkRadioButton.parameters = { 
  backgrounds: { default: 'dark' },
  styles: {
    body: { backgroundColor: '#000000 !important' },
    '#storybook-root': { backgroundColor: '#000000 !important' }
  }
}

2. 调整截图工具的渲染配置 #

如果用Storybook Test Runner（基于Playwright），在配置里禁用颜色压缩并强制设置背景：
创建.storybook/test-runner.js文件，添加以下内容：

module.exports = {
  async setup(page) {
    await page.emulateMedia({ colorScheme: 'dark' });
    await page.setViewportSize({ width: 1280, height: 720 });
    // 强制注入背景样式，禁用抗锯齿
    await page.addStyleTag({ content: `
      body, #storybook-root {
        background-color: #000000 !important;
        image-rendering: pixelated;
      }
    `});
  },
};

3. 关闭无头浏览器的抗锯齿 #

如果用Puppeteer作为截图工具，在启动参数里添加抗锯齿禁用项，消除渲染时的颜色模糊：

// 示例：在Puppeteer启动配置中添加
const browser = await puppeteer.launch({
  args: ['--disable-antialiasing'],
  headless: true
});

4. 放宽快照对比的色差阈值 #

如果无法彻底消除色差，可以让快照测试工具忽略细微的颜色差异，比如在Jest中调整阈值：

// jest.config.js
module.exports = {
  snapshotSerializers: ['jest-puppeteer-snapshot/serializer'],
  setupFilesAfterEnv: ['<rootDir>/setup-jest.js'],
};

// setup-jest.js
expect.extend({
  toMatchImageSnapshot(received, options = {}) {
    return expect(received).toMatchImageSnapshot({
      ...options,
      customDiffConfig: { threshold: 0.01 }, // 阈值越小越严格，按需调整
    });
  },
});

5. 确保背景样式加载顺序正确 #

在preview.js中注入全局CSS，强制暗模式下的背景色：

// .storybook/preview.js
import './global-preview.css';

// global-preview.css
body[data-storybook-background="dark"] {
  background-color: #000000 !important;
}

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