模拟模块

组件也可能依赖于导入到组件文件中的模块。这些模块可能来自外部包或项目内部。在 Storybook 中渲染这些组件或对其进行测试时，您可能希望模拟这些模块以控制其行为。

如果您更喜欢通过示例学习，我们创建了一个全面的演示项目，使用了此处描述的模拟策略。

在 Storybook 中模拟模块有两种主要方法。这两种方法都涉及到创建一个模拟文件来替换原始模块。两种方法之间的区别在于如何将模拟文件导入到您的组件中。

对于这两种方法，都不支持被模拟模块的相对导入。

模拟文件

要模拟一个模块，请创建一个与其要模拟的模块同名且位于同一目录中的文件。例如，要模拟一个名为 session 的模块，请在其旁边创建一个名为 session.mock.js|ts 的文件，并具有以下几个特点

它必须使用相对导入来导入原始模块。
- 使用子路径或别名导入将导致它导入自身。
它应该重新导出原始模块的所有导出。
它应该使用 fn 实用程序来模拟原始模块中任何必要的功能。
它应该使用 mockName 方法来确保在缩小时保留名称
它不应引入可能影响其他测试或组件的副作用。模拟文件应是隔离的，并且仅影响它们正在模拟的模块。

这是一个名为 session 的模块的模拟文件示例

lib/session.mock.ts

import { fn } from '@storybook/test';
import * as actual from './session';
 
export * from './session';
export const getUserFromSession = fn(actual.getUserFromSession).mockName('getUserFromSession');

当您使用 fn 实用程序来模拟模块时，您将创建完整的 Vitest 模拟函数。有关如何在您的 stories 中使用模拟模块的示例，请参阅下文。

外部模块的模拟文件

您不能直接模拟像 uuid 或 node:fs 这样的外部模块。相反，您必须将其包装在您自己的模块中，您可以像模拟任何其他内部模块一样模拟它。例如，对于 uuid，您可以执行以下操作

// lib/uuid.ts
import { v4 } from 'uuid';
 
export const uuidv4 = v4;

并为包装器创建一个模拟

// lib/uuid.mock.ts
import { fn } from '@storybook/test';
 
import * as actual from './uuid';
 
export const uuidv4 = fn(actual.uuidv4).mockName('uuidv4');

子路径导入

模拟模块的推荐方法是使用子路径导入，这是 Node 包的一个特性，Vite 和 Webpack 都支持。

要配置子路径导入，您需要在项目的 package.json 文件中定义 imports 属性。此属性将子路径映射到实际文件路径。下面的示例为四个内部模块配置了子路径导入

package.json

{
  "imports": {
    "#api": {
      // storybook condition applies to Storybook
      "storybook": "./api.mock.ts",
      "default": "./api.ts",
    },
    "#app/actions": {
      "storybook": "./app/actions.mock.ts",
      "default": "./app/actions.ts",
    },
    "#lib/session": {
      "storybook": "./lib/session.mock.ts",
      "default": "./lib/session.ts",
    },
    "#lib/db": {
      // test condition applies to test environments *and* Storybook
      "test": "./lib/db.mock.ts",
      "default": "./lib/db.ts",
    },
    "#*": ["./*", "./*.ts", "./*.tsx"],
  },
}

此配置有三个值得注意的方面

首先，每个子路径都必须以 # 开头，以将其与常规模块路径区分开来。#* 条目是一个捕获所有条目，它将所有子路径映射到根目录。

其次，键的顺序很重要。default 键应放在最后。

第三，请注意每个模块条目中的 storybook、test 和 default 键。storybook 值用于在 Storybook 中加载时导入模拟文件，而 default 值用于在您的项目中加载时导入原始模块。test 条件也在 Storybook 中使用，这允许您在 Storybook 和其他测试中使用相同的配置。

完成包配置后，您可以更新您的组件文件以使用子路径导入

// AuthButton.ts
// ➖ Remove this line
// import { getUserFromSession } from '../../lib/session';
// ➕ Add this line
import { getUserFromSession } from '#lib/session';
 
// ... rest of the file

只有当您的 TypeScript 配置中的 moduleResolution 属性设置为 'Bundler'、'NodeNext' 或 'Node16' 时，子路径导入才能被正确解析和键入。

如果您当前正在使用 'node'，则这是为使用低于 v10 版本的 Node.js 的项目准备的。使用现代代码编写的项目可能不需要使用 'node'。

Storybook 推荐 TSConfig Cheat Sheet，以获得有关设置 TypeScript 配置的指导。

构建工具别名

