fusion-framework-mocking

Fusion Framework のモック

使用する場面

実際の Entra ID テナント、サービスレジストリ、バックエンドを使わずに、サインイン済みユーザー、現在のコンテキスト、シード済みの機能フラグ／ブックマーク、または偽の HTTP レスポンスなど、決定論的な Fusion Framework モジュールの状態がテストで必要な場合に使用します。

よくある例：

• 「useAccessToken をモックする／テストユーザーをサインインさせるにはどうすればよいですか？」
• 「このテスト用に現在のコンテキストをシードする」
• 「この HTTP エンドポイントのレスポンスを偽装する」
• 「アプリがネットワークにアクセスしないよう、サービスディスカバリーをモックする」
• 「独自のモジュール用のモックを追加する」
• 「サインアウト／ログイン／ログアウトの動作をテストする」
• 「ミドルウェアが呼び出されたことをアサートする」

暗黙的な例：

• テストで mockFramework、mockAppModules、または @equinor/fusion-framework-module-*/mock のエントリーポイントをインポートする
• 実際の認証情報や起動中のバックエンドなしでアプリを起動する必要がある
• Fusion モジュール用の *.mock.ts／モックコンフィギュレーターの作成またはレビュー

使用しない場面

• コンポーネント／フックのレンダリング、または Vitest／Browser Mode の設定 — fusion-framework-testing を使用します
• ローカルの ffc app dev 用の dev-server.config.ts による API のモック／プロキシ — これは開発時のみの機能で、テスト時のモジュールモックとは関係ありません。fusion-developer-app を参照してください
• 特定の呼び出し（引数、呼び出し回数、リセット）のアサート — これはテストランナーの役割です（vi.spyOn、vi.fn）。このスキルではモジュール状態のシードのみを扱います
• バックエンド／サービスリポジトリのテストダブル（別のリポジトリ、別のスタック）

必要な入力

必須

• 偽装する境界：認証、サービスディスカバリー、コンテキスト、ブックマーク、機能フラグ、HTTP、分析、テレメトリー、アプリマニフェスト、またはカスタムモジュール
• テストのスコープ：親フレームワーク（mockFramework）、アプリ独自のモジュール（mockAppModules）、または独自のモジュールグラフ（モジュール独自の enable*Mock）

条件付き

• 認証が関係する場合は、サインイン済みユーザーの詳細（名前、ユーザー名、特定のトークンクレーム）
• テストを完全にオフラインにする必要があるかどうか（想定されるすべてのリクエストに応答するミドルウェアが必要です）
• テスト対象の API がすでに OpenAPI ドキュメントで記述されているかどうか

手順

ステップ 1 — モックの設計を理解する

モックを書く前に、設計ルールについて references/framework-and-app-mocks.md を読んでください。

• 置き換えるのはクライアント（ネットワーク I/O を行うオブジェクト）のみです。プロバイダー、コンフィギュレーター、スキーマ検証、モジュールの initialize はすべて実際に実行されるため、配線の誤りもテストで検出できます。
• モックは置き換えるモジュールの隣、つまりそのモジュール独自の /mock エントリーポイントに配置します。@equinor/fusion-framework/mock は組み込みのセットを組み合わせるだけで、独自のモックロジックは含みません。
• 個別の呼び出しを対象とする Fusion のモック API はありません。モッククライアントは通常のメソッドを持つ単純なクラスです。vi.spyOn、bun:test の spyOn、または Node の t.mock.method を直接使用してください。

ステップ 2 — 適切なレイヤーを選ぶ

テストのスコープ	使用するもの	インポート
親フレームワーク／ポータルレベルのモジュールをまとめて扱う	mockFramework	@equinor/fusion-framework/mock
アプリ独自のモジュール（React なし）	mockAppModules	@equinor/fusion-framework-app/mock
独自のモジュールグラフ内の単一モジュール	そのモジュールの enable*Mock	@equinor/fusion-framework-module-*/mock
アプリモジュールを利用する React フック／コンポーネント	レンダーヘルパー（ここでは対象外）	fusion-framework-testing を参照

