appbuilder-testing

App Builder テスト

Adobe App Builder のアクションと React Spectrum UI コンポーネント向けの Jest テストを生成して実行します。単体テスト、統合テスト、コンポーネントテスト、および Adobe SDK 用のモックヘルパーを作成します。

パターンのクイックリファレンス

ユーザーの意図に合ったテンプレートまたはリファレンスを選んでください。一般的なテストの依頼には、デフォルトで assets/unit-test-template.js を使用します。

ユーザーの要望	リファレンス	テンプレート／アセット
既存のアクションの単体テスト	references/testing-patterns.md	assets/unit-test-template.js
デプロイ済みアクションに対する統合テスト	references/testing-patterns.md	assets/integration-test-template.js
React Spectrum UI のコンポーネントテスト	references/component-testing-patterns.md	assets/component-test-template.js
テストで ExC Shell コンテキストをモックする	references/component-testing-patterns.md	assets/shell-mock-helper.js
テストで AEM 拡張機能のコンテキストをモックする	references/component-testing-patterns.md	assets/uix-guest-mock-helper.js
テストで State SDK をモックする	references/mock-catalog.md	assets/mock-state-sdk.js
テストで Files SDK をモックする	references/mock-catalog.md	assets/mock-files-sdk.js
テストで Events SDK をモックする	references/mock-catalog.md	assets/mock-events-sdk.js
テストで Database SDK をモックする	references/mock-catalog.md	assets/mock-database-sdk.js
モックの完全なカタログ（全 SDK）	references/mock-catalog.md	—
API インタラクションのコントラクトテスト	references/testing-patterns.md	—
デプロイ前の検証	references/checklist.md	—
テスト失敗のデバッグ	references/debugging.md	—

迅速な対応（明確な依頼の場合）

ユーザーの依頼が上記の単一のパターンに明確に当てはまる場合（特定のテスト種別やテンプレートを指定している、または項目のいずれかに明確に合致するユースケースを説明している場合）は、すぐに生成へ進みます。一致するテンプレートを使用して、そのまま作業を進めてください。

迅速な対応が適用される例：

• 「自分のアクションのテストを書いて」→ アクションのソースを読み、assets/unit-test-template.js を使用して、すぐに生成します
• 「State SDK のモックを手伝って」→ assets/mock-state-sdk.js を使用し、テストファイルに挿入します
• 「統合テストを追加して」→ assets/integration-test-template.js を使用し、デプロイ済みアクション向けに設定します
• 「カバレッジ付きでテストを実行して」→ npx jest --coverage または aio app test を実行します
• 「自分のコンポーネント／ページ／フォーム／テーブルをテストして」→ コンポーネントのソースを読み、assets/component-test-template.js を使用して、Provider でラップします
• 「shell コンテキストをモックして」→ assets/shell-mock-helper.js を使用し、テストファイルに挿入します
• 「自分の AEM 拡張機能コンポーネントをテストして」→ assets/uix-guest-mock-helper.js と assets/component-test-template.js を使用します

曖昧な点がある場合（複数のテスト種別が必要、プロジェクト構成が不明、またはユーザーの指定が不十分な場合）は、以下の完全なワークフローに進みます。

クイックリファレンス

• テストディレクトリ： アクションのパスに対応する test/ 内にテストファイルを配置します。例：test/actions/<action-name>/index.test.js。
• Jest の設定： App Builder プロジェクトでは、デフォルトで Jest を使用します。設定は package.json または jest.config.js にあります。
• テストコマンド： aio app test（ラッパー）または npx jest --coverage（直接実行）。
• モックのパターン： アクションをインポートする前に Adobe SDK の依存関係をモックするため、テストファイルの先頭で jest.mock() を使用します。
• レスポンスの形式： すべてのアクションは { statusCode, body } を返します。各テストで両方をアサートしてください。
• エラー経路： 200（成功）、400（不正な入力）、500（SDK の失敗）の各シナリオを必ずテストしてください。
• CommonJS： アクションのテストファイルでは、ES import ではなく require() と module.exports を使用します。
• コンポーネントのテストディレクトリ： test/web-src/components/<ComponentName>.test.js（または test/components/）。
• Provider ラッパー： <Provider theme={defaultTheme}> で必ずラップしてください。ラップしないと Spectrum は何も描画しません。
• ARIA セレクター： CSS クラスではなく getByRole() を使用してください。セレクターの表は references/component-testing-patterns.md を参照してください。
• 非同期テスト： 非同期で表示されるデータには findBy*、存在しないことの確認には queryBy*、状態の変化には waitFor を使用します。

