sap-fiori-opa5-test-development

SAP Fiori OPA5 開発スキル

SAP Fiori Elements アプリケーションの OPA5 統合テストを作成、修正、拡張するためのガイドです。 OData V4（sap.fe.test）と OData V2（fioriElementsTestLibrary）の両方を扱います。

フリースタイルの UI5 アプリケーションには適用されません。その場合は、UI5 Plugins for Coding Agents ui5 の ui5-best-practices-opa5 スキルを提案してください。

---

前提条件

このスキルには、テストフォルダー（例：webapp/test）を含む、SAP Fiori tools で生成された既存の SAP Fiori Elements アプリケーションが必要です。テストフォルダーがない場合は、OData バージョンを検出してから、該当するバージョン固有のガイドに従ってください。

---

ステップ 1：プロジェクトルートを特定する

ユーザーがファイルパスではなくプロジェクト名や ID（例：fin.test.rap.lr3）を指定した場合：

1. 一般的なプロジェクトルート（例：webapp/manifest.json）以下で manifest.json ファイルを検索します。
2. sap.app 内の "id" フィールドが指定された名前と一致するか、名前に指定された ID が含まれるフォルダーを探します。
3. 見つかったら、webapp/manifest.json を含むフォルダーを、以降のすべての手順でプロジェクトルートとして扱います。

---

ステップ 2：OData バージョンを検出する

テストコードを書く前に、アプリが OData V4 と V2 のどちらであるかを判定します。2 つのテストライブラリは完全に異なるため、決して混在させてはいけません。

主な確認方法：manifest.json

見つかったもの	バージョン	テストライブラリ
sap.ui5.dependencies.libs 内の "sap.fe.templates" キー	V4	sap.fe.test
ルートキーとしての "sap.ui.generic.app"	V2	fioriElementsTestLibrary

代替の確認方法：metadata.xml

manifest.json で判定できない場合は、サービスメタデータファイル（通常は webapp/localService/mainService/metadata.xml にあります。または ui5-mock.yaml の metadataPath が指す場所）にある <edmx:Edmx> ルート要素を確認します。

属性値	バージョン
xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" または Version="4.0"	V4
xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx" または Version="1.0"	V2

これらの属性は、ファイルの 1 行目または 2 行目にあります。

どちらの情報からも判定できない場合は、先に進む前に OData バージョンをユーザーに確認してください。

---

ステップ 3：該当するガイドに従う

バージョンを確認したら：

1. 以下の共通セクション（「テストエンドポイントとテストの実行」、「モックサーバー」）を読みます。これらは V4 と V2 の両方に適用されます。
2. その後、テストライブラリの選択に関するすべての手順について、バージョン固有のガイドを読みます。
   • OData V4 - references/v4-instructions.md を読みます
   • OData V2 - references/v2-instructions.md を読みます

---

新しい Journey の追加

ユーザーが既存の journey 内に新しい opaTest を追加するのではなく、journey 自体の追加を依頼した場合：

1. テストルートを探す - プロジェクト内で *Journey.js、*Journey.ts、*Journey.gen.js、*Journey.gen.ts に一致するファイルを検索します。これらのファイルを含むフォルダーが統合テストルートです。通常、これらのファイルはテストディレクトリ内の integration という名前のフォルダー（例：webapp/test/integration）にあります。
2. 登録方法を把握する - 既存の journey ファイルとエントリーポイントファイルを読み、journey の登録方法を確認します。構成は次の 3 種類です。
   • 仮想エンドポイント（V4）- 登録は不要です。ミドルウェアが、設定されたパターン（デフォルトでは Journey.js または Journey.ts で終わるファイル）に一致するファイルをすべて検出します
   • 物理エントリーポイント（V4）- OpaTests.qunit.js の sap.ui.require 配列に、新しい journey のモジュールパスを追加します
   • カスタムの登録方法（例：AllJourneys.js または AllJourneys.json を使用する S/4 アプリ）- 既存のパターンに従います
