Vitest快照类名不匹配求助（Vite+React+MUI项目）

MUI默认依赖Emotion生成带哈希的类名，这类哈希会随测试上下文（比如新增测试导致的模块加载顺序变化）改变，即使组件代码未修改，也会触发快照不匹配。以下是几种可行的解决办法：

1. 使用Emotion的快照序列化器（推荐） #

@emotion/jest提供的序列化器会自动处理类名中的哈希，将其替换为稳定的占位符，避免快照因哈希变化失效。

步骤：

• 安装依赖：

  npm install -D @emotion/jest
  

• 在vitest.config.js中配置序列化器：

  import { defineConfig } from 'vitest/config';
  import react from '@vitejs/plugin-react';
  
  export default defineConfig({
    plugins: [react()],
    test: {
      environment: 'jsdom',
      snapshotSerializers: ['@emotion/jest/serializer'],
    },
  });
  

之后生成的快照会自动将哈希类名转换为统一格式，比如把css-wwkw0y-xxx替换为css-[hash]-xxx，彻底解决哈希波动问题。

2. 配置Emotion生成稳定类名 #

通过自定义Emotion缓存，强制生成固定的类名前缀或去掉哈希：

• 创建测试专用的Emotion缓存文件：

  // src/test-utils/emotion-cache.js
  import createCache from '@emotion/cache';
  
  export const testCache = createCache({
    key: 'mui-test',
    // 禁用动态哈希，替换为固定标识
    stylisPlugins: [
      (style) => {
        style.selector = style.selector.replace(/css-[a-zA-Z0-9]+/g, 'css-stable');
        return style;
      },
    ],
  });
  

• 在测试启动文件（如vitest.setup.js）中封装带缓存的渲染方法：

  import { CacheProvider } from '@emotion/react';
  import { render } from '@testing-library/react';
  import { testCache } from './src/test-utils/emotion-cache';
  
  export const renderWithStableClasses = (ui, options) => {
    return render(
      <CacheProvider value={testCache}>{ui}</CacheProvider>,
      options
    );
  };
  

• 测试中使用renderWithStableClasses替代原render方法：

  import { renderWithStableClasses } from '../vitest.setup';
  import MyComponent from './MyComponent';
  
  test('renders correctly', () => {
    const { container } = renderWithStableClasses(<MyComponent />);
    expect(container.firstChild).toMatchSnapshot();
  });
  

这样生成的类名会统一变为css-stable-xxx，快照完全稳定。

3. 快照中手动替换哈希（快速临时方案） #

如果不想修改全局配置，可在单个测试中手动替换哈希部分：

import { render } from '@testing-library/react';
import MyComponent from './MyComponent';

test('renders correctly', () => {
  const { container } = render(<MyComponent />);
  // 正则替换所有css-开头的哈希字符串
  const processedHtml = container.innerHTML.replace(/css-[a-zA-Z0-9]+/g, 'css-fixed-hash');
  expect(processedHtml).toMatchSnapshot();
});

这种方式适合小范围测试，但需要每个测试都做处理，维护成本较高。

内容的提问来源于stack exchange，提问作者Erik Kránicz