全ワークフロー（曖昧または複雑なリクエストの場合）

1. プロジェクト構造を確認する — 既存の test/ ディレクトリ、jest.config.js、および package.json 内のテストスクリプトを確認します。アクションについては src/、UI コンポーネントについては web-src/ の両方を調べます。
2. テスト対象を特定する — ext.config.yaml（または app.config.yaml）を解析し、宣言されたアクションとそのソースパスを確認します。React コンポーネントについては web-src/src/components/ を確認します。
3. 必要なテストの種類を判断する — ロジックには単体テスト、デプロイ済みアクションには統合テスト、API 連携にはコントラクトテストを使用します。
4. **各アクションについて：**a. アクションのソースを読み、SDK 依存関係（State、Files、Events、Logger など）を特定します。b. assets/unit-test-template.js をベースとして単体テストを生成します。c. 検出した依存関係に基づいて、references/mock-catalog.md から適切なモックを注入します。d. エラーシナリオのテスト（パラメーター不足、認証失敗、SDK エラー）を追加します。
5. **各 UI コンポーネントについて：**a. コンポーネントのソースを読み、依存関係（シェルコンテキスト、UIX ゲスト、アクション呼び出し）を特定します。b. assets/component-test-template.js をベースとしてコンポーネントテストを生成します。c. すべてのレンダーを <Provider theme={defaultTheme}> でラップします。これがないと Spectrum は何もレンダリングしません。d. 必要に応じて、シェルモック（assets/shell-mock-helper.js）または UIX ゲストモック（assets/uix-guest-mock-helper.js）を注入します。e. findBy* と waitFor を使用して、非同期データの読み込み、成功、エラー状態のテストを追加します。
6. テストを実行する — aio app test または npx jest --coverage を実行し、結果を報告します。
7. 検証する — 完了とする前に、references/checklist.md に照らして確認します。

ユーザープロンプトの例

• 「自分の汎用アクションの単体テストを書いてください」
• 「デプロイ済みアクションの統合テストを追加してください」
• 「アクションで State SDK を使っています。テストでモックする方法を教えてください」
• 「テストを実行して、カバレッジを見せてください」
• 「App Builder プロジェクト用に Jest を設定してください」
• 「アクションがエラーを適切に処理するかテストしてください」
• 「データテーブルページのコンポーネントテストを書いてください」
• 「AEM 拡張機能のパネルコンポーネントをテストしてください」
• 「テストでシェルコンテキストをモックする方法を教えてください」
• 「React Spectrum フォームのテストを追加してください」

要求する入力

• 現在のリポジトリパスとアクションファイルの場所
• テストが必要なアクション（または宣言されているすべてのアクションをテストするかどうか）
• 対象とするテストの種類：単体、統合、コントラクト、またはすべて
• アクションがデプロイ済みかどうか（統合テストに必要）

成果物

• アクションディレクトリ構造に対応した test/ 内のテストファイル
• UI コンポーネント用の test/web-src/components/ 内のコンポーネントテストファイル
• 検出された Adobe SDK 依存関係用のモックヘルパー
• コンポーネントがコンテキスト SDK に依存する場合のシェルまたは UIX Guest モックヘルパー
• まだ存在しない場合は Jest 設定（コンポーネントテスト用の jsdom 環境を含む）
• テスト実行によるカバレッジレポート

