Storyshots 迁移指南

我们正在积极整合社区反馈，以改进 Storybook 快照测试的工具和文档。如果您有兴趣参与此过程并帮助我们改进它。请填写此表格以分享您的反馈。

本指南将教您如何将快照测试从 Storyshots 插件迁移到 Storybook 的 test-runner 或可移植 stories。此外，您还可以了解它们之间的差异，并使用 Storybook 提供的可用工具设置、配置和运行快照测试。

从 Storyshots 迁移测试

先决条件

在开始迁移过程之前，请确保您已具备以下条件

已完全配置并运行最新稳定版本（即 7.6 或更高版本）的 Storybook，并具有受支持的框架之一。
熟悉您当前的 Storybook 及其测试设置。

使用 test-runner

Storybook test-runner 将您的所有 stories 转换为可执行的测试。由 Jest 和 Playwright 驱动。它是一个独立的、框架无关的实用程序，与您的 Storybook 并行运行。它使您能够在多浏览器环境中运行多种测试模式，包括使用 play 函数、DOM 快照和可访问性测试的组件测试。

设置

要开始从 Storyshots 插件迁移到 test-runner 的过程，我们建议您从项目中删除 Storyshots 插件和类似的包（例如，storybook/addon-storyshots-puppeteer），包括任何相关的配置文件。然后，按照 test-runner 的设置说明进行安装、配置和运行。

扩展您的测试覆盖率

Storyshots 插件提供了一个高度可定制的测试解决方案，允许用户以各种方式扩展测试覆盖率。但是，test-runner 提供了类似的体验，但具有不同的 API。下面，您将找到使用 test-runner 实现与使用 Storyshots 类似结果的其他示例。

使用 test-runner 启用 DOM 快照测试

要使用 test-runner 启用 DOM 快照测试，您可以扩展 test-runner 的配置文件，并使用可用的钩子，并将它们与 Playwright 的内置 API 结合使用，为项目中的每个 story 生成 DOM 快照。例如

.storybook/test-runner.ts

import type { TestRunnerConfig } from '@storybook/test-runner';
 
const config: TestRunnerConfig = {
  async postVisit(page, context) {
    // the #storybook-root element wraps the story. In Storybook 6.x, the selector is #root
    const elementHandler = await page.$('#storybook-root');
    const innerHTML = await elementHandler.innerHTML();
    expect(innerHTML).toMatchSnapshot();
  },
};
 
export default config;

如果您已在项目中使用 test-runner 设置了 DOM 快照测试，并启用了通过 CLI 标志启用了 index.json 模式，则测试将在项目外部的临时文件夹中生成，快照将与它们一起存储。您需要扩展 test-runner 的配置并提供自定义快照解析器，以允许快照使用不同的位置。有关更多信息，请参阅故障排除部分。

使用 test-runner 运行图像快照测试

默认情况下，test-runner 为您提供了使用最少配置运行多种测试模式（例如，DOM 快照测试、可访问性）的选项。但是，如果您愿意，您可以扩展它以与其他测试一起运行视觉回归测试。例如

.storybook/test-runner.ts

import { TestRunnerConfig, waitForPageReady } from '@storybook/test-runner';
 
import { toMatchImageSnapshot } from 'jest-image-snapshot';
 
const customSnapshotsDir = `${process.cwd()}/__snapshots__`;
 
const config: TestRunnerConfig = {
  setup() {
    expect.extend({ toMatchImageSnapshot });
  },
  async postVisit(page, context) {
    // Waits for the page to be ready before taking a screenshot to ensure consistent results
    await waitForPageReady(page);
 
    // To capture a screenshot for for different browsers, add page.context().browser().browserType().name() to get the browser name to prefix the file name
    const image = await page.screenshot();
    expect(image).toMatchImageSnapshot({
      customSnapshotsDir,
      customSnapshotIdentifier: context.id,
    });
  },
};
export default config;

使用可移植 Stories

Storybook 提供了一个 composeStories 实用程序，可帮助将 story 文件中的 stories 转换为可渲染的元素，这些元素可以在带有 JSDOM 的 Node 测试中重用。它还允许您应用项目中已启用的其他 Storybook 功能（例如，decorators，args），这允许您的组件正确渲染。这就是所谓的可移植 stories。

设置

我们建议您关闭当前的 storyshots 测试以开始迁移过程。为此，请重命名配置文件（例如，storybook.test.ts|js 或类似文件）为 storybook.test.ts|js.old。这将阻止检测到测试，因为您将创建一个具有相同名称的新测试配置文件。通过这样做，您将能够在过渡到可移植 stories 之前保留现有测试，然后再从项目中删除 Storyshots 插件。

从 Storybook 导入项目级注解

