/sap-fiori-opa5-test-development

name: sap-fiori-opa5-test-development
description: Use this skill when writing, fixing, extending, or reviewing OPA5 integration tests
  for SAP Fiori Elements applications - whether the app uses OData V4 (sap.fe.test library)
  or OData V2 (fioriElementsTestLibrary). Triggers on any request involving OPA5 journeys,
  page objects, JourneyRunner setup, test structure, mock data, or debugging test failures
  in a SAP Fiori Elements project generated by SAP Fiori tools. Use even when the user says
  "write integration tests" or "add an OPA journey" without specifying the library, as long
  as the project context is SAP Fiori Elements. Not applicable to freestyle UI5 apps.
metadata:
   author: sap-fiori-tools
   version: "1.0.4"

SAP Fiori OPA5 Development Skill

A guide for writing, fixing, and extending OPA5 integration tests for SAP Fiori Elements applications. Covers both OData V4 (`sap.fe.test`) and OData V2 (`fioriElementsTestLibrary`).

Not applicable to freestyle UI5 applications - for those, suggest the `ui5-best-practices-opa5` skill from the **UI5 Plugins for Coding Agents** `ui5`.

---

Prerequisites

This skill requires an existing SAP Fiori Elements application generated by SAP Fiori tools with a test folder present (e.g. at `webapp/test`). If it is missing, follow the version-specific guide after detecting the OData version.

---

Step 1: Locate the Project Root

When the user provides a project name or ID (e.g. `fin.test.rap.lr3`) instead of a file path: 1. Search for `manifest.json` files under common project roots (e.g. `webapp/manifest.json`). 2. Match the `"id"` field in `sap.app` to the given name, or look for a folder whose name contains the given ID. 3. Once found, treat the folder containing `webapp/manifest.json` as the project root for all subsequent steps.

---

Step 2: Detect OData Version

Before writing any test code, determine whether the app is OData V4 or V2. The two test libraries are completely different and must never be mixed.

Primary check: `manifest.json`

| What you find | Version | Test library | |---|---|---| | `"sap.fe.templates"` key inside `sap.ui5.dependencies.libs` | **V4** | `sap.fe.test` | | `"sap.ui.generic.app"` as a root key | **V2** | `fioriElementsTestLibrary` |

Fallback check: `metadata.xml`

If `manifest.json` is inconclusive, check the `<edmx:Edmx>` root element in the service metadata file (typically at `webapp/localService/mainService/metadata.xml`, or wherever `metadataPath` points in `ui5-mock.yaml`):

| Attribute value | Version | |---|---| | `xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx"` or `Version="4.0"` | **V4** | | `xmlns:edmx="http://schemas.microsoft.com/ado/2007/06/edmx"` or `Version="1.0"` | **V2** |

These attributes appear on line 1 or 2 of the file.

If neither signal is present, ask the user to confirm the OData version before proceeding.

---

Step 3: Follow the Matching Guide

Once the version is confirmed:

1. Read the shared sections further below ("Test Endpoint and Running Tests", "Mock Server") - they apply to both V4 and V2. 2. Then read the version-specific guide for all test library decisions:

• **OData V4** - read `references/v4-instructions.md`
• **OData V2** - read `references/v2-instructions.md`

---

Adding a New Journey

When the user asks to add an additional journey (not just a new `opaTest` inside an existing journey):

1. **Find the test root** - search for files matching `*Journey.js`, `*Journey.ts`, `*Journey.gen.js`, or `*Journey.gen.ts` in the project. The folder containing those files is the integration test root. These files typically live in a folder named `integration` within the test directory, e.g. `webapp/test/integration`. 2. **Understand the wiring** - read the existing journey files and any entry point files to understand how journeys are registered. Three setups are possible:

• **Virtual endpoint** (V4) - no registration needed; the middleware picks up any file matching the configured pattern (default: ends in `Journey.js` or `Journey.ts`)
• **Physical entry point** (V4) - add the new journey's module path to the `sap.ui.require` array in `OpaTests.qunit.js`
• **Custom wiring** (e.g. S/4 apps with `AllJourneys.js` or `AllJourneys.json`) - follow the existing pattern

3. **Create the journey file** following the same naming pattern as existing journeys. 4. **Confirm** to the user which file was created and how it is registered (or that registration is automatic).

---

General Anti-Patterns (V4 and V2)

These apply regardless of OData version or test library.

**Never invent method names.** Only use methods that are confirmed to exist in the test library. If a method is not shown in the quick-reference patterns, do NOT guess or construct a name - look it up first:

• **V4**: check `references/v4-standard-patterns.md` for common patterns. If the method is not there, check `references/v4-custom-selectors.md` for custom selector patterns. If still not found, read `references/v4-sap-fe-test-api-guide.md` and consult the official `sap.fe.test` API documentation it points to. A method that "sounds right" is not sufficient — it must be confirmed to exist.
• **V2**: check `references/fiori-elements-v2-test-library.md` which contains the full API reference for all V2 page objects.

Invented methods fail silently with a "not a function" runtime error that is hard to diagnose.

**Every `opaTest` must have at least one `Then` assertion.** A test with only `Given`/`When` steps reports 0 assertions and fails silently.

// ❌ 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 property names are case-sensitive** - always match the exact casing from `metadata.xml`. Wrong ca