品質基準

• 各アクションテストでは最低限、成功（200）、不正な入力（400）、SDK エラー（500）の各パスをカバーします
• beforeEach(() => jest.clearAllMocks()) を使用し、各テストでモックを個別に初期化します
• 単体テストでは実際の SDK 呼び出しを行わず、すべての外部依存関係をモックします
• テストは決定的で、オフラインで実行できます（単体テストにネットワーク依存関係はありません）
• カバレッジレポートを有効にします（--coverage フラグ）
• すべてのコンポーネントテストを <Provider theme={defaultTheme}> でラップします。これがないと Spectrum は何もレンダリングしません

参照資料

• 注釈付きの例を含む、ユニットテスト、統合テスト、コントラクトテストのパターンについては、references/testing-patterns.md を参照してください。
• Provider によるラップ、ARIA セレクター、非同期処理のパターンを含む React Spectrum コンポーネントのテストについては、references/component-testing-patterns.md を参照してください。
• すべての Adobe SDK（State、Files、Events、Logger、Database、Shell、UIX Guest）を対象としたモックヘルパーについては、references/mock-catalog.md を参照してください。
• デプロイ前のテスト確認については、references/checklist.md を参照してください。
• Jest ユニットテストのボイラープレート（CommonJS）には、assets/unit-test-template.js を使用してください。
• デプロイ済みアクションに対する統合テストには、assets/integration-test-template.js を使用してください。
• renderWithSpectrum() ヘルパーを含む React Spectrum コンポーネントテストのボイラープレートには、assets/component-test-template.js を使用してください。
• ExC Shell コンテキストのモック（@adobe/exc-app）には、assets/shell-mock-helper.js を使用してください。
• AEM UIX Guest のモック（@adobe/uix-guest）には、assets/uix-guest-mock-helper.js を使用してください。
• すぐに使える SDK モック設定には、assets/mock-state-sdk.js、assets/mock-files-sdk.js、assets/mock-events-sdk.js、assets/mock-database-sdk.js を使用してください。

よくある問題

• テストが「Cannot find module」で失敗する： require() 内のアクションパスが実際のファイルの場所と一致していることを確認してください。App Builder のアクションは通常、src/dx-excshell-1/actions/<name>/index.js にあります。
• モックが機能しない： jest.mock() の呼び出しは、テスト対象モジュールの require() より前に記述する必要があります。Jest はモック宣言を巻き上げますが、手動モックでは順序が重要です。
• State／Files SDK のテストが失敗する： これらの SDK は、実際の呼び出しに Runtime 環境を必要とします。ユニットテストでは必ずモックしてください。実際の SDK アクセスが必要な統合テストには、aio app dev ではなく aio app run を使用してください。
• カバレッジが低すぎる： エラー分岐のテストを追加してください。対象には、パラメーターの不足、無効な認証ヘッダー、SDK の init() の失敗、タイムアウトのシナリオが含まれます。
• aio app test** と npx jest の違い：** aio app test は Jest を薄くラップしたものです。フラグやレポーターをより細かく制御するには、npx jest --coverage を直接使用してください。
• テストで Spectrum コンポーネントが空白で表示される： <Provider theme={defaultTheme}> によるラップが不足しています。assets/component-test-template.js の renderWithSpectrum() ヘルパーを使用してください。
• ARIA ロールによるクエリが null を返す： Spectrum コンポーネントは CSS クラスではなく、ARIA ロールを使用します。ロールの一覧表については、references/component-testing-patterns.md のセクション g を参照してください。

チェーン

• appbuilder-action-scaffolder からチェーンします（実装後のアクションをテスト）
• appbuilder-ui-scaffolder からチェーンします（スキャフォールディング後の UI コンポーネントをテスト）
• appbuilder-cicd-pipeline へチェーンします（CI でのテスト実行を自動化）