如果你需要在你的测试中启用项目级别的注解 (例如，装饰器, args, 样式) ，这些注解包含在你的 ./storybook/preview.js|ts 文件中，请调整你的测试设置文件，按如下方式导入注解

setupTest.ts

import { beforeAll } from 'vitest';
// 👇 If you're using Next.js, import from @storybook/nextjs
//   If you're using Next.js with Vite, import from @storybook/experimental-nextjs-vite
import { setProjectAnnotations } from '@storybook/react';
// 👇 Import the exported annotations, if any, from the addons you're using; otherwise remove this
import * as addonAnnotations from 'my-addon/preview';
import * as previewAnnotations from './.storybook/preview';
 
const annotations = setProjectAnnotations([previewAnnotations, addonAnnotations]);
 
// Run Storybook's beforeAll hook
beforeAll(annotations.beforeAll);

为可移植 stories 配置测试框架

为了帮助你从 Storyshots addon 迁移到 Storybook 的可移植 stories，并使用 composeStories 辅助 API，我们准备了一些示例来帮助你入门。下面列出了两个最流行的测试框架的示例：Jest 和 Vitest。我们建议将代码放置在一个新创建的 storybook.test.ts|js 文件中，并根据你的测试框架相应地调整代码。以下两个示例都将

基于 glob 模式导入所有 story 文件
遍历这些文件，并在每个文件的模块上使用 composeStories，从而生成每个 story 的可渲染组件列表
循环遍历 stories，渲染它们，并进行快照

Vitest

如果你正在使用 Vitest 作为你的测试框架，你可以参考以下示例，开始将你的快照测试迁移到 Storybook 的可移植 stories，并使用 composeStories 辅助 API。你需要按如下方式修改你的 storybook.test.ts|js 文件：

storybook.test.ts

// @vitest-environment jsdom
 
// Replace your-framework with one of the supported Storybook frameworks (react, vue3)
import type { Meta, StoryFn } from '@storybook/your-framework';
 
import { describe, expect, test } from 'vitest';
 
// Replace your-renderer with the renderer you are using (e.g., react, vue3, svelte, etc.)
import { composeStories } from '@storybook/your-renderer';
 
type StoryFile = {
  default: Meta;
  [name: string]: StoryFn | Meta;
};
 
const compose = (entry: StoryFile): ReturnType<typeof composeStories<StoryFile>> => {
  try {
    return composeStories(entry);
  } catch (e) {
    throw new Error(
      `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${e}`,
    );
  }
};
 
function getAllStoryFiles() {
  // Place the glob you want to match your story files
  const storyFiles = Object.entries(
    import.meta.glob<StoryFile>('./stories/**/*.(stories|story).@(js|jsx|mjs|ts|tsx)', {
      eager: true,
    }),
  );
 
  return storyFiles.map(([filePath, storyFile]) => {
    const storyDir = path.dirname(filePath);
    const componentName = path.basename(filePath).replace(/\.(stories|story)\.[^/.]+$/, '');
    return { filePath, storyFile, componentName, storyDir };
  });
}
 
// Recreate similar options to Storyshots. Place your configuration below
const options = {
  suite: 'Storybook Tests',
  storyKindRegex: /^.*?DontTest$/,
  storyNameRegex: /UNSET/,
  snapshotsDirName: '__snapshots__',
  snapshotExtension: '.storyshot',
};
 
describe(options.suite, () => {
  getAllStoryFiles().forEach(({ storyFile, componentName, storyDir }) => {
    const meta = storyFile.default;
    const title = meta.title || componentName;
 
    if (options.storyKindRegex.test(title) || meta.parameters?.storyshots?.disable) {
      // Skip component tests if they are disabled
      return;
    }
 
    describe(title, () => {
      const stories = Object.entries(compose(storyFile))
        .map(([name, story]) => ({ name, story }))
        .filter(({ name, story }) => {
          // Implements a filtering mechanism to avoid running stories that are disabled via parameters or that match a specific regex mirroring the default behavior of Storyshots.
          return !options.storyNameRegex?.test(name) && !story.parameters.storyshots?.disable;
        });
 
      if (stories.length <= 0) {
        throw new Error(
          `No stories found for this module: ${title}. Make sure there is at least one valid story for this module, without a disable parameter, or add parameters.storyshots.disable in the default export of this file.`,
        );
      }
 
      stories.forEach(({ name, story }) => {
        // Instead of not running the test, you can create logic to skip it, flagging it accordingly in the test results.
        const testFn = story.parameters.storyshots?.skip ? test.skip : test;
 
        testFn(name, async () => {
          await story.run();
          // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot.
          await new Promise((resolve) => setTimeout(resolve, 1));
 
          expect(document.body.firstChild).toMatchSnapshot();
        });
      });
    });
  });
});

