feat(ui5): Add OPA5 guidelines as Skills (#64)

Adding skills for OPA5 integration testing.

JIRA: BGSOFUIPIRIN-6914

Author: kineticjs

plugins/ui5/.github/plugin/plugin.json

@@ -13,6 +13,7 @@
         "ui5",
         "sapui5",
         "openui5",
+        "opa5",
         "plugin",
         "linter",
         "api-documentation",

plugins/ui5/README.md

@@ -1,6 +1,6 @@
 # UI5 Plugin for Coding Agents
 
-Complete SAPUI5 / OpenUI5 plugin for coding agents with MCP tools, API documentation access, linting capabilities, and development guidelines.
+Complete SAPUI5 / OpenUI5 plugin for coding agents with MCP tools, API documentation access, linting capabilities, development and integration testing guidelines.
 
 ---
 
@@ -42,6 +42,15 @@ Development guidelines for UI Integration Cards (also known as UI5 Integration C
 - **i18n** - Bind all user-facing strings to the i18n model; never hardcode
 - **Actions** - Use the `actions` property for links and interactions; never inline `<a>` tags or hand-roll URL handlers
 
+#### ui5-best-practices-opa5
+
+Guidelines and debugging workflow for OPA5 integration tests:
+
+- **Failure inspection** - Pause-on-failure mode (`sap.ui.test.qunitPause.pauseRule`) keeps the app live at the failure point for browser inspection
+- **TestRecorder tooling** - Temporary `sap.ui.testrecorder.ControlTree` integration to inspect the live control tree and generate reliable OPA5 snippets (UI5 ≥ 1.147)
+- **Page object organization** - Placement of actions and assertions across views
+- **App teardown** - Cleanup patterns in OPA5 journey tests
+
 ---
 
 ## Installation

plugins/ui5/plugin.json

@@ -13,6 +13,7 @@
         "ui5",
         "sapui5",
         "openui5",
+        "opa5",
         "plugin",
         "linter",
         "api-documentation",

plugins/ui5/skills/ui5-best-practices-opa5/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: ui5-best-practices-opa5
+description: This skill should be used in any OPA5 task - creating, modifying, extending, debugging, fixing or reviewing an integration test. Use when the user asks to "write an OPA5 test", "add an OPA5 journey", "fix the OPA5 test failure" or mentions OPA5 or its components - opaTest, page object, journey, waitFor.
+---
+
+# OPA5 Guidelines and Tools
+
+## Handle Special Cases (follow when planning and writing an OPA5 test)
+- **Initial Configuration for OPA5 Test** → follow `references/configuration.md`
+- **If the test-case spans multiple views** → follow `references/handle-multiple-views.md`
+- **Teardown the App** → follow `references/handle-teardown.md`
+
+## Set Up Browser Inspection Tools (follow **before running the OPA5 test**)
+**Purpose:** Efficient inspection of test failures with minimal steps.
+**Prerequisites:** A tool to load the OPA5 test in the browser and evaluate javascript in the browser window (e.g. MCP Playwright)
+**Instructions:** → follow `references/setup-inspection-tools.md`

plugins/ui5/skills/ui5-best-practices-opa5/references/configuration.md

@@ -0,0 +1,26 @@
+# Configuration
+
+1. Use this folder layout:
+```
+test/integration/
+├── opaTests.qunit.js   ← single entry point
+├── pages/
+│   ├── Welcome.js      ← one page object per view (name matches the view)
+│   ├── Items.js
+│   └── Browser.js      ← cross-view actions (navigation, hash)
+├── WelcomeJourney.js   ← one journey per feature/functionality
+└── FilterItemsJourney.js
+```
+
+2. **ALWAYS** enable `autoWait` and define `viewNamespace` globally in `opaTests.qunit.js`.
+```javascript
+// opaTests.qunit.js
+sap.ui.define(["sap/ui/test/Opa5"], (Opa5) => {
+	"use strict";
+    Opa5.extendConfig({
+		autoWait: true,
+		viewNamespace: "com.myorg.myapp.view."
+	});
+	// ...
+});
+```

plugins/ui5/skills/ui5-best-practices-opa5/references/enable-testrecorder-tooling.md

@@ -0,0 +1,65 @@
+# TestRecorder Tooling
+
+The `sap.ui.testrecorder` library provides the module `sap.ui.testrecorder.ControlTree` that allows to:
+- inspect the live control tree in the browser
+- retrieve reliable OPA5 snippets for interacting with any part of the control tree
+
+## Prerequisites to Use `sap.ui.testrecorder.ControlTree`
+
+- **UI5 version ≥ 1.147**
+- Tool to load the OPA5 test in the browser and evaluate javascript in the browser window (e.g. MCP Playwright)
+- **`sap.ui.testrecorder` library loaded** — temporarily add to the app's library declarations in the places listed below (**ORDERED BY PRIORITY**):
+  1. `ui5.yaml` → `framework.libraries`: `- name: sap.ui.testrecorder`
+  2. `manifest.json` → `sap.ui5.dependencies.libs`: `"sap.ui.testrecorder": {}`
+  3. `index.html` → `data-sap-ui-libs` bootstrap attribute: append `,sap.ui.testrecorder`
+
+  > After adding to `ui5.yaml` ensure the server is serving the added library before proceeding:
+  > ```bash
+  > curl -s -o /dev/null -w "%{http_code}" \
+  >   http://localhost:8080/resources/sap/ui/testrecorder/ControlTree.js
+  > ```
+  > If 404, **ALWAYS** start a fresh server on the next free port (8081, 8082, …) and use that port
+  >   for all subsequent browser navigation
+
+  > Remove `sap.ui.testrecorder` after use — not needed at runtime.
+  > Kill after use any started fresh server instance.
+
+## `sap.ui.testrecorder.ControlTree` API
+
+**`ControlTree.search(query)`** — Search the live UI5 control tree.
+- Returns `Promise<string>` — a tree snapshot with matching controls and their parents
+- `query=""` returns the full tree; `query="anchorBar"` returns filtered results
+- Matches against control type short names, non-default property values, and accessibility attributes
+- Each node carries a `nodeId="N_M"` (snapshot N, node M) — use these in `ControlTree` methods that require a `nodeId` parameter
+
+**`ControlTree.getControlData(nodeId)`** — Get selector and full control state.
+- Returns `Promise<{ selectorSnippet, properties, aggregations, associations, bindings }>`
+- `selectorSnippet` — OPA5 `waitFor` code to locate the control (use as the base selector)
+- Other fields provide live control state for customizing assertions
+
+**`ControlTree.press(nodeId, settings?)`** — Press a control and get its OPA5 action snippet.
+- Returns `Promise<string>` — an OPA5 `waitFor` snippet with `actions: new Press()`
+- Also **replays the press** on the running app, advancing the UI state for the next search
+- Optional `settings`: `altKey`, `ctrlKey`, `shiftKey`, `xPercentage`, `yPercentage`
+
+**`ControlTree.enterText(nodeId, settings)`** — Type into a control and get its OPA5 action snippet.
+- Returns `Promise<string>` — an OPA5 `waitFor` snippet with `actions: new EnterText()`
+- Also **replays the text entry** on the running app
+- `settings`: `text`, `clearTextFirst` (default `true`), `submitText` (default `true`)
+
+## Example Usage
+
+```javascript
+sap.ui.require(["sap/ui/testrecorder/ControlTree"], async (ControlTree) => {
+    "use strict";
+    // Navigate to the state where the anchor bar is visible, then:
+    await ControlTree.search("anchorBar"); // When resolved, inspect the returned markdown snapshot and pick nodeId, e.g. Button nodeId="1_8" text="Methods"
+
+    // Use the picked nodeId to interact with the corresponding control
+    await ControlTree.press("1_8"); // When resolved, save the returned OPA5 snippet; UI has now navigated
+
+    await ControlTree.search("selectedSection"); // When resolved, parse returned snapshot and pick nodeId, e.g. ObjectPageLayout nodeId="2_3"
+
+    await ControlTree.getControlData("2_3"); // When resolved, save result.selectorSnippet + result.associations → build assertion
+});
+```

plugins/ui5/skills/ui5-best-practices-opa5/references/handle-multiple-views.md

@@ -0,0 +1,35 @@
+# Page Object Organization Across Multiple Views
+
+**ALWAYS** add the new actions/assertions to the semantically corresponding page object
+
+Example 1:  
+❌ Anti-Pattern:  
+Adding selector for a control from `App.view.xml` into the page object for its **nested** view (e.g. into `integration/pages/Detail.js` for `Detail.view.xml`):
+```javascript
+// integration/pages/Detail.js
+iShouldSeeTheAppInFullScreenMode() {
+	return this.waitFor({
+		id: "layout",
+		viewName: "App",
+		success: function () { ... }
+	});
+},
+```
+✅ Correct Pattern:  
+Place the assertion for the `App.view.xml` in page object file `integration/pages/App.js`
+
+Example 2:  
+❌ Anti-Pattern:  
+View-specific page object file containing selector for cross-view navigation:
+```javascript
+// integration/pages/Detail.js
+iShouldSeeTheHash(sExpectedHash) {
+	return this.waitFor({
+		success: function () {
+			Opa5.assert.strictEqual(Opa5.getHashChanger().getHash(), sExpectedHash, "The Hash not correct");
+		}
+	});
+},
+```
+✅ Correct Pattern:  
+Place the actions/assertions for cross-view navigation into page object `integration/pages/Browser.js`

plugins/ui5/skills/ui5-best-practices-opa5/references/handle-teardown.md

@@ -0,0 +1,26 @@
+# Teardown the App
+
+QUnit requires assertions to validate tests. Teardown methods are NOT assertions.
+
+❌ Incorrect:
+```javascript
+opaTest("Should clean up", function(Given, When, Then) {
+    Then.iTeardownMyApp();  // ❌ missing assertion (because teardown is not an assertion)
+});
+```
+
+❌ Incorrect:
+```javascript
+opaTest("Should assert state and clean up", function(Given, When, Then) {
+    Then.onTheWorklistPage.iShouldSeeTheTable()
+      .and.onTheWorklistPage.iTeardownMyApp();  // ❌ chaining on wrong object
+});
+```
+
+✅ Correct:
+```javascript
+opaTest("Should assert state and clean up", function(Given, When, Then) {
+    Then.onTheWorklistPage.iShouldSeeTheTable() // ✅ assertion before teardown
+      .and.iTeardownMyApp();  // ✅ correct chaining
+});
+```

plugins/ui5/skills/ui5-best-practices-opa5/references/setup-inspection-tools.md

@@ -0,0 +1,24 @@
+# Set Up Browser Inspection Tools
+
+**Prerequisites:** A tool to load the OPA5 test in the browser and evaluate javascript in the browser window (e.g. MCP Playwright)
+
+## 1. Set Up TestRecorder Tooling (UI5 version ≥ 1.147 only)
+**Purpose:**
+- Diagnose issues by inspecting the live control tree in the browser, including private/internal controls the test needs to find;
+- Collect reliable OPA5 snippets for non-trivial actions and assertions.
+**Setup:** Follow `enable-testrecorder-tooling.md` for detailed instructions.
+
+## 2. Enable Pause-on-Failure Mode (all UI5 versions)
+**Purpose:** When enabled, execution pauses on the first test failure and the app remains live in the browser exactly as it was at the point of failure — no teardown, no reload happens automatically. The paused state persists until you explicitly navigate away, so you can inspect the actual UI directly (without reloading) in the browser to see why it differs from what the test expected.
+**Setup:** Add the following line to your test entry point (right before `Opa5.extendConfig`):
+```javascript
+// Inside the existing sap.ui.define callback in your test entry point
+sap.ui.test.qunitPause.pauseRule = "assert,timeout"; // enables pause on assertion failures and timeouts
+// Opa5.extendConfig({...});
+```
+
+## Workflow
+1. Enable the inspection tools above and load the test in the browser.
+2. When the test pauses on failure, inspect the app in the browser. Before changing any code, verify the full causal chain with no gaps. Rule out app-side issues before assuming the test is wrong.
+3. Iterate on the test until all journeys pass.
+4. Once all journeys pass, remove the `sap.ui.testrecorder` library from the app and the pause-on-failure rule `sap.ui.test.qunitPause.pauseRule`.