如果您的项目无法使用子路径导入，您可以配置您的 Storybook 构建工具，将模块别名指向模拟文件。这将指示构建工具在捆绑您的 Storybook stories 时，将模块替换为模拟文件。

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  viteFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve?.alias,
        // 👇 External module
        lodash: require.resolve('./lodash.mock'),
        // 👇 Internal modules
        '@/api': path.resolve(__dirname, './api.mock.ts'),
        '@/app/actions': path.resolve(__dirname, './app/actions.mock.ts'),
        '@/lib/session': path.resolve(__dirname, './lib/session.mock.ts'),
        '@/lib/db': path.resolve(__dirname, './lib/db.mock.ts'),
      };
    }
 
    return config;
  },
};
 
export default config;

在 stories 中使用模拟模块

当您使用 fn 实用程序来模拟模块时，您将创建完整的 Vitest 模拟函数，它们具有许多有用的方法。例如，您可以使用 mockReturnValue 方法为模拟函数设置返回值，或使用 mockImplementation 定义自定义实现。

在这里，我们在 story 上定义 beforeEach（这将在 story 渲染之前运行），以便为 Page 组件使用的 getUserFromSession 函数设置模拟返回值

Page.stories.ts

// Replace your-renderer with the name of your renderer (e.g. react, vue3)
import type { Meta, StoryObj } from '@storybook/your-renderer';
 
// 👇 Must include the `.mock` portion of filename to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
 
import { Page } from './Page';
 
const meta: Meta<typeof Page> = {
  component: Page,
};
export default meta;
 
type Story = StoryObj<typeof Page>;
 
export const Default: Story = {
  async beforeEach() {
    // 👇 Set the return value for the getUserFromSession function
    getUserFromSession.mockReturnValue({ id: '1', name: 'Alice' });
  },
};

如果您正在在 TypeScript 中编写您的 stories，您必须使用完整的模拟文件名导入您的模拟模块，以便在您的 stories 中正确键入函数。您不需要在您的组件文件中执行此操作。这就是子路径导入或构建工具别名的目的。

监视模拟模块

fn 实用程序还会监视原始模块的函数，您可以使用它来断言它们在测试中的行为。例如，您可以使用组件测试来验证是否使用特定参数调用了某个函数。

例如，这个 story 检查当用户单击保存按钮时是否调用了 saveNote 函数

NoteUI.stories.ts

// Replace your-renderer with the name of your renderer (e.g. react, vue3)
import type { Meta, StoryObj } from '@storybook/your-renderer';
import { expect, userEvent, within } from '@storybook/test';
 
// 👇 Must include the `.mock` portion of filename to have mocks typed correctly
import { saveNote } from '#app/actions.mock';
import { createNotes } from '#mocks/notes';
import NoteUI from './note-ui';
 
const meta: Meta<typeof NoteUI> = {
  title: 'Mocked/NoteUI',
  component: NoteUI,
};
export default meta;
 
type Story = StoryObj<typeof NoteUI>;
 
const notes = createNotes();
 
export const SaveFlow: Story = {
  name: 'Save Flow ▶',
  args: {
    isEditing: true,
    note: notes[0],
  },
  play: async ({ canvasElement, step }) => {
    const canvas = within(canvasElement);
 
    const saveButton = canvas.getByRole('menuitem', { name: /done/i });
    await userEvent.click(saveButton);
    // 👇 This is the mock function, so you can assert its behavior
    await expect(saveNote).toHaveBeenCalled();
  },
};

设置和清理

在 story 渲染之前，您可以使用异步 beforeEach 函数来执行您需要的任何设置（例如，配置模拟行为）。此函数可以在 story、组件（将为文件中的所有 stories 运行）或项目（在 .storybook/preview.js|ts 中定义，这将为项目中的所有 stories 运行）级别定义。

您还可以从 beforeEach 返回一个清理函数，该函数将在您的 story 卸载后调用。这对于取消订阅观察者等任务很有用。

没有必要使用清理函数恢复 fn() 模拟，因为 Storybook 会在渲染 story 之前自动执行此操作。有关更多信息，请参阅 parameters.test.restoreMocks API。

这是一个使用 mockdate 包来模拟 Date 并在 story 卸载时重置它的示例。

Page.stories.ts

// Replace your-renderer with the name of your renderer (e.g. react, vue3)
import type { Meta, StoryObj } from '@storybook/your-renderer';
import MockDate from 'mockdate';
 
// 👇 Must include the `.mock` portion of filename to have mocks typed correctly
import { getUserFromSession } from '#api/session.mock';
import { Page } from './Page';
 
const meta: Meta<typeof Page> = {
  component: Page,
  // 👇 Set the value of Date for every story in the file
  async beforeEach() {
    MockDate.set('2024-02-14');
 
    // 👇 Reset the Date after each story
    return () => {
      MockDate.reset();
    };
  },
};
export default meta;
 
type Story = StoryObj<typeof Page>;
 
export const Default: Story = {
  async play({ canvasElement }) {
    // ... This will run with the mocked Date
  },
};