import { mockFramework } from '@equinor/fusion-framework/mock';

const fusion = await mockFramework((configurator) => {
  configurator.msal.setAccount({ name: 'Ada Lovelace' });
  configurator.context.setCurrentContext({ id: 'project-a', type: { id: 'ProjectMaster' }, value: {} });
  configurator.serviceDiscovery.addService({ key: 'catalog' });
});

mockFramework は FrameworkConfigurator が宣言するすべてのモジュール（event、auth、http、serviceDiscovery、context、telemetry）を設定なしで初期化します。デフォルトでサインイン済みの Test User とオフラインのサービス解決が利用できます。

ステップ 3 — テストに必要なモジュールをシードする

モジュールごとの表（認証、サービスディスカバリー、コンテキスト、ブックマーク、機能フラグ、分析、テレメトリー、アプリマニフェスト）と、デフォルト値、ビルダーメソッド、サインアウト／トークンを完全一致させる方法については、references/module-mocks.md を参照してください。

ステップ 4 — HTTP レスポンスを偽装する

references/http-and-openapi-mocks.md を使って、手書きの configurator.http.addMiddleware(...)、複数のルートを扱う createRouterMiddleware、または OpenAPI ドキュメント全体を対象とする（@equinor/fusion-openapi-mock を基盤とした） createOpenApiMockMiddleware のいずれかを選びます。一致するリクエストがない場合は必ず next(uri, init) に渡され、最終的に実際のネットワーク通信が行われます。完全にオフラインでテストするには、想定するすべてのリクエストに応答する必要があります。

ステップ 5 — カスタムモジュールのモックを追加する（必要な場合）

テスト対象のモジュールが組み込みモジュールではない場合は、references/custom-module-mocks.md を使用します。クライアントの接続箇所（setClient）、ビルダーが所有する設定、そして FrameworkMockConfigurator の _pin／_getConfig を介して configurator.<yourModule> アクセサーを公開する方法を扱います。

ステップ 6 — 確認する

• モックする境界はクライアントのみです — configurator／provider／validation は実際のものを使用します
• 決定性：トークンと解決済みサービスは実行間で同一です（シードを指定せずに Date.now() に由来するアサーションを使用しないでください）
• 想定するすべての HTTP リクエストに応答するミドルウェアがあるか、テストで意図的に後続へ処理を渡すようにしています
• 呼び出し単位のアサーションには、独自の Fusion API を作らず、テストランナー独自のスパイ機能を使用します

想定される出力

• 適切な /mock エントリーポイントを通じて Fusion モジュールの状態をシードするテストコード
• 使用するレイヤー（mockFramework／mockAppModules／モジュールの enable*Mock）の選択とその理由
• 選択した HTTP の偽装方法（手書きのミドルウェア、ルーター、OpenAPI）と、オフラインでの保証
• 該当する場合は、カスタムモジュールのモックの配線

安全性と制約

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

• 個々の呼び出しのアサーション用に Fusion 固有のモック API を作ること — それはテストランナーの役割です
• 署名されていないモック JWT（createMockToken／MSAL モックの出力）を、テスト以外で有効なものとして扱うこと
• クライアントだけを偽装すればよい場合に、モジュールの provider または configurator 全体を置き換えること
• フレームワーク自体が起動時に解決するすべてのサービス（例：context）を宣言せずに、setResolveUnknownServices(false) を安全だと想定すること

必ず次のことを行ってください。

• テスト対象の動作を検証できる、最小のモック境界を優先すること
• 作り上げた API ではなく、実際に使用するパッケージ／エクスポートを明記すること（例：@equinor/fusion-framework-module-context/mock の enableContextMock）
• テストで意図的にネットワークへの処理の受け渡しを許可する場合と、完全なオフラインを保つ必要がある場合を明記すること