Playwright React 组件测试实战指南：基于 Story Gallery 方案的 StrictMode、Provider、类型化 Props 与 CSS 配置全解

导读

本文围绕 Playwright 组件测试（Component Testing）的 React 落地细节展开：如何在现有 React 应用中以极轻量的 Story Gallery 方案为组件编写隔离测试，无需引入专用测试运行时。你将掌握 React 场景下的 StrictMode 正确用法、全局 Provider（主题/路由/i18n/store）的装饰器组织方式、mount 的类型化 props 传递与 update() 校验、全局样式与 Tailwind 的接入，以及 React Query/Apollo 等数据请求库的测试策略。阅读前请先按 SKILL.md 完成环境搭建，并对照 gallery-spec.md 实现你的 gallery；本文是该技能包中 React 专属的深入说明页。

一、React 场景的整体工作流与文件布局

Playwright 组件测试的核心思想是：用普通 Playwright e2e 测试去测试一个由应用自身 dev server 托管的 "Story Gallery" 小页面，页面通过内置的 mount fixture 驱动渲染，无需额外的测试运行器、打包器集成或 npm 包。

React 相关的完整流程分两步：

1. 按 SKILL.md 的 setup workflow 完成：识别框架与打包器 → 按 gallery-spec.md 实现 gallery → 配置 playwright.config.ts → 编写 story 与 spec → 运行 npx playwright test --project=components。
2. 实现 gallery 时，以 gallery-spec.md 中的 React + Vite 完整可运行示例 作为起点（该示例展示了 flushSync 渲染、复用 root 以支持 update() 等关键细节），再叠加本文的 React 专属注意事项。

React 场景下涉及两类关键文件：

• playwright/gallery/：需要实现的 gallery（一个 index.html + 一个 main.tsx 模块），它向 window 暴露 mount(params) / window.unmount()。要求 React 与 react-dom 版本为 18+，因为渲染走的是 react-dom/client 的 createRoot API——仓库 gallery 示例中正是 import { createRoot, type Root } from 'react-dom/client' 并配合 flushSync（见 gallery-spec.md）。
• Stories：遵循 src/**/*.story.tsx 的 glob 约定（该 glob 同样会匹配 .story.jsx），每个命名的 export 代表一个 story。参考模板见 templates/react/Button.story.tsx。

Story 约定（来自 SKILL.md）：story 是包裹被测组件的一个微型 wrapper，把某个具体场景（硬编码 props、mock 数据、providers、被记录的回调）固化下来；story 文件与被测组件放一起，每个命名 export 即一个 story。story id 的推荐语法为 <src 下路径去掉 .story.* 扩展名>/<ExportName>，例如 src/components/Button.story.tsx 的 Primary export → mount('components/Button/Primary')。

二、StrictMode：贴近生产渲染，同时守住真实信号

React 应用在生产中普遍以 <React.StrictMode> 包裹根组件。为了让测试环境贴近"大多数应用的真实渲染方式"，应在你的 gallery 渲染 story 时也包上 StrictMode。

// playwright/gallery/main.tsx（示意）
import { StrictMode } from 'react';
// ... resolve 逻辑与 root 复用逻辑同 gallery-spec.md 示例
flushSync(() => root!.render(
  <StrictMode>
    <Story {...props} />
  </StrictMode>
));

需要理解 StrictMode 在 development 构建下会刻意地双重调用渲染函数与 effects（mount → unmount → remount 的模拟），这意味着：

• 对依赖 effects 中设置计数器来记录事件的 story 会产生影响——副作用重复执行可能导致计数翻倍或触发两次；
• 而像模板中 CountsClicks 这类通过事件处理器里的 state 更新来记录的 story（见 templates/react/Button.story.tsx），其记录逻辑不经过 effects，因此不受 StrictMode 双重调用影响。

这里有一条重要的工程判断准则：如果某个 story 在 StrictMode 下表现异常，这通常是关于组件本身的真实发现（例如组件在 mount/unmount 生命周期中清理不彻底），而不是测试环境的问题。只有当你的应用本身不使用 StrictMode 时，才应去掉 gallery 中的这个 wrapper。换言之：让 gallery 的渲染模式与应用生产代码保持一致，测试才具有代表性。

三、Global providers：共享 decorator，而非塞进 gallery

React 组件往往依赖 context（主题 theme、状态 store、国际化 i18n、路由 router）。正确做法是创建一个共享的 decorator（装饰器），在各 story 中复用它，从而让每个 story 只声明自己的场景、不重复包裹逻辑。decorator 是一个纯粹的组件 helper，不参与测试断言。

// src/stories/decorators.tsx
import { ThemeProvider } from '../theme';
import { MemoryRouter } from 'react-router-dom';

export function AppScaffold({ children, route = '/' }: { children: React.ReactNode, route?: string }) {
  return (
    <ThemeProvider theme="light">
      <MemoryRouter initialEntries={[route]}>{children}</MemoryRouter>
    </ThemeProvider>
  );
}

之后在每个 story 中显式包裹：

// src/components/ProfilePage.story.tsx
export const LoggedIn = () => (
  <AppScaffold route="/profile/42">
    <ProfilePage user={{ id: 42, name: 'Test User' }} />
  </AppScaffold>
);

两点实践约束：

