@roopesh.yadava/qa-pack 1.5.0 → 1.5.1

package/claude/skills/mobile-automation/BDD_TEMPLATES.md

@@ -0,0 +1,221 @@
+# Mobile BDD Templates & Reference
+
+> Load this file at the start of Phase 1 (Gherkin generation) and Phase 3 (POM), alongside
+> `LOCATOR_PATTERNS.md` and `MOBILE_MCP_REFERENCE.md`.
+> Contains the Gherkin format, step definition template, POM class template, platform-
+> conditional step pattern, app-lifecycle steps, and permission-dialog handling.
+
+---
+
+## Gherkin Format Example
+
+```gherkin
+Feature: <feature title from card>
+
+  Background: (optional — only if 2+ scenarios share the same Given)
+    Given the app is launched fresh
+
+  Rule: <business rule — taken verbatim from AC/COS>
+
+    @android @ios
+    Example: <Persona> as <role> <scenario description>
+      Given <persona> is on the <screen name> screen
+      When <persona> <action described as intent, not mechanics>
+      Then <persona> should <observable outcome>
+
+    @android
+    Example: <Android-only variation — e.g. hardware back button behavior>
+      Given ...
+      When <persona> presses the hardware back button
+      Then ...
+
+    @ios
+    Example: <iOS-only variation — e.g. swipe-back gesture>
+      Given ...
+      When <persona> swipes back from the left edge
+      Then ...
+
+    Scenario Outline: <persona> <flow description> with multiple <data type>
+      Given <persona> is on the <screen name> screen
+      When <persona> enters credentials "<username>" and "<password>"
+      Then <persona> should see "<expected_message>"
+
+      Examples:
+        | persona | username        | password     | expected_message    |
+        | John    | john@test.com   | Admin@1234   | Verification passed |
+        | Maria   | maria@test.com  | Branch@1234  | Verification passed |
+```
+
+**Platform tags:** tag every `Example`/`Scenario` `@android`, `@ios`, or both, when the
+underlying interaction differs (see `LOCATOR_PATTERNS.md` §7 hardware BACK). Untagged
+scenarios run on whichever `--project` is active per the config's platform matrix.
+
+---
+
+## Step Definition Template
+
+```javascript
+const { Given, When, Then, Before, After } = require('@cucumber/cucumber');
+const { faker } = require('@faker-js/faker');
+const LoginScreen = require('../../Pages/Auth/login-screen.cjs');
+
+let loginScreen;
+
+// ── Unconditional Before — resolve platform + fresh app state ────────────────
+Before(async function () {
+  this.platform = this.config.platform; // 'android' | 'ios' — set once, reused by every
+                                          // platform-conditional step in this run
+});
+
+// ── Steps ──────────────────────────────────────────────────────────────────
+
+Given('{word} is on the {string} screen', async function (persona, screenName) {
+  loginScreen = new LoginScreen(this.screen);
+  await loginScreen.navigateTo(screenName);
+});
+
+When('{word} enters credentials {string} and {string}', async function (persona, username, password) {
+  await loginScreen.fillCredentials(username, password);
+});
+
+Then('{word} should see {string}', async function (persona, expectedMessage) {
+  await loginScreen.verifyMessage(expectedMessage);
+});
+
+// ── Platform-conditional step (see LOCATOR_PATTERNS.md §7) ───────────────────
+When('{word} goes back', async function (persona) {
+  if (this.platform === 'android') {
+    await this.screen.pressButton('BACK');
+  } else {
+    await loginScreen.tapBackButton(); // POM method — POM decides the iOS-specific locator
+  }
+});
+
+// ── App lifecycle steps — reusable across every feature ──────────────────────
+Given('the app is launched fresh', async function () {
+  await this.device.launchApp({ newInstance: true });
+});
+
+When('{word} backgrounds the app', async function (persona) {
+  await this.screen.pressButton('HOME');
+});
+
+When('{word} resumes the app', async function (persona) {
+  await this.device.launchApp(); // foregrounds an existing instance, does not cold-start
+});
+
+// ── Permission dialog handling — call after any step that may trigger one ────
+When('the app requests permission', async function () {
+  const elements = await this.device.listElementsOnScreen();
+  const allowButton = elements.find(el => /allow|while using the app/i.test(el.text));
+  if (allowButton) {
+    await this.screen.getByText(/allow|while using the app/i).tap();
+  }
+  // No dialog present → no-op, don't fail the scenario over an OS dialog that didn't fire.
+});
+```
+
+---
+
+## POM Class Template
+
+```javascript
+const { expect } = require('@mobilewright/test');
+
+class LoginScreen {
+  /**
+   * @param {import('@mobilewright/test').Screen} screen
+   */
+  constructor(screen) {
+    this.screen = screen;
+
+    // ── Locators (constructor ONLY — never inside methods) ───────────────
+    // All locators confirmed via mobile_list_elements_on_screen on the live device
+    // Priority: resource-id/accessibility-id → getByRole/getByLabel → getByText → getByType → coordinates
+    this.usernameInput  = screen.getByTestId('login-username');
+    this.passwordInput  = screen.getByTestId('login-password');
+    this.submitButton   = screen.getByTestId('login-submit');
+    this.errorMessage   = screen.getByTestId('login-error');
+    this.backButton     = screen.getByTestId('nav-back-button'); // iOS-specific usage — see step def
+  }
+
+  // ── Navigation ───────────────────────────────────────────────────────
+
+  async navigateTo(screenName) {
+    // Screen reached via app navigation, not a URL — describe the path taken,
+    // not just the destination, since there's no direct deep link by default.
+    await this.screen.getByText(screenName).tap();
+  }
+
+  // ── Actions ──────────────────────────────────────────────────────────
+
+  async fillCredentials(username, password) {
+    await this.usernameInput.fill(username);
+    await this.passwordInput.fill(password);
+    await this.submitButton.tap();
+  }
+
+  async tapBackButton() {
+    await this.backButton.tap();
+  }
+
+  // ── Assertions ───────────────────────────────────────────────────────
+
+  async verifyMessage(expectedText) {
+    await expect(this.screen.getByText(expectedText)).toBeVisible();
+  }
+}
+
+module.exports = LoginScreen;
+```
+
+---
+
+## Faker.js Patterns (same library, same discipline as the web `automation` skill)
+
+```javascript
+const { faker } = require('@faker-js/faker');
+
+faker.string.alphanumeric(15)                             // random name
+`test+${faker.string.alphanumeric(8)}@yourdomain.com`     // email
+faker.number.int({ min: 1, max: 100 })
+faker.date.future().toISOString().split('T')[0]           // 'YYYY-MM-DD'
+```
+
+Generate inside the method — never in the constructor or at module scope.
+
+---
+
+## App-Lifecycle Step Catalog (reuse these before writing a new lifecycle step)
+
+| Step | Underlying call |
+|---|---|
+| `the app is launched fresh` | `mobile_launch_app` / `device.launchApp({ newInstance: true })` — cold start |
+| `{word} backgrounds the app` | `screen.pressButton('HOME')` |
+| `{word} resumes the app` | `device.launchApp()` (no `newInstance`) — foregrounds, doesn't cold-start (see `LOCATOR_PATTERNS.md` §10) |
+| `the app is force-closed` | `mobile_terminate_app` |
+| `the app requests permission` | dump screen, tap Allow/While-using if a system dialog is present, no-op otherwise |
+| `{word} rotates the device to {string}` | `mobile_set_orientation` + re-dump per `LOCATOR_PATTERNS.md` §9 |
+| `{word} opens the deep link {string}` | `mobile_open_url` |
+
+---
+
+## Quick Reference
+
+| Content | Location |
+|---------|----------|
+| Business rule | `Rule:` in `.feature` |
+| Platform-specific variation | `@android` / `@ios` tag on the `Example`/`Scenario` |
+| Persona/role variation | `Example:` block |
+| Same flow, different data | `Scenario Outline` + `Examples:` |
+| Locators discovered | `mobile_list_elements_on_screen` on the live device |
+| Locators written | POM constructor only |
+| Actions | POM async methods |
+| Assertions | POM `verify*` methods |
+| Generated test data | `faker.js` — inside methods |
+| Direct `screen.getByX()` calls in step files | ❌ Never — always go through POM methods |
+| Hardcoded coordinates | ❌ Last resort only, see `LOCATOR_PATTERNS.md` |
+| Hardcoded waits | ❌ Never — use `expect(...).toBeVisible()` |
+| `import`/`export` | ❌ Use `require`/`module.exports` (CommonJS, matches the web skill's convention unless the repo's own discovered convention says otherwise) |
+| Gate 1 skipped | ❌ Never — always confirm Gherkin before writing code |
+| Gate 2 skipped | ❌ Never — always confirm step defs before writing POM |

