fusion-framework-testing

Fusion Framework 测试

适用场景

编写或运行 Fusion Framework React 应用的 Vitest 测试时使用——测试对象可以是 hook、组件、路由或完整应用；也适用于设置或排查测试项目本身的问题。

典型触发场景：

• “为这个组件 / hook / 路由编写测试”
• “为这个应用设置 vitest.config.ts”
• “为什么这个测试会挂起 / 访问网络 / 无法解析应用？”
• “这应该是 hook 测试还是组件测试？”
• “在一个测试文件中共享预置的测试数据”
• “将这个测试套件从 Testing Library / jsdom 迁移出去”

隐式触发场景：

• 测试文件导入了 @equinor/fusion-framework-vitest-plugin-react-app（或其 /test、 /config 子路径）
• vitest.config.ts 需要配置 Browser Mode、Playwright 或应用文件解析
• 测试会渲染读取 useAppModule、useFramework 或类似内容的组件 / hook

不适用场景

• 为模块专属状态准备数据（已登录用户、当前上下文、功能标志、HTTP 响应）——使用 fusion-framework-mocking；本技能仅涵盖测试的渲染 / 运行
• 为本地 ffc app dev 设置 dev-server.config.ts API 模拟 / 代理——仅用于开发时，请参阅 fusion-developer-app
• 非 Fusion 测试套件，或后端 / 服务仓库测试

必需输入

必填

• 测试对象：纯函数、hook、组件、路由或完整应用
• 项目是否已为此程序包配置 vitest.config.ts

有条件必填

• 测试是否需要特定的已登录用户、预置上下文或伪造的 HTTP 响应（如需要，请移交给 fusion-framework-mocking 处理数据准备细节）
• 多个测试文件是否需要相同的测试数据默认值

操作说明

步骤 1 — 为待测行为选择最小测试层级

Fusion 测试工具仅替代外部边界；运行器、断言、生命周期钩子、间谍、计时器和覆盖率仍由 Vitest 负责。

测试意图	从以下选项开始	导入
纯函数或与框架无关的 hook	标准 Vitest	vitest
使用应用模块的 React hook	renderAppHook	@equinor/fusion-framework-vitest-plugin-react-app
React 组件、路由或完整应用	test/render fixture	@equinor/fusion-framework-vitest-plugin-react-app/test
无需自动解析应用文件的可复用应用 fixture	testApp	@equinor/fusion-framework-vitest-plugin-react-app
不使用 React 的应用模块配置	mockAppModules	请参阅 fusion-framework-mocking
父级框架或门户级模块	mockFramework	请参阅 fusion-framework-mocking
单次方法调用、计时器、全局对象或 JS 模块	Vitest 的 vi API	vitest

组件测试不应重新创建门户；应用生命周期测试不应通过 JavaScript 模块模拟替换每个 Fusion hook。完整的层级选择表（包括模块 / HTTP 层）请参阅 references/getting-started-and-configuration.md。

步骤 2 — 安装并配置

pnpm add -D vitest playwright @vitest/browser-playwright vitest-browser-react \
  @equinor/fusion-framework-vitest-plugin-react-app
pnpm exec playwright install chromium

// vitest.config.ts
import { defineProject } from '@equinor/fusion-framework-vitest-plugin-react-app/config';

export default defineProject();

defineProject 会注册 appTestVitePlugin、通过 Playwright 启动的无头 Chromium、测试文件匹配规则（src/**/*.{test,spec}.{ts,tsx}）以及延迟导入预热。关于合并覆盖项、替换默认值或解析非标准应用文件，请参阅 references/getting-started-and-configuration.md。

步骤 3 — 编写第一个测试

import { expect } from 'vitest';
import { test } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
import { App } from './App';

test('renders the app', async ({ render }) => {
  const screen = await render(<App />);
  await expect.element(screen.getByRole('heading')).toBeVisible();
});

始终对每个 Fusion 渲染 / hook 辅助函数（render、renderHook、renderAppComponent、renderAppHook）使用 await——模块初始化会在首次渲染前完成。

步骤 4 — 组合 fixture 以便复用（多个测试共享预置状态时）

扩展 test（来自 /test）以准备共享状态，或者使用 test.override(...)，为单个文件 / 套件覆盖设置，而无需创建新的导出。关于 configureApp/configureFusion/mergeEnvConfig、扩展与覆盖的区别，以及路由 / 应用生命周期测试，请参阅 references/fixtures-and-advanced-usage.md。

步骤 5 — 诊断失败

先查阅 references/troubleshooting.md 的症状表，再进行判断——大多数失败都源于未等待渲染辅助函数完成、缺少 appTestVitePlugin 注册，或 HTTP 请求没有对应的响应中间件。

步骤 6 — 选择 Browser Mode 或其他渲染器（仅在确有需要时）

Browser Mode（通过 Playwright 使用无头 Chromium）是默认选项，优先考虑的是保真度，而非速度。只有在能够证明某个组件或 Hook 不依赖真实浏览器行为时，才改用 happy-dom/jsdom——权衡因素和 happy-dom 的接线方式请参阅 references/browser-mode-and-migration.md。

步骤 7 — 迁移现有测试套件（如适用）

如需将现有的 @testing-library/react/jsdom 测试套件迁移到此包，请参阅 references/browser-mode-and-migration.md。

预期输出

• 使用能够测试目标行为的最小层级编写的测试文件
• 正确注册 appTestVitePlugin 的 vitest.config.ts（直接注册或通过 defineProject 注册）
• 每个 Fusion 渲染/Hook 辅助函数都已等待完成
• 仅在跨用例/文件复用确有必要时，才使用 Fixture 组合（extend/override）
• 将模块专属的 Mock 初始化交由 fusion-framework-mocking 处理

安全与约束

切勿：

• 未先等待渲染/Hook 辅助函数完成，就声称渲染结果正确
• 用未经测试的 Polyfill 或组件替换来弥补 DOM 模拟的不足，并宣称测试通过
• 假设未匹配的 HTTP 请求会保持离线——未匹配的请求会访问真实网络
• 虚构此技能参考资料中未记载的 Vitest/Playwright 配置选项

务必：

• 常规应用路径优先使用 @equinor/fusion-framework-vitest-plugin-react-app/test 中的 test/render；仅当测试必须显式提供 env/configure/fusion 时，才改用 renderAppHook/renderAppComponent/testApp
• 测试文件移动时，确保 server.warmup.clientFiles 与 test.include 保持一致
• 引用实际使用的导出项/API，不要虚构 Fusion 专用测试辅助函数