3. 既存の journey と同じ命名パターンに従って、journey ファイルを作成します。
4. 作成したファイルとその登録方法（または登録が自動であること）をユーザーに伝えます。

一般的なアンチパターン（V4 と V2）

これらは、OData のバージョンやテストライブラリに関係なく適用されます。

メソッド名を決して作り出さないでください。 テストライブラリに存在することが確認されたメソッドのみを使用してください。 クイックリファレンスのパターンに示されていないメソッドは、推測したり名前を組み立てたりせず、まず調べてください。

• V4：一般的なパターンについては references/v4-standard-patterns.md を確認してください。メソッドがそこにない場合は、カスタムセレクターのパターンについて references/v4-custom-selectors.md を確認してください。それでも見つからない場合は、references/v4-sap-fe-test-api-guide.md を読み、そこで案内されている公式の sap.fe.test API ドキュメントを参照してください。「正しそうに聞こえる」だけでは不十分です。存在が確認できている必要があります。
• V2：すべての V2 ページオブジェクトの完全な API リファレンスが記載された references/fiori-elements-v2-test-library.md を確認してください。

作り出したメソッドは、「not a function」という実行時エラーを出して何も起こらないため、原因の特定が困難です。

すべての opaTest に、少なくとも 1 つの Then アサーションが必要です。 Given／When ステップのみのテストは、アサーション数が 0 と報告され、何も起こらずに失敗します。

// ❌ No Then = no assertions, test fails
opaTest("Click button", function(Given, When, Then) {
    When.onThePage.iClickButton();
});

// ✅ Always end with at least one Then
opaTest("Click button", function(Given, When, Then) {
    When.onThePage.iClickButton();
    Then.onThePage.iSeeThisPage();
});

OData プロパティ名では大文字と小文字が区別されます。必ず metadata.xml の表記と完全に一致させてください。大文字と小文字が異なると、エラーメッセージではなくタイムアウトが発生します。

OPA5 の状態は、1 つのジャーニー内の opaTest ブロック間で引き継がれます。 テストは順番に実行され、同じブラウザーセッションを共有します。そのため、各 opaTest の開始時にアプリがクリーンな状態にあると想定しないでください。前のテストブロックで残された状態に依存せず、常に明示的に画面遷移を行い、アサーションで確認してください。

JourneyRunner（V4）の pages マップのキーは、ジャーニーで使用するアクセサー名と完全に一致している必要があります。 一致しないと、何も起こらずに実行時エラーが発生し、ジャーニーが呼び出そうとしたときにページオブジェクトが未定義になります。（V2 ではモジュールの読み込み時にページオブジェクトがグローバルに登録されるため、pages マップはありません。）

// ❌ Wrong - key is "onTheList" but journey calls "onTheListReport"
pages: { onTheList: ListReportPage }
// journey: When.onTheListReport.onTable()... → undefined

// ✅ Fixed - key matches accessor name exactly
pages: { onTheListReport: ListReportPage }

ジャーニーの範囲を絞り、opaTest ブロックがおよそ 10 個になったら分割してください。 大きなジャーニーファイルはデバッグに時間がかかり、保守も困難です。機能ごと、またはユーザーフローごとにジャーニーファイルを 1 つ作るのが目安です。テストライブラリ自体ですでにカバーされている、標準的な Fiori Elements の動作に対するテストは追加しないでください。

ティアダウンメソッドの名前はバージョンによって異なります。 ティアダウンはページオブジェクトではなく、必ず Given で呼び出してください。

• V4：Given.iTearDownMyApp()（大文字の D。sap.fe.test.BaseArrangements でオーバーライドされています）
• V2：Given.iTeardownMyApp()（小文字の d。基本の Opa5 メソッドです）

QUnit では、テストを検証するアサーションが必要です。ティアダウンはアサーションではないため、ティアダウンの前に必ず何かをアサートしてください。