package/claude/skills/mobile-automation/LOCATOR_PATTERNS.md

@@ -0,0 +1,205 @@
+# Mobile Locator Patterns — Hard-Won Lessons
+
+> Load this file before Phase 2 (Step Definitions) and Phase 3 (POM), alongside
+> `BDD_TEMPLATES.md` and `MOBILE_MCP_REFERENCE.md`. Apply every rule below before writing
+> any locator.
+
+## Locator Priority (strictly enforced)
+
+| Priority | Method | Use when |
+|----------|--------|----------|
+| 1 ✅ | `screen.getByTestId('...')` | Always prefer — maps to `resource-id` (Android) / `accessibility-id` (iOS). Ask for one to be added if missing rather than falling further down this table |
+| 2 ✅ | `screen.getByRole(...)` | When no resource-id/accessibility-id exists |
+| 3 ⚠️ | `screen.getByLabel('...')` | Accessibility label present, no role match |
+| 4 ⚠️ | `screen.getByText('...')` | Visible text only — fragile across locales, use a regex where wording may vary |
+| 5 ⚠️ | `screen.getByType('...')` | Element type only — broad, matches multiple elements easily |
+| 6 ❌ | `mobile_click_on_screen_at_coordinates(x, y)` | Last resort only — breaks on any resolution/orientation/layout change. Comment why no better locator existed |
+
+---
+
+### 1. `resource-id` and `accessibility-id` are not the same field
+
+Android exposes `resource-id`; iOS exposes `accessibility-id` (sometimes surfaced as `name`
+depending on the inspection tool). `mobile_list_elements_on_screen` returns whichever field
+the platform actually has — checking only one will silently miss the other platform's
+elements in a cross-platform project.
+
+```javascript
+// ❌ WRONG — only checks the Android field name, misses every iOS element
+const hasTestId = element['resource-id'];
+
+// ✅ CORRECT — check both, platform-agnostic
+const hasTestId = element['resource-id'] || element['accessibility-id'] || element['name'];
+```
+
+`screen.getByTestId(...)` in MobileWright abstracts this for you at the framework level —
+but when reasoning from a raw `mobile_list_elements_on_screen` dump during authoring or
+self-heal, check both fields yourself before concluding "no testid on this element."
+
+---
+
+### 2. WebView / hybrid screens don't expose native resource-ids for their content
+
+A screen embedding a WebView (in-app browser, hybrid checkout, help center) reports the
+WebView container as one native element — the HTML content inside it is invisible to
+`mobile_list_elements_on_screen`.
+
+```javascript
+// ❌ WRONG — assumes the hybrid content has a resource-id, times out
+this.helpArticleLink = screen.getByTestId('help-article-3');
+
+// ✅ CORRECT — flag it, don't retry the native locator harder
+// "This screen is a WebView — native resource-id inspection won't find its content.
+//  Falls back to getByText() on visible text, or needs a web-style inspection strategy."
+this.helpArticleLink = screen.getByText('Refund policy');
+```
+
+---
+
+### 3. System permission dialogs interrupt the flow unpredictably
+
+A location/camera/notification/contacts permission prompt is OS-level chrome, not app UI —
+it can appear right after a navigation step and block every subsequent tap until dismissed.
+
+```javascript
+// ❌ WRONG — assumes the next screen loaded; every following action times out
+await screen.getByTestId('enable-location').tap();
+await screen.getByTestId('map-view').waitFor(); // times out — a permission dialog is covering it
+
+// ✅ CORRECT — check for a system dialog before assuming the locator is wrong
+const elements = await mobile_list_elements_on_screen();
+if (elements.some(el => /allow|deny|while using the app/i.test(el.text))) {
+  await screen.getByText(/allow|while using the app/i).tap();
+}
+await screen.getByTestId('map-view').waitFor();
+```
+
+If a test hits "element not found" right after a step that plausibly triggers a permission
+prompt, dump the screen and check for dialog text before concluding the locator is broken.
+
+---
+
+### 4. Coordinate taps are resolution/DPI-relative — never hardcode across a device matrix
+
+A coordinate captured on one simulator breaks on a different device profile, and definitely
+breaks across a `projects` matrix spanning multiple device sizes.
+
+```javascript
+// ❌ WRONG — works on iPhone 15 Pro sim, wrong on every other device in the matrix
+await mobile_click_on_screen_at_coordinates(187, 640);
+
+// ✅ CORRECT — resolve locator by identifier, use coordinates only as documented last resort
+await screen.getByTestId('agree-checkbox').tap();
+```
+
+---
+
+### 5. The soft keyboard shifts layout — re-dump before any coordinate fallback
+
+Focusing a text field can push screen content upward to make room for the keyboard. Any
+coordinates recorded before that focus are now wrong.
+
+```javascript
+// ❌ WRONG — coordinate recorded before the keyboard appeared
+await screen.getByLabel('Email').fill('user@example.com');
+await mobile_click_on_screen_at_coordinates(200, 500); // may now hit a different element
+
+// ✅ CORRECT — re-dump after any focus change if a coordinate fallback is unavoidable
+await screen.getByLabel('Email').fill('user@example.com');
+const elements = await mobile_list_elements_on_screen(); // re-dump post-keyboard
+```
+
+---
+
+### 6. OTP autofill can race a manual `type` action
+
+Both platforms often auto-fill an SMS OTP into the field without any typed input. A step that
+types digit-by-digit can collide with the autofill and leave the field in an unexpected state.
+
+```javascript
+// ❌ WRONG — assumes typing succeeded, doesn't verify against a possible autofill race
+await screen.getByTestId('otp-input').fill(otpCode);
+await screen.getByTestId('verify-button').tap();
+
+// ✅ CORRECT — verify the field's actual value before proceeding
+await screen.getByTestId('otp-input').fill(otpCode);
+await expect(screen.getByTestId('otp-input')).toHaveText(otpCode);
+await screen.getByTestId('verify-button').tap();
+```
+
+---
+
+### 7. Hardware BACK is Android-only
+
+`screen.pressButton('BACK')` has no iOS equivalent — iOS uses an edge swipe gesture or an
+explicit on-screen back element instead.
+
+```javascript
+// ❌ WRONG — a shared step across both platforms with no branch
+When('{word} goes back', async function () {
+  await this.screen.pressButton('BACK');   // does nothing meaningful on iOS
+});
+
+// ✅ CORRECT — platform-conditional step, resolved from the World/config
+When('{word} goes back', async function () {
+  if (this.platform === 'android') {
+    await this.screen.pressButton('BACK');
+  } else {
+    await this.screen.getByTestId('nav-back-button').tap(); // or a swipe gesture
+  }
+});
+```
+
+---
+
+### 8. Dynamic/virtualized lists — an element not in the dump may just be off-screen
+
+Long lists (`RecyclerView`, `UICollectionView`, virtualized FlatLists) only render items near
+the viewport. `mobile_list_elements_on_screen` returning no match for a list item doesn't
+always mean the locator is wrong.
+
+```javascript
+// ❌ WRONG — concludes the locator is broken after one failed dump
+// "getByTestId('item-42') not found — locator must be wrong"
+
+// ✅ CORRECT — swipe toward the expected item first, then re-check
+await screen.swipe('up', { distance: 400 });
+const elements = await mobile_list_elements_on_screen(); // re-dump after scroll
+```
+
+---
+
+### 9. Orientation changes re-lay the whole screen
+
+A `resource-id`/`accessibility-id` usually survives rotation; its on-screen coordinates never
+do. Any scenario that rotates mid-flow must re-dump before falling back to a coordinate
+locator afterward.
+
+```javascript
+// ❌ WRONG — coordinate captured in portrait, used again after rotating to landscape
+await mobile_set_orientation('landscape');
+await mobile_click_on_screen_at_coordinates(300, 120); // stale — layout has changed
+
+// ✅ CORRECT
+await mobile_set_orientation('landscape');
+const elements = await mobile_list_elements_on_screen(); // re-dump post-rotation
+```
+
+---
+
+### 10. Backgrounding vs terminating are different device states
+
+`mobile_terminate_app` forces a cold start on next launch. Pressing `HOME`
+(`screen.pressButton('HOME')`) leaves the app alive in the background. A scenario testing
+"resume where you left off" needs HOME + relaunch, not terminate + launch — using the wrong
+one tests the wrong behavior entirely.
+
+```javascript
+// ❌ WRONG — tests cold-start behavior when the scenario is about background resume
+await mobile_terminate_app(bundleId);
+await mobile_launch_app(bundleId);
+
+// ✅ CORRECT — genuine background/resume
+await screen.pressButton('HOME');
+await mobile_launch_app(bundleId); // brings the backgrounded app back to foreground
+```