当你的测试使用 Vitest 执行时，它将生成一个包含项目中所有 stories 的单个快照文件 (例如，storybook.test.ts|js.snap)。但是，如果你想生成单独的快照文件，你可以使用 Vitest 的 toMatchFileSnapshot API。例如：

storybook.test.js|ts

// ...Code omitted for brevity
 
describe(options.suite, () => {
  // 👇 Add storyDir in the arguments list
  getAllStoryFiles().forEach(({ filePath, storyFile, storyDir }) => {
    // ...Previously existing code
    describe(title, () => {
      // ...Previously existing code
      stories.forEach(({ name, story }) => {
        // ...Previously existing code
        testFn(name, async () => {
          await story.run();
          // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot.
          await new Promise((resolve) => setTimeout(resolve, 1));
 
          // 👇 Define the path to save the snapshot to:
          const snapshotPath = path.join(
            storyDir,
            options.snapshotsDirName,
            `${componentName}${options.snapshotExtension}`
          );
          await expect(document.body.firstChild).toMatchFileSnapshot(snapshotPath);
        });
      });
    });
  });
});

Jest

如果你正在使用 Jest 作为你的测试框架，你可以参考以下示例，开始将你的快照测试迁移到 Storybook 的可移植 stories，并使用 composeStories 辅助 API。你需要按如下方式修改你的 storybook.test.ts|js 文件：

storybook.test.ts

import path from 'path';
import * as glob from 'glob';
 
// Replace your-framework with one of the supported Storybook frameworks (react, vue3)
import type { Meta, StoryFn } from '@storybook/your-framework';
 
import { describe, test, expect } from '@jest/globals';
 
// Replace your-renderer with the renderer you are using (e.g., react, vue3, svelte, etc.)
import { composeStories } from '@storybook/your-renderer';
 
type StoryFile = {
  default: Meta;
  [name: string]: StoryFn | Meta;
};
 
const compose = (entry: StoryFile): ReturnType<typeof composeStories<StoryFile>> => {
  try {
    return composeStories(entry);
  } catch (e) {
    throw new Error(
      `There was an issue composing stories for the module: ${JSON.stringify(entry)}, ${e}`,
    );
  }
};
 
function getAllStoryFiles() {
  // Place the glob you want to match your stories files
  const storyFiles = glob.sync(
    path.join(__dirname, 'stories/**/*.{stories,story}.{js,jsx,mjs,ts,tsx}'),
  );
 
  return storyFiles.map((filePath) => {
    const storyFile = require(filePath);
    return { filePath, storyFile };
  });
}
 
// Recreate similar options to Storyshots. Place your configuration below
const options = {
  suite: 'Storybook Tests',
  storyKindRegex: /^.*?DontTest$/,
  storyNameRegex: /UNSET/,
  snapshotsDirName: '__snapshots__',
  snapshotExtension: '.storyshot',
};
 
describe(options.suite, () => {
  getAllStoryFiles().forEach(({ storyFile, componentName }) => {
    const meta = storyFile.default;
    const title = meta.title || componentName;
 
    if (options.storyKindRegex.test(title) || meta.parameters?.storyshots?.disable) {
      // Skip component tests if they are disabled
      return;
    }
 
    describe(title, () => {
      const stories = Object.entries(compose(storyFile))
        .map(([name, story]) => ({ name, story }))
        .filter(({ name, story }) => {
          // Implements a filtering mechanism to avoid running stories that are disabled via parameters or that match a specific regex mirroring the default behavior of Storyshots.
          return !options.storyNameRegex.test(name) && !story.parameters.storyshots?.disable;
        });
 
      if (stories.length <= 0) {
        throw new Error(
          `No stories found for this module: ${title}. Make sure there is at least one valid story for this module, without a disable parameter, or add parameters.storyshots.disable in the default export of this file.`,
        );
      }
 
      stories.forEach(({ name, story }) => {
        // Instead of not running the test, you can create logic to skip it, flagging it accordingly in the test results.
        const testFn = story.parameters.storyshots?.skip ? test.skip : test;
 
        testFn(name, async () => {
          await story.run();
          // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot.
          await new Promise((resolve) => setTimeout(resolve, 1));
          expect(document.body.firstChild).toMatchSnapshot();
        });
      });
    });
  });
});

当你的测试使用 Jest 执行时，它将生成一个包含项目中所有 stories 的单个快照文件 (例如，__snapshots__/storybook.test.ts|js.snap)。但是，如果你想生成单独的快照文件，你可以使用 jest-specific-snapshot 包。例如：

storybook.test.js|ts