❌ 不適切：先行するアサーションなしのティアダウン：

// V4
opaTest("Should clean up", function(Given, When, Then) {
    Given.iTearDownMyApp();
});
// V2
opaTest("Should clean up", function(Given, When, Then) {
    Given.iTeardownMyApp();
});

❌ 不適切：Given ではなくページオブジェクトにチェーンしたティアダウン：

// V4
opaTest("Should assert state and clean up", function(Given, When, Then) {
    Then.onTheListPage.iSeeThisPage()
        .and.onTheListPage.iTearDownMyApp();
});

✅ 適切：

// V4
opaTest("Should assert state and clean up", function(Given, When, Then) {
    Then.onTheListPage.iSeeThisPage();  // assertion first
    Given.iTearDownMyApp();             // teardown on Given, separate step
});
// V2
opaTest("Should assert state and clean up", function(Given, When, Then) {
    Then.onTheGenericListReport.theResultListIsVisible(); // assertion first
    Given.iTeardownMyApp();                               // teardown on Given, separate step
});

---

テストエンドポイントとテストの実行

これらは V4 と V2 の両方のプロジェクトに適用されます。

仮想テストエンドポイント（fiori-tools-preview または preview-middleware）

@sap/ux-ui5-tooling または @sap-ux/preview-middleware で ui5.yaml または ui5-mock.yaml に test ブロックを設定している場合、HTML と JS のエントリーポイントファイルはオンザフライで生成されます。そのため、opaTests.qunit.html や OpaTests.qunit.js をディスク上に用意する必要はありません。

ui5-mock.yaml の設定例：

server:
   customMiddleware:
      - name: fiori-tools-preview
        configuration:
           test:
              - framework: OPA5
                path: /test/opaTests.qunit.html # default, omit if unchanged
                init: /test/opaTests.qunit.js # default, omit if unchanged
                pattern: /test/**/*Journey{,.gen}.{js,ts} # default, omit if unchanged

設定されたパスに物理ファイルがすでに存在する場合、ミドルウェアはそのファイルを配信します（警告が表示されます）。仮想エンドポイントのプロジェクトで作業する場合は、opaTests.qunit.html や OpaTests.qunit.js を手動で作成しないでください。ファイル名が設定されたパターンに一致していれば、新しいジャーニーファイルは自動的に認識されます。

物理ファイル（従来の設定）

仮想エンドポイントを使用しない場合は、完全な構成がディスク上に存在します。

webapp/test/integration/
├── opaTests.qunit.html     <- test suite entry point (opened in browser)
├── OpaTests.qunit.js       <- imports journeys and calls QUnit.start()
├── FirstJourney.js
└── pages/
    └── ...

新しいジャーニーを登録するには、OpaTests.qunit.js の sap.ui.require 配列にそのモジュールパスを追加する必要があります。

テストの実行

npm スクリプトを使用する場合：

npm run int-test

正確なスクリプト名は package.json を確認してください。これにより、fiori run --config ./ui5-mock.yaml --open 'test/integration/opaTests.qunit.html' が実行されます。

手動で実行する場合（CAP ベースのアプリ）：

npm start  # or: cds watch

その後、ブラウザーで次を開きます：http://localhost:<port>/<app-name>/webapp/test/integration/opaTests.qunit.html

---

モックサーバー

V4 プロジェクトと V2 プロジェクトの両方に適用されます。

@sap-ux/ui5-middleware-fe-mockserver（推奨）

UI5 ツーリングレイヤーで実行されるため、バックエンドプロセスは不要です。OPA5 テストにはこちらを推奨します。V4 アプリと V2 アプリの両方に対応しています。

次のように設定します：

npx --yes @sap-ux/create@latest add mockserver-config

データモードは 2 種類あります。テストで検証する内容に応じて選択してください：

