Storybook 中的 Play 函数：实现自动化组件交互测试-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01100/article/details/148323406

Storybook 中的 Play 函数：实现自动化组件交互测试

storybook Storybook是一个独立运行的UI组件开发环境，支持React、Vue、Angular等多种前端框架。它允许开发者在隔离环境中创建、展示和测试UI组件，有助于组件化开发和设计系统的标准化，提高团队协作效率和代码质量。项目地址: https://gitcode.com/gh_mirrors/st/storybook

什么是 Play 函数

Play 函数是 Storybook 提供的一个强大特性，它允许开发者在故事渲染完成后自动执行一系列交互操作。这些小型代码片段能够模拟用户行为，为组件测试带来革命性的便利。

Play 函数的核心价值

传统的前端组件测试往往需要人工操作来验证交互逻辑，而 Play 函数解决了这一痛点：

自动化测试：无需人工干预即可完成复杂交互流程
可视化调试：通过交互面板清晰展示每个操作步骤
真实场景模拟：能够模拟用户真实操作序列

基础用法示例

以一个注册表单组件为例，我们可以使用 Play 函数自动填写并提交表单：

export const FilledForm = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    await userEvent.type(canvas.getByTestId('email'), 'test@email.com');
    await userEvent.type(canvas.getByTestId('password'), 'a-random-password');
    await userEvent.click(canvas.getByRole('button'));
  },
};

这段代码会在故事渲染后自动执行，模拟用户输入邮箱、密码并点击提交按钮的全过程。

核心 API 详解

canvas 对象

Play 函数接收的上下文参数中包含 canvas 对象，它提供了以下能力：

基于 Testing Library 的查询方法
作用域限定在当前故事渲染的 DOM 中
支持所有常用查询方法如 getByText, getByRole 等

play: async ({ canvasElement }) => {
  const canvas = within(canvasElement);
  const submitButton = canvas.getByRole('button', { name: /submit/i });
  await userEvent.click(submitButton);
}

screen 对象

对于需要查询故事边界之外元素的情况（如模态框、弹出菜单等），可以使用全局的 screen 对象：

import { screen } from 'storybook/test';

play: async () => {
  await userEvent.click(screen.getByRole('button'));
  const dialog = await screen.findByRole('dialog');
  expect(dialog).toBeInTheDocument();
}

高级组合技巧

利用 ES6 模块系统和 Storybook 的组件故事格式(CSF)，我们可以组合多个 Play 函数实现复杂的工作流测试：

const TypeAndSubmit = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    await userEvent.type(canvas.getByTestId('field'), 'test input');
    await userEvent.click(canvas.getByRole('button'));
  },
};

export const SuccessCase = {
  ...TypeAndSubmit,
  play: async (context) => {
    await TypeAndSubmit.play(context);
    const canvas = within(context.canvasElement);
    await waitFor(() => {
      expect(canvas.getByText('Success!')).toBeInTheDocument();
    });
  },
};

这种组合方式不仅减少了代码重复，还能清晰地表达测试意图。