Storybook Test Runner 自定义快照序列化器配置指南通过snapshotSerializers让 HTML 快照稳定可复现【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook导读Storybook 的 Test Runnerstorybook/test-runner可以把你的每一个 Story 变成可执行的 Jest 测试其中基于 DOM 的快照测试依赖默认的jest-serializer-html序列化器。然而一旦组件引入 CSS-in-JS如 Emotion、Angular 的ng属性或会生成哈希类名/动态 ID 的 UI 库如 React Aria快照内容就会随每次构建而变化导致快照频繁失效。本篇文章以 test-runner-config-serializer.md 为核心完整讲解如何在test-runner-jest.config.js中通过getJestConfig()与snapshotSerializers选项注入自定义快照序列化器配合 test-runner-custom-snapshot-serializer.md 中的序列化器实现让快照在不同测试运行之间保持一致、可复现。一、为什么需要自定义快照序列化器1.1 Test Runner 的快照测试机制在 Storybook Test Runner 中启用 DOM 快照测试只需要在 Storybook 目录下新增一个.storybook/test-runner.js或.ts配置文件通过postVisit钩子读取渲染结果并断言// .storybook/test-runner.js module.exports { async postVisit(page, context) { // 在 Storybook 6.x 中包裹 Story 的根节点选择器是 #root const elementHandler await page.$(#storybook-root); const innerHTML await elementHandler.innerHTML(); expect(innerHTML).toMatchSnapshot(); }, };完整示例可参考 test-runner-dom-snapshot-testing.md含 TypeScript 版本。执行yarn test-storybook后Test Runner 会遍历所有 Story为每个 Story 在__snapshots__目录下生成对应的快照文件。1.2 默认序列化器与快照不稳定的根源Test Runner 默认使用jest-serializer-html来序列化 HTML 快照该包作为storybook/test-runner的依赖随包安装无需单独引入。正如 test-runner.mdx 中的 Customize snapshot serialization 小节所说明的这种默认行为在以下场景会引发问题CSS-in-JS 库如 Emotion会为 CSS 类名生成基于哈希的标识符每次编译都可能产生不同值Angular 的ng属性框架注入的ng-*属性内容可能包含动态信息生成动态 ID 的组件库例如 React Aria 等无障碍组件库会生成类似react-aria970235672-:rl:的动态 ID 与for属性。这些动态内容一旦进入快照就会导致同样的组件在不同运行中产生不同的快照文本破坏快照的稳定性。解决思路是在快照被写入之前用一个自定义序列化器对 HTML 做预处理——把动态生成的属性替换为静态、固定的值。二、核心配置test-runner-jest.config.js与snapshotSerializers2.1 配置文件从哪来Test Runner 支持零配置开箱即用但当你需要更细粒度的控制时有两种方式获得可编辑的配置文件运行test-storybook --eject会在项目根目录生成一个test-runner-jest.config.js文件直接在项目根目录手动创建test-runner-jest.config.js。2.2 关联文档中的完整配置test-runner-config-serializer.md 给出了启用自定义快照序列化器的标准配置// ./test-runner-jest.config.js import { getJestConfig } from storybook/test-runner; const defaultConfig getJestConfig(); const config { ...defaultConfig, snapshotSerializers: [ // Sets up the custom serializer to preprocess the HTML before its passed onto the test-runner ./snapshot-serializer.js, ...defaultConfig.snapshotSerializers, ], }; export default config;这段配置值得逐行拆解代码片段作用说明import { getJestConfig } from storybook/test-runner从storybook/test-runner包中导入工厂函数用于获取 Test Runner 内置的默认 Jest 配置包括默认的snapshotSerializers、测试环境、匹配器等const defaultConfig getJestConfig()调用函数得到默认配置对象这是零配置能力的基础...defaultConfig通过展开运算符继承全部默认配置确保自定义文件只做增量覆盖不破坏 Test Runner 的默认行为snapshotSerializers: [./snapshot-serializer.js, ...defaultConfig.snapshotSerializers]覆盖snapshotSerializers数组把自定义序列化器放在数组最前面再拼接回默认序列化器列表2.3 为什么自定义序列化器要放在数组最前面snapshotSerializers是 Jest 标准的配置项用于注册快照序列化器。Jest 在序列化值时会按照数组顺序依次调用每个序列化器的test(val)方法做匹配检测第一个返回true的序列化器将负责处理该值。因此把./snapshot-serializer.js放在...defaultConfig.snapshotSerializers之前可以确保自定义序列化器优先于默认的jest-serializer-html被命中从而在 HTML 被默认序列化器处理之前完成动态内容的替换。这与文档注释 Sets up the custom serializer to preprocess the HTML before its passed onto the test-runner 的意图完全一致。三、配套实现自定义序列化器snapshot-serializer.js3.1 实现代码配置引用的./snapshot-serializer.js需要你自行创建在项目根目录。完整的参考实现来自 test-runner-custom-snapshot-serializer.md// ./snapshot-serializer.js // The jest-serializer-html package is available as a dependency of the test-runner const jestSerializerHtml require(jest-serializer-html); const DYNAMIC_ID_PATTERN /react-aria-\d(\.\d)?/g; module.exports { /* * The test-runner calls the serialize function when the test reaches the expect(SomeHTMLElement).toMatchSnapshot(). * It will replace all dynamic IDs with a static ID so that the snapshot is consistent. * For instance, from label idreact-aria970235672-:rl: forreact-aria970235672-:rk:Favorite color/label to label idreact-mocked_id forreact-mocked_idFavorite color/label */ serialize(val) { const withFixedIds val.replace(DYNAMIC_ID_PATTERN, mocked_id); return jestSerializerHtml.print(withFixedIds); }, test(val) { return jestSerializerHtml.test(val); }, };3.2 序列化器接口契约serialize与testJest 快照序列化器遵循一个约定俗成的双方法接口本实现同样遵守test(val)判断当前值是否应由本序列化器处理。这里直接复用jestSerializerHtml.test(val)的判定逻辑——即仅当传入值是需要按 HTML 序列化的字符串时返回true从而与默认序列化器的能力边界保持一致serialize(val)当test返回true时被调用执行实际的序列化。这里的处理分两步先用正则/react-aria-\d(\.\d)?/g匹配并替换所有react-aria前缀的动态 ID含可选的小数部分统一替换为静态占位符mocked_id再把替换后的字符串交给jestSerializerHtml.print(withFixedIds)复用默认序列化器的格式化输出能力。从代码注释可以看到预期效果形如label idreact-aria970235672-:rl: forreact-aria970235672-:rk:Favorite color/label的 HTML会被规整为label idreact-mocked_id forreact-mocked_idFavorite color/label——属性值稳定了快照也就稳定了。3.3 如何适配你自己的组件库正则DYNAMIC_ID_PATTERN是针对 React Aria 动态 ID 编写的示例。实际项目中你应该根据自己组件库生成动态内容的格式来调整匹配模式例如匹配 Emotion 等 CSS-in-JS 生成的哈希类名/css-\w/g匹配 Angular 注入的ng属性把ng-reflect-*、ng-version等属性从 HTML 中剔除匹配其他库的动态 ID把对应的前缀与编号结构写进正则即可。原则是只替换真正动态的部分保留静态内容避免过度规整导致快照失去回归检测的意义。四、完整配置流程与验证将以上两部分组合起来完整的启用步骤如下确保已安装并配置 Test Runner安装storybook/test-runner并在package.json的scripts中添加test-storybook: test-storybook参考 test-runner-install.md创建自定义序列化器在项目根目录新建snapshot-serializer.js内容见本文第三节创建/修改 Jest 配置文件在项目根目录新建或通过test-storybook --eject生成后修改test-runner-jest.config.js内容见本文第二节启动 Storybook先在一个终端运行yarn storybook或你的启动脚本因为 Test Runner 需要连接一个正在运行的 Storybook 实例本地或已发布版本运行测试新开终端执行yarn test-storybook。首次运行会生成__snapshots__目录下的快照文件之后每次运行都会与既有快照比对。可以验证的一点打开生成的快照文件如果组件包含react-aria动态 ID其中存储的应当是统一的mocked_id而非每次变化的随机 ID。若快照内容仍包含动态值应检查test()方法是否正确返回true、正则是否覆盖了实际的 ID 格式。五、深入理解与默认配置的关系及同类配置5.1getJestConfig()是零配置的基石Test Runner 的零配置体验依赖getJestConfig()工厂函数——它集中封装了测试环境、快照目录约定、序列化器等默认设置。在自定义配置中始终先const defaultConfig getJestConfig()再基于它做展开覆盖是官方推荐的增量扩展方式可以避免手写全部配置带来的维护成本和与 Test Runner 内部约定脱节的风险。5.2 与snapshotResolver的区分在 test-runner.mdx 的 Override the default snapshot directory 小节中还存在一个容易混淆的配置项snapshotResolver。两者的职责边界清晰配置项解决的问题配置示例snapshotResolver控制快照文件存到哪里自定义快照目录/命名snapshotResolver: ./snapshot-resolver.js完整示例见 test-runner-config-snapshot-resolver.mdsnapshotSerializers控制快照内容如何生成序列化前预处理 HTMLsnapshotSerializers: [./snapshot-serializer.js, ...defaultConfig.snapshotSerializers]即本文核心配置如果你的组件存在动态 ID 问题需要的是snapshotSerializers如果只是想把快照文件从默认的__snapshots__目录挪到别处需要的是snapshotResolver。两者也可以在同一份test-runner-jest.config.js中同时启用。5.3 适用前提与注意事项本配置方案面向 Webpack 构建的 Storybook Test Runner该文档位于 test-runner.mdx 中标题即标注了 Test runner (Webpack)若你使用 Vite 驱动的 Storybook 框架官方推荐改用功能更现代的 Vitest addon以docs/writing-tests/integrations/目录下的 vitest-addon 文档为准自定义序列化器会按数组顺序参与所有快照的序列化因此test(val)的判定务必精确避免误伤非 HTML 类型的快照值序列化器文件路径是相对项目根目录解析的如./snapshot-serializer.js路径写错会导致 Jest 加载失败修改序列化器逻辑后如需重新生成基线快照可配合test-storybook -u--updateSnapshot更新既有快照。六、小结围绕 test-runner-config-serializer.md 这一核心配置片段本文完整还原了 Storybook Test Runner 自定义快照序列化器的整套方案先用getJestConfig()获取默认配置再通过snapshotSerializers数组将自定义序列化器置于默认序列化器之前最后在序列化器中用正则规整动态 ID 并复用jest-serializer-html的输出能力。这套预处理 委托默认序列化器的模式是让含动态属性CSS-in-JS 哈希、ng属性、无障碍组件动态 ID的组件快照保持稳定、可复现、适合纳入 CI 回归检测的通用解法。配套的序列化器实现与快照目录自定义示例可分别继续阅读 test-runner-custom-snapshot-serializer.md 与 test-runner-config-snapshot-resolver.md 获取。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考