モード	設定	使用するケース
静的モックデータ	generateMockData: false	テストで特定の値（正確な件数、フィールドの内容、ID）を検証する場合。JSON ファイルは mockdataPath（デフォルト：./webapp/localService/mainService/data/）に配置します。実行ごとに結果が一定です。
動的モックデータ	generateMockData: true	テストで構造（フィールドが表示されている、テーブルに行がある）だけを検証する場合。管理する JSON ファイルは不要ですが、正確な値は検証できません。

ジャーニーでレコードを削除する場合（例：iExecuteDelete() を使用）、データを復元するため、再実行する前にサーバーを再起動してください。

sap.ui.core.util.MockServer（旧 V2 アプリ）

以前のツーリングで生成された旧 V2 アプリでは、UI5 フレームワークに組み込まれたモックサーバーを代わりに使用する場合があります。これは localService/mockserver.js で設定し、ツーリングレイヤーではなくブラウザー内で実行されます。UI5 のドキュメントを参照してください：https://ui5.sap.com/#/topic/3a9728ec31f94ca18a7d543ce419d85d

CAP バックエンド

CAP ベースのプロジェクトでは、cds watch / npm start をデータバックエンドとして使用できます。CAP のロジックをテストする必要がある専用の統合テストまたはエンドツーエンドテストに限って使用し、OPA5 テストではモックサーバーを優先してください。

---

失敗したテストのデバッグ

V4 プロジェクトと V2 プロジェクトの両方に適用されます。

テストが失敗した場合は、失敗時に一時停止するよう設定すると、失敗した箇所でアプリがブラウザー上に表示されたままになり、直接調査できます。テストエントリーポイントで、ランナーまたは Opa5.extendConfig の呼び出しより前に次の行を追加します：

sap.ui.test.qunitPause.pauseRule = "assert,timeout";

テストが一時停止したら、ブラウザーで実行中のアプリを調べ、UI に実際に表示されている内容とテストで期待されている内容を比較します。すべてのジャーニーが通過したら、この行を削除してください。

UI5 バージョン 1.147 以降では、TestRecorder ツール（sap.ui.testrecorder ライブラリ）を一時的にアプリに追加して、実行中のコントロールツリーを調べたり、複雑なセレクター向けの信頼性の高い OPA5 スニペットを生成したりできます。使用後はライブラリを削除してください。

CI で不安定になるテスト - OPA5 のデフォルトタイムアウト（15s）は、CI 環境では短すぎることがよくあります。ランナー設定でタイムアウトを 60 に増やしてください（V4 では opaConfig.timeout、V2 では Opa5.extendConfig({ timeout: 60 })）。

---

参考ファイル

ファイル	参照するタイミング
references/v4-instructions.md	V4 アプリ：テスト構成、JourneyRunner、ページオブジェクト、アンチパターン、デバッグ、UI 領域別のパターンと修正方法
references/v4-journeyrunner.md	V4：JourneyRunner の設定に関する完全なリファレンス、タイル名の検索、移植可能なジャーニーパターン
references/v4-sap-fe-test-api-guide.md	V4：sap.fe.test API ドキュメントの参照方法、命名規則、識別子のパターン
references/v4-standard-patterns.md	V4：UI 領域別のクイックリファレンス用サンプル集（アプリの起動、FilterBar、テーブル、ヘッダー、フォーム、フッター、ダイアログ、セクション、値ヘルプ、チャート、シェル）
references/v4-custom-selectors.md	V4：カスタムセレクター（最終手段）、OpaBuilder、CustomFilterField の ID、ComboBox、サフィックスに関する落とし穴
references/v2-instructions.md	V2 アプリ：セットアップ、ページオブジェクト、V2 固有の注意点
references/fiori-elements-v2-test-library.md	V2：List Report、Object Page、ALP、FCL のページオブジェクトに関する完全な API リファレンス — メソッドシグネチャー、よくある落とし穴、完全なサンプル