// 👇 Augment expect with jest-specific-snapshot
import 'jest-specific-snapshot';
 
// ...Code omitted for brevity
 
describe(options.suite, () => {
  //👇 Add storyDir in the arguments list
  getAllStoryFiles().forEach(({ filePath, storyFile, storyDir }) => {
    // ...Previously existing code
    describe(title, () => {
      // ...Previously existing code
      stories.forEach(({ name, story }) => {
        // ...Previously existing code
        testFn(name, async () => {
          await story.run();
          // Ensures a consistent snapshot by waiting for the component to render by adding a delay of 1 ms before taking the snapshot.
          await new Promise((resolve) => setTimeout(resolve, 1));
 
          //👇 Define the path to save the snapshot to:
          const snapshotPath = path.join(
            storyDir,
            options.snapshotsDirName,
            `${componentName}${options.snapshotExtension}`,
          );
          expect(document.body.firstChild).toMatchSpecificSnapshot(snapshotPath);
        });
      });
    });
  });
});

已知限制

如果你选择在测试中使用可移植 stories，你将拥有一个可以在 JSDOM 环境中运行的单个测试文件，用于渲染和快照所有 stories。但是，随着你的项目增长，你可能会遇到之前使用 Storyshots 时遇到的限制

你没有在真实的浏览器中进行测试。
你必须 mock 许多浏览器实用程序 (例如，canvas, window APIs 等)。
你的调试体验不会那么好，因为你无法在测试中访问浏览器。

或者，你可能需要考虑迁移到 Storybook 快照测试的另一个可用选项：test-runner，这是一个更强大的解决方案，它使用 Playwright 在真实的浏览器环境中运行测试。

故障排除

由于使用 Storybook 和 test-runner 运行快照测试可能会导致一些技术限制，这些限制可能会阻止你成功设置或运行测试，因此我们准备了一组说明来帮助你排除可能遇到的任何问题。

如果你在使用 test-runner 时遇到间歇性测试失败，当你的测试在浏览器中运行时，可能会发生未捕获的错误。如果你之前使用 Storyshots addons，这些错误可能不会被捕获。默认情况下，test-runner 会将这些未捕获的错误视为失败的测试。但是，如果这些错误是预期的，你可以通过在你的 stories 和 test-runner 配置文件中启用自定义 story 标签来忽略它们。有关更多信息，请参阅 test-runner 文档。

test-runner 没有在预期的目录中生成快照文件

如果你已配置 test-runner 运行快照测试，你可能会注意到快照文件的路径和名称与之前由 Storyshots addon 生成的路径和名称不同。这是因为 test-runner 对快照文件使用了不同的命名约定。使用自定义快照解析器，你可以配置 test-runner 使用你之前使用的相同命名约定。

运行以下命令以生成 test-runner 的自定义配置文件，你可以使用该文件来配置 Jest

npm run test-storybook -- --eject

更新文件并启用 snapshotResolver 选项以使用自定义快照解析器

./test-runner-jest.config.js

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;

最后，创建一个 snapshot-resolver.js 文件来实现自定义快照解析器

./snapshot-resolver.js

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',
};

快照文件的格式与 Storyshots addon 生成的格式不同

默认情况下，test-runner 使用 jest-serializer-html 来序列化 HTML 快照。这可能会导致格式与你现有的快照不同，即使你正在使用特定的 CSS-in-JS 库，如 Emotion、Angular 的 ng 属性或其他类似的库，这些库为 CSS 类生成基于哈希的标识符。但是，你可以配置 test-runner 使用自定义快照序列化器来解决此问题，方法是将随机类名覆盖为静态类名，该静态类名在每次测试运行时都相同。

运行以下命令以生成 test-runner 的自定义配置文件，你可以使用该文件来提供其他配置选项。

npm run test-storybook -- --eject

更新文件并启用 snapshotSerializers 选项以使用自定义快照序列化器。例如

./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 it's passed onto the test-runner
    './snapshot-serializer.js',
    ...defaultConfig.snapshotSerializers,
  ],
};
 
export default config;

最后，创建一个 snapshot-serializer.js 文件来实现自定义快照序列化器

./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 id="react-aria970235672-:rl:" for="react-aria970235672-:rk:">Favorite color</label> to <label id="react-mocked_id" for="react-mocked_id">Favorite color</label>
   */
  serialize(val) {
    const withFixedIds = val.replace(DYNAMIC_ID_PATTERN, 'mocked_id');
    return jestSerializerHtml.print(withFixedIds);
  },
  test(val) {
    return jestSerializerHtml.test(val);
  },
};

当 test-runner 执行你的测试时，它将检查生成的 HTML，并在对组件进行快照之前，将任何动态生成的属性替换为正则表达式提供的静态属性。