fusion-framework-testing

Fusion Framework のテスト

使用するタイミング

Fusion Framework の React アプリ向けに、フック、コンポーネント、ルート、またはアプリ全体の Vitest テストを作成または実行するとき、あるいはテストプロジェクト自体をセットアップまたはトラブルシューティングするときに使用します。

よくあるきっかけ：

• 「このコンポーネント／フック／ルートのテストを書いて」
• 「このアプリ用に vitest.config.ts を設定して」
• 「このテストがハングする／ネットワークにアクセスする／アプリの解決に失敗するのはなぜ？」
• 「これはフックのテストとコンポーネントのテストのどちらにすべき？」
• 「テストファイル間でシード済みのフィクスチャを共有して」
• 「このテストスイートを Testing Library／jsdom から移行して」

暗黙のきっかけ：

• テストファイルが @equinor/fusion-framework-vitest-plugin-react-app（またはその /test、 /config サブパス）をインポートしている
• vitest.config.ts で Browser Mode、Playwright、またはアプリファイルの解決を設定する必要がある
• テストで、useAppModule、useFramework などを参照するコンポーネント／フックをレンダリングしている

使用しないタイミング

• モジュール固有の状態（サインイン済みユーザー、現在のコンテキスト、機能フラグ、HTTP レスポンスなど）のシード — fusion-framework-mocking を使用してください。このスキルの対象はテストのレンダリング／実行のみです
• ローカルの ffc app dev 向けの dev-server.config.ts による API のモック／プロキシ設定 — 開発時のみを対象とします。fusion-developer-app を参照してください
• Fusion 以外のテストスイート、またはバックエンド／サービスリポジトリのテスト

必要な入力

必須

• テスト対象：純粋関数、フック、コンポーネント、ルート、またはアプリ全体
• このパッケージ用にプロジェクトの vitest.config.ts がすでに設定されているかどうか

条件付き

• テストで特定のサインイン済みユーザー、シード済みコンテキスト、または偽の HTTP レスポンスが必要かどうか（その場合は、シードの詳細について fusion-framework-mocking に引き継いでください）
• 複数のテストファイルで同じフィクスチャのデフォルト値が必要かどうか

手順

ステップ 1 — テスト対象の振る舞いに必要な最小レイヤーを選ぶ

Fusion のテストユーティリティは外部境界のみを置き換えます。テストランナー、アサーション、ライフサイクルフック、スパイ、タイマー、カバレッジは引き続き Vitest が担当します。

テストの目的	まず使用するもの	インポート
純粋関数またはフレームワークに依存しないフック	標準の Vitest	vitest
アプリモジュールを使用する React フック	renderAppHook	@equinor/fusion-framework-vitest-plugin-react-app
React コンポーネント、ルート、またはアプリ全体	test／render フィクスチャ	@equinor/fusion-framework-vitest-plugin-react-app/test
アプリファイルの自動解決なしで再利用できるアプリフィクスチャ	testApp	@equinor/fusion-framework-vitest-plugin-react-app
React を使用しないアプリモジュールの設定	mockAppModules	fusion-framework-mocking を参照
親フレームワークまたはポータルレベルのモジュール	mockFramework	fusion-framework-mocking を参照
1 つのメソッド呼び出し、タイマー、グローバル、または JS モジュール	Vitest の vi API	vitest

コンポーネントテストでポータルを再現する必要はありません。アプリのライフサイクルテストで、すべての Fusion フックを JavaScript モジュールのモックに置き換える必要もありません。モジュール／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 のレンダリング／フックヘルパー（render、renderHook、renderAppComponent、renderAppHook）は、必ずすべて await してください。最初のレンダリングより前にモジュールの初期化が完了します。

ステップ 4 — フィクスチャを組み合わせて再利用する（複数のテストでシード済みの状態を共有する場合）

test（/test から）を拡張して共有状態をシードするか、新しいエクスポートを作成せずに、1 つのファイル／スイートに test.override(...) を使用します。configureApp／configureFusion／mergeEnvConfig、拡張とオーバーライドの使い分け、ルート／アプリのライフサイクルテストについては、references/fixtures-and-advanced-usage.md を参照してください。

ステップ 5 — 失敗を診断する

推測する前に、references/troubleshooting.md の症状一覧を確認してください。失敗の多くは、レンダーヘルパーの await 忘れ、appTestVitePlugin の登録漏れ、または応答するミドルウェアがない HTTP リクエストが原因です。

ステップ 6 — ブラウザモードまたは別のレンダラーを選ぶ（必要な場合のみ）

ブラウザモード（Playwright を介したヘッドレス Chromium）は、速度ではなく忠実度を優先する場合のデフォルトです。実際のブラウザーの動作に依存しないことを証明できるコンポーネントやフックに限り、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 のレンダリング／フックヘルパーがすべて await されている
• フィクスチャの合成（extend／override）は、ケース間／ファイル間で再利用する正当な理由がある場合にのみ使用されている
• モジュール固有のモックのシード設定は fusion-framework-mocking に委任されている

安全性と制約

次のことは決して行わないでください。

• レンダリング／フックヘルパーを先に await せずに、レンダリング結果が正しいと断言する
• 未テストのポリフィルやコンポーネントの置き換えで 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 と一致させてください
• Fusion 固有のテストヘルパーを作り出すのではなく、実際に使用したエクスポート／API を記載してください