1. 不要把 decorator 内置进 gallery。 decorator 放在 story 文件层（跟随各 story 使用）让包裹关系在代码中可见，也允许个别 story 选择退出（例如某个无路由依赖的纯展示组件可以直接裸渲染）。
2. 路由用 MemoryRouter 的 initialEntries 模拟初始地址（如 /profile/42），这样 story 无需真实 URL 即可测试路由感知组件；每类 provider 都在 AppScaffold 里集中配置，未来增删 provider 只改一处。

四、Typed props：让 mount 的类型检查覆盖每一条 props

mount 对 story 是泛型的：把 story 类型作为模板参数传入，即可对每测试的 props以及 update() 做类型检查。props 会从组件签名中自动推断，函数组件与 class 组件都支持。

先在 story 中定义一个接收 props 的、带默认值的包装组件：

// src/components/Button.story.tsx
export const WithTitle = ({ title = 'Default' }: { title?: string }) =>
  <Button title={title} />;

然后在 spec 中显式传入类型参数：

// src/components/button.spec.ts
import type { WithTitle } from './Button.story';

const component = await mount<typeof WithTitle>('components/Button/WithTitle', { title: 'Hello' });

技术要点：这里应使用 import type 语法，确保 story 文件（连带其 React/Vue 与 CSS 等 import）永远不会被加载进 Node 测试进程（详见 typing.md）。加上 typeof WithTitle 模板参数后，{ title: 'Hello' } 的字段会被逐一检查，component.update({ title: 'Again' }) 同样受约束。

如果连 story id 本身都想获得类型（自动补全与重命名安全），可以采用第二种方案——生成 gallery 类型：当 story id 是 @playwright/test 导出的空 interface Stories 的键时，mount 会自动按该条目约束 props；通过一个小型 Vite 插件生成 stories.d.ts 并用 module augmentation 填充 Stories，即可获得 mount('acme-ui/components/Button/WithTitle', { title: 'Hello' }) 这种无类型导入的调用形态。该插件本身框架无关、只负责列出 story 文件，并需在 tsconfig 的 files 中显式登记生成文件（详见 typing.md）。

五、CSS：全局样式与 Tailwind 的接入姿势

React 组件测试要还原真实渲染效果，样式接入必须与应用自身的入口保持一致：

• 全局样式表：在 gallery 的入口模块里按应用的写法导入。例如应用入口是 import './src/index.css'，那 gallery 中同样执行 import '../../src/index.css'（位于 playwright/gallery/main.tsx），让被测组件拿到与生产一致的全局样式（字体、reset、主题变量等）。
• Tailwind：如果你的 Tailwind 配置采用基于路径的内容扫描（content scanning），务必确认 *.story.tsx 文件被涵盖在扫描范围内。Tailwind 按文件路径生成工具类，story 文件若未被扫描，其中使用的 utility class 将不会生成，导致测试渲染与生产样式不一致。可将 story glob 加入 tailwind.config.* 的 content 数组。

六、Data fetching：客户端对象要在 story/decorator 内创建

对于持有"客户端（client）"对象的请求类库——典型的如 React Query、Apollo——应当在 story 或 decorator 内部创建客户端实例。原因是每次 mount() 都会产生一次全新导航（mount fixture 会先导航到 baseURL 的 gallery 页面再调用 window.mount），因此：

• 把 client 创建放在 story/decorator 内部，能保证每次导航都从一个全新的 client 状态开始，避免跨用例的缓存、连接或订阅泄漏；
• 与全局 Provider 一节的原则一致：story 完全自包含，"组件需要的一切都在 story 里搭好"（该原则详见 SKILL.md）。

这与仓库 gallery 契约中"window.mount 就是你的 setup/teardown hook"的设计相呼应——在浏览器侧渲染前安装 providers、播种 store、启动内存 mock server 都在 window.mount 内部完成（见 gallery-spec.md）。数据请求既可在 story 层用 client 直连 mock 端点，也可在测试层用常规 page.route() 拦截——注册要在 mount() 之前完成，并配合配置中的 serviceWorkers: 'block' 防止应用自带 SW 以缓存响应遮蔽路由 mock（见 SKILL.md）。

七、可验证的仓库落点

• Gallery 契约与 React + Vite 完整实现示例（含 createRoot + flushSync + root 复用与 window.mount/window.unmount）：gallery-spec.md
• 完整 setup 流程、config 片段与测试模式总纲：SKILL.md
• 类型化的两种可选层次（显式 story 类型 vs 生成的 gallery 类型 + Vite 插件）：typing.md
• 可直接对照的 story 与 spec 模板（CountsClicks、WithTitle 等即出自此处）：templates/react/Button.story.tsx、templates/react/button.spec.ts
• 从 @playwright/experimental-ct-react 迁移的概念对照表（这些包自 Playwright 1.63 起已移除）：migration.md

补充说明：React 与 Vue 两条参考线结构完全平行（Vue 侧见 vue.md，覆盖 .story.ts 渲染函数式与 .story.vue 单文件式两种 story、Pinia/vue-router 插件装饰器、Vue 必须"双份声明"运行时 props 等差异），但其 StrictMode 语义、decorator 封装、样式入口一致性三大原则与本文 React 版完全一致。若你的 story 在应用改用 StrictMode 或接入全局 Provider 后出现行为差异，回到本文第二、三节核对 gallery 与 decorator 的搭建方式，往往即可定位问题。