Storybook Test Runner 自定义 Snapshot 目录通过 snapshotResolver 配置 Jest 快照路径【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybookStorybook 的 test-runnerstorybook/test-runner基于 Jest 与 Playwright能把项目中的每个 story 转化为可执行的测试并默认在__snapshots__目录下为每个 story 生成快照文件。当默认的快照命名约定或存放目录无法满足你的工程规范时可以通过 Jest 的snapshotResolver选项自定义快照的生成路径与命名规则。本文将基于 Storybook 官方文档 test-runner.mdx 及其配套代码片段完整讲解从零配置自定义快照解析器的过程、两个常用实现示例以及背后的工作原理。背景test-runner 如何生成快照Storybook test-runner 将项目中的全部 story 转为测试用例官方文档对没有 play function 的 story验证其能否无错误地渲染对有 play function 的 story额外检查 play function 中的断言是否全部通过。这些测试运行在真实浏览器环境中可经由 CLI 命令 或 CI 服务器执行。在开启快照测试snapshot testing后test-runner 会遍历所有 story为每个 story 生成一份快照文件默认存放在__snapshots__目录中见 test-runner.mdx。test-runner 开箱即用地提供了一套内置的快照测试配置覆盖了大多数使用场景。如果你需要更精细的控制官方推荐两条路径见 test-runner.mdx运行test-storybook --eject在项目根目录生成一份可修改的test-runner-jest.config.js或直接在项目根目录手工创建test-runner-jest.config.js。本篇文章聚焦的正是其中“自定义快照目录”这一能力。核心配置在 test-runner-jest.config.js 中启用 snapshotResolver当需要把快照文件从默认的__snapshots__目录调整到自定义目录时首先需要创建/修改项目根目录下的test-runner-jest.config.js并开启snapshotResolver选项。官方配置片段test-runner-config-snapshot-resolver.md如下import { getJestConfig } from storybook/test-runner; const defaultConfig getJestConfig(); const config { // The default Jest configuration comes from storybook/test-runner ...defaultConfig, snapshotResolver: ./snapshot-resolver.js, }; export default config;这段配置有三处关键点getJestConfig()从storybook/test-runner包导出的工厂函数返回 test-runner 内置的默认 Jest 配置。getJestConfig是 test-runner 对外暴露的标准扩展入口所有自定义配置都应基于它展开。...defaultConfig将默认配置展开合并进新配置确保 Jest 的 preset、testEnvironment、transform 等内部关键设置不被覆盖。不要省略这一步——如果丢弃默认配置test-runner 将无法正常收集和转换 story 文件。snapshotResolver指向自定义快照解析器文件的路径这里是项目根目录下的./snapshot-resolver.js。Jest 在决定“测试文件对应哪个快照文件”以及“快照文件对应哪个测试文件”时会调用该文件中定义的解析函数。配置完成后当 test-runner 被再次执行时它会遍历所有 story 并运行快照测试将每个 story 的快照文件生成到你自定义的目录中见 test-runner.mdx。实现自定义 snapshotResolver完整 API 与字段说明snapshotResolver指向的文件需要以 ES Module 形式导出一个对象该对象必须实现 Jest 约定的三个字段。官方示例test-runner-snapshot-resolver-custom-directory.md是一个“把快照集中存放到./src/test/__snapshots__/目录”的实现import path from path; export default { resolveSnapshotPath: (testPath) { const fileName path.basename(testPath); const fileNameWithoutExtension fileName.replace(/\.[^/.]$/, ); // Defines the file extension for the snapshot file const modifiedFileName ${fileNameWithoutExtension}.snap; // Configure Jest to generate snapshot files using the following convention (./src/test/__snapshots__/Button.stories.snap) return path.join(./src/test/__snapshots__, modifiedFileName); }, resolveTestPath: (snapshotFilePath, snapshotExtension) path.basename(snapshotFilePath, snapshotExtension), testPathForConsistencyCheck: example, };三个字段的含义与实现要点resolveSnapshotPath(testPath)测试路径 → 快照路径该函数接收被测测试文件的绝对路径返回对应的快照文件路径。示例中的处理链路为path.basename(testPath)取出测试文件名例如Button.stories.jsfileName.replace(/\.[^/.]$/, )用正则去掉最后一个扩展名得到Button.stories拼接新文件名${fileNameWithoutExtension}.snap即Button.stories.snappath.join(./src/test/__snapshots__, modifiedFileName)将文件放入自定义目录最终得到./src/test/__snapshots__/Button.stories.snap。这里的.snap是自定义快照扩展名Jest 默认使用.snap作为快照文件后缀你可以沿用也可以改为其他后缀见下文“自定义命名约定”示例。resolveTestPath(snapshotFilePath, snapshotExtension)快照路径 → 测试路径反向解析给定快照文件路径还原出对应的测试文件路径。示例中简单地返回path.basename(snapshotFilePath, snapshotExtension)即去掉快照扩展名后的文件基本名。Jest 在--updateSnapshot-u回写快照、或进行一致性校验时需要用到这个反向映射。testPathForConsistencyCheck一致性校验锚点一个用于校验解析器双向映射正确性的占位字符串。Jest 会断言resolveSnapshotPath(testPathForConsistencyCheck)与resolveTestPath(...)构成可逆映射若resolveSnapshotPath(example)返回./src/test/__snapshots__/example.snap则resolveTestPath必须能将其还原为example。该字段随意填写会导致校验失败应始终使用一个能通过双向解析的示例值。变体自定义快照文件的命名约定.storyshot除了改变存放目录snapshotResolver同样可以改变快照文件的命名约定。官方提供的第二个示例test-runner-custom-snapshot-resolver.md将快照后缀改为.storyshot并把快照目录固定在测试文件同级的__snapshots__下import path from path; export default { resolveSnapshotPath: (testPath) { const fileName path.basename(testPath); const fileNameWithoutExtension fileName.replace(/\.[^/.]$/, ); const modifiedFileName ${fileNameWithoutExtension}.storyshot; // Configure Jest to generate snapshot files using the following naming convention (__snapshots__/Button.storyshot) return path.join(path.dirname(testPath), __snapshots__, modifiedFileName); }, resolveTestPath: (snapshotFilePath, snapshotExtension) path.basename(snapshotFilePath, snapshotExtension), testPathForConsistencyCheck: example.storyshot, };与上一示例相比差异点在于modifiedFileName使用.storyshot而非.snap快照文件将命名为Button.storyshot目标目录使用path.dirname(testPath)拼到测试文件所在的目录即“就近存放”而非集中存放一致性校验锚点同步改为example.storyshot与新的扩展名匹配。两个示例说明了同一个核心事实resolveSnapshotPath中如何拼接文件名与目录完全由你决定——只要resolveTestPath能按同样的规则逆向还原并保证testPathForConsistencyCheck通过一致性校验即可。完整落地步骤从安装到自定义快照目录将上述配置串起来完整的操作流程如下第 1 步安装 test-runner官方安装片段# npm npm install storybook/test-runner --save-dev # pnpm pnpm add --save-dev storybook/test-runner # yarn yarn add --dev storybook/test-runner第 2 步在 package.json 中添加脚本test-runner.mdx{ scripts: { test-storybook: test-storybook } }第 3 步启动 Storybooktest-runner 依赖本地运行中的 Storybook 或已发布的 Storybook 才能执行测试。第 4 步创建snapshot-resolver.js按上文示例实现三个字段。第 5 步创建或修改项目根目录的test-runner-jest.config.js基于getJestConfig()展开默认配置并启用snapshotResolver: ./snapshot-resolver.js。第 6 步运行测试yarn test-storybook此时 test-runner 会遍历全部 story将快照生成到你在resolveSnapshotPath中指定的目录。如果希望先查看默认配置再修改也可以先运行test-storybook --eject生成test-runner-jest.config.js基线文件。关联能力自定义快照序列化snapshotSerializers与“自定义快照存放位置”配套的另一个常见需求是“自定义快照内容格式”。默认情况下test-runner 使用jest-serializer-html序列化 HTML 快照见 test-runner.mdx。当项目使用 Emotion 等 CSS-in-JS 库、或 Angular 的ng属性时序列化后的 HTML 中会包含基于哈希生成的类名导致每次运行快照内容漂移。此时可以编写snapshot-serializer.js自定义序列化逻辑并在test-runner-jest.config.js中通过snapshotSerializers选项启用import { getJestConfig } from storybook/test-runner; const defaultConfig getJestConfig(); const config { ...defaultConfig, snapshotSerializers: [./snapshot-serializer.js], }; export default config;执行测试时test-runner 会先检查渲染出的 HTML将动态生成的属性替换为序列化器中正则指定的静态内容再写入快照从而保证快照在不同测试运行之间保持一致。小结与延伸阅读配置入口getJestConfig()提供默认配置snapshotResolver接管快照路径的生成与还原核心实现resolveSnapshotPath正向、resolveTestPath反向、testPathForConsistencyCheck一致性校验三者必须成对出现且可逆典型用途集中存放快照到独立测试目录、改用.storyshot等自定义后缀、按团队规范重排目录结构。快照测试还支持通过postVisit钩子实现 DOM 快照采集相关配置与 CLI 选项如-u/--updateSnapshot、--ci可进一步查阅 test-runner.mdx 的“Run snapshot tests”与“CLI Options”章节以及通用的 快照测试指南。【免费下载链接】storybookStorybook is the industry standard workshop for building, documenting, and testing UI components in isolation项目地址: https://gitcode.com/GitHub_Trending/st/storybook创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考