package/claude/skills/mobile-automation/MOBILE_MCP_REFERENCE.md

@@ -0,0 +1,234 @@
+# Mobile MCP + MobileWright — Command & Tool Reference
+
+> Load this file once at Phase 0 (Environment + Device Discovery). Do not reload later in
+> the run — reference tools/commands by name from context, same discipline as the web
+> `automation` skill applies to `LOCATOR_PATTERNS.md`.
+
+## Two tool surfaces — know which one to reach for
+
+| Surface | Role | When to use |
+|---|---|---|
+| **Mobile MCP** (`mobile-next/mobile-mcp`) | Live device control — the mobile equivalent of Playwright MCP. Drives the actual simulator/emulator/real device during authoring and self-heal. | Discovering devices/apps, inspecting the current screen, tapping/typing/swiping to explore a flow before writing a locator, re-inspecting on self-heal |
+| **MobileWright** (`mobilewright` CLI + `@mobilewright/test`) | The authored test framework — what the generated Gherkin/step-defs/POM actually run against. | Writing the real test code, running the real suite, generating reports |
+
+Generated tests never call Mobile MCP tools directly. Mobile MCP is this skill's
+authoring/inspection tool — exactly how Playwright MCP is used by the web `automation`
+skill, never referenced from inside the `.feature`/step-def/POM files it produces.
+
+## Mobile MCP — Tool Catalog
+
+From `mobile-next/mobile-mcp`. Verify exact names **and parameters** against whatever server
+is actually connected before relying on them — MCP servers version-drift like anything else;
+if a tool listed here doesn't exist, or takes different arguments than assumed, treat the
+connected server as the current truth, not this table. In particular: when Phase 0c resolves
+more than one connected device, check whether each tool call below needs an explicit device
+identifier passed alongside it — don't assume every call implicitly targets "the" device
+once more than one is available.
+
+### Device Management
+| Tool | Purpose |
+|---|---|
+| `mobile_list_available_devices` | Lists simulators, emulators, and connected real devices |
+| `mobile_get_screen_size` | Screen dimensions in pixels — needed before any coordinate-based tap |
+| `mobile_get_orientation` / `mobile_set_orientation` | Read / change portrait ↔ landscape |
+
+### App Management
+| Tool | Purpose |
+|---|---|
+| `mobile_list_apps` | Installed apps on the device |
+| `mobile_launch_app` | Start an app by package/bundle ID |
+| `mobile_terminate_app` | Stop a running app — cold-start on next launch (distinct from HOME — see `LOCATOR_PATTERNS.md` §10) |
+| `mobile_install_app` | Deploy `.apk` / `.ipa` / `.app` / `.zip` |
+| `mobile_uninstall_app` | Remove by bundle ID / package name |
+
+### Screen Interaction & UI Inspection
+| Tool | Purpose | Token cost |
+|---|---|---|
+| `mobile_list_elements_on_screen` | Reads the real accessibility tree — coordinates + properties **including `resource-id` and accessibility-id fields**. Mobile equivalent of `browser_snapshot()` / DOM inspection. | Expensive — full tree. Once per new/changed screen, never per interaction |
+| `mobile_take_screenshot` | Captures current screen, returned inline | Expensive if not saved |
+| `mobile_save_screenshot` | Persists screenshot straight to a file | Cheap — zero response tokens, use for all evidence capture |
+| `mobile_click_on_screen_at_coordinates` | Tap at x,y | Last-resort locator method only |
+| `mobile_double_tap_on_screen` | Double-tap at x,y | — |
+| `mobile_long_press_on_screen_at_coordinates` | Long-press at x,y | — |
+| `mobile_swipe_on_screen` | Directional swipe (up/down/left/right) | — |
+
+### Input & Navigation
+| Tool | Purpose |
+|---|---|
+| `mobile_type_keys` | Enter text, optional submit |
+| `mobile_press_button` | `HOME` / `BACK` (Android only) / `VOLUME_UP` / `VOLUME_DOWN` / `ENTER` |
+| `mobile_open_url` | Open a URL in the device browser — deep-link entry points |
+
+### Recording & Diagnostics
+| Tool | Purpose |
+|---|---|
+| `mobile_start_screen_recording` / `mobile_stop_screen_recording` | Video capture across a multi-step flow |
+| `mobile_list_crashes` / `mobile_get_crash` | Retrieve crash reports — pull the crash report into a bug candidate's Description when a self-heal assertion failure coincides with a crash |
+
+## Token Discipline
+
+Mirrors the web `automation`/`manual-testing` skills' Playwright rules — same principle, different tool names:
+
+| Operation | Use | Avoid | Why |
+|---|---|---|---|
+| Screen inspection | `mobile_list_elements_on_screen` once per new/changed screen | Calling it after every single tap | Full accessibility tree — same cost profile as `browser_snapshot()` |
+| Evidence capture | `mobile_save_screenshot` | `mobile_take_screenshot` without saving | Inline image return burns response tokens |
+| Repeated screens | Fingerprint check (below) before re-inspecting | Re-dumping a screen whose resource-ids haven't moved | Same principle as the web skill's DOM fingerprint cache |
+
+## Resource-ID / Accessibility-ID Detection ("is there a testid on this screen")
+
+Before writing any locator, dump the current screen and check whether the target element
+carries a stable identifier:
+
+```
+mobile_list_elements_on_screen()
+```
+
+For each element in the result, check in this order:
+1. **`resource-id`** (Android) or **`accessibility-id`** (iOS) — if present, this is the
+   mobile equivalent of a web `data-testid` and maps directly to MobileWright's
+   `screen.getByTestId(...)`. Check both field names — they aren't interchangeable across
+   platforms (see `LOCATOR_PATTERNS.md` §1).
+2. If absent, check for an accessibility label/role (`getByLabel` / `getByRole`).
+3. If neither, fall through to the Locator Priority table in `LOCATOR_PATTERNS.md`.
+
+If `npx mobilewright --help` (checked once at Phase 0) reveals a dedicated UI-dump command in
+the installed version, prefer it for authoring convenience — but `mobile_list_elements_on_screen`
+stays the source of truth during self-heal since it reflects the live device, not a static
+dump. Don't assume a specific dump subcommand name beyond what `--help`/`doctor` actually shows
+for the installed version.
+
+## MobileWright — Setup & Environment Commands
+
+```bash
+npx mobilewright doctor                          # environment health check (Xcode, ADB, simulators)
+npx mobilewright doctor --json                   # machine-readable, for logging without narrating to chat
+npx mobilewright doctor --category ios|android|system
+npx mobilewright devices                         # list connected devices/simulators/emulators
+npm init mobilewright@latest                     # scaffold config + example test (skips existing files)
+```
+
+`mobilecli` (the device server) must already be running in a separate terminal —
+`mobilecli start`. If any MCP tool call or `doctor` reports no device / connection refused,
+stop and ask the user to confirm `mobilecli` is running before proceeding — same pattern as
+the web skill's Playwright MCP pre-flight check.
+
+## MobileWright — Config Reference
+
+`mobilewright.config.ts` (or `.js`) at the project root. Config values are defaults —
+options passed directly to a launch call always win.
+
+```typescript
+import { defineConfig } from 'mobilewright';
+
+export default defineConfig({
+  platform:    'android',          // 'ios' | 'android'
+  bundleId:    'com.example.app',
+  deviceName:  /Pixel 7/,
+  installApps: './builds/app.apk',
+  timeout:     10_000,
+  retries:     1,
+  reporter:    'html',
+});
+```
+
+Multi-platform matrix:
+```typescript
+export default defineConfig({
+  projects: [
+    { name: 'iOS',     platform: 'ios',     bundleId: 'com.app.ios' },
+    { name: 'Android', platform: 'android', bundleId: 'com.app.android' },
+  ],
+});
+```
+
+## MobileWright — Test-Writing API (what generated POM/step defs call)
+
+```typescript
+import { test, expect } from '@mobilewright/test';
+
+// Finding elements — priority order matches LOCATOR_PATTERNS.md
+screen.getByTestId('submit-button');            // 1st — maps to resource-id/accessibility-id
+screen.getByRole('button', { name: 'Submit' });  // 2nd
+screen.getByLabel('Username');                   // 2nd (accessibility label)
+screen.getByText('Sign In');                      // 3rd — fragile across locales
+screen.getByType('TextField');                    // 4th — broad, last resort before coordinates
+
+// Actions
+await screen.getByText('Sign In').tap();
+await screen.getByRole('button', { name: 'Submit' }).doubleTap();
+await screen.getByText('Options').longPress();
+await screen.getByLabel('Email').fill('user@example.com');
+await screen.swipe('up');
+await screen.swipe('down', { distance: 300 });
+await screen.pressButton('HOME');
+await screen.pressButton('BACK'); // Android only
+
+// Assertions
+await expect(screen.getByText('Welcome')).toBeVisible();
+await expect(screen.getByRole('button', { name: 'Submit' })).toBeEnabled();
+await expect(screen.getByTestId('greeting')).toHaveText('Hello, World');
+await expect(screen.getByText('Error')).not.toBeVisible();
+```
+
+## MobileWright — Running Tests
+
+Native runner:
+```bash
+npx mobilewright test                       # all tests
+npx mobilewright test tests/login.test.ts   # one file
+npx mobilewright test --grep "sign in"
+npx mobilewright test --project=ios
+npx mobilewright test --list                # list without running
+```
+
+BDD/Cucumber profile — this skill's default output shape, matching the pack's existing
+reuse-first Gherkin approach:
+```bash
+npm test                        # all features, default profile
+npm run test:android            # PLATFORM=android
+npm run test:ios                # PLATFORM=ios
+npm run test:dry                # validate steps without touching a device — mobile
+                                 # equivalent of `cucumber-js --dry-run`
+npx cucumber-js test/features/Auth/login.feature
+npx cucumber-js --tags @smoke
+```
+
+Reports:
+```bash
+npx mobilewright show-report
+npx mobilewright show-report --host 0.0.0.0 --port 8080
+npm run report:open              # BDD profile's cucumber-report.html
+```
+
+## MobileWright — Project Structure (BDD/Cucumber profile)
+
+Discover this at Phase 0 — never impose it if the repo already has its own layout, same rule
+the web `automation` skill follows for its tree (including preserving any existing typos):
+
+```
+test/
+  app/                    # .apk / .ipa binaries
+  features/               # Gherkin .feature files
+  Pages/                  # Page Object Model classes
+  step_definitions/       # Cucumber step implementations (Driver.js = World + hooks)
+  TestData/                # Faker-based test data generators
+  Utils/BasePage.js        # Base class for all page objects
+cucumber.js                # Cucumber profile config
+mobilewright.config.js
+.env.example / .env
+```
+
+## Debugging
+
+```bash
+DEBUG=mw:* npx mobilewright test        # verbose logging
+MWDEBUGIMPL=1 npx mobilewright test     # verbose driver output
+```
+
+| Issue | Fix |
+|---|---|
+| `mobilecli: command not found` | `npm install -g mobilecli@latest` |
+| No devices found / connection refused | `adb kill-server && adb start-server && adb devices`, or confirm `mobilecli start` is running |
+| Tests time out immediately | Confirm `mobilecli` running, device ID matches `mobilewright devices`, raise timeout |
+| iOS not running on Linux/Windows | iOS requires macOS + Xcode — use `platform: 'android'` elsewhere |