@roopesh.yadava/qa-pack 1.4.0 → 1.5.1

package/claude/skills/manual-testing/TEST_DESIGN_GUIDE.md

@@ -0,0 +1,200 @@
+# Test Design Guide — Requirement Analysis, Coverage Dimensions, Scenario Framework
+
+Loaded once by the manual-testing skill at Phase 1 (Requirement Analysis). Reference sections
+by number afterward (e.g. "per §2 trigger table") — never re-quote this file in chat or in
+saved reports.
+
+Purpose: manual testing should verify a feature is functionally correct, usable, reliable,
+secure, compatible, and aligned with business expectations — not just that the happy path
+works. This guide operationalizes that without inflating every card into the same fixed
+checklist: coverage is scoped by what the card actually touches (§2) and by risk (§4), so a
+copy-change card and a payment card get proportionally different depth.
+
+---
+
+## §1 — Requirement Gap Checklist
+
+Run once per card, right after Phase 1 fetch, before the test plan is drafted. For each row
+whose signal is present, fold the question into the **one** consolidated gap-question message
+(same message as any Phase 0 gaps — never a second round of questions). Skip a row entirely
+if the AC already answers it — do not manufacture questions on a precise, complete AC.
+
+| Gap type | Signal to look for | Question to ask if missing |
+|---|---|---|
+| No AC at all | Card has no AC/COS section | "No Acceptance Criteria found — what should be tested?" (most severe — if this fires, skip the rest of this table and just ask this) |
+| Ambiguous requirement | Vague terms in AC ("appropriate", "as needed", "similar to", "etc.") | Quote the exact phrase, ask for the precise rule |
+| Missing validation rule | A field/form is named with no stated format or limit | "What's the valid format/limit for {field}?" |
+| Missing negative/error case | AC describes only the happy path, no failure behavior | "What should happen on {plausible failure mode}?" |
+| Missing permission rule | Roles/access mentioned but AC doesn't say who can do what | "Which roles can perform this action?" |
+| Missing boundary condition | A numeric/length limit is implied ("a short code", "a few items") but not exact | "What's the exact min/max for {field}?" |
+| Missing state/workflow rule | A status/workflow field exists but transitions aren't listed | "What are the valid status transitions?" |
+| Missing data relationship | AC needs a specific paired entity (parent+child, account+card) without naming which | Already covered by the skill's Test Data & Entity Selection Rules — ask once or mark `🔒 BLOCKED`, don't duplicate the question here |
+
+---
+
+## §2 — Feature Signal → Coverage Dimension Trigger Table
+
+Scan the card title + AC (already read in Phase 1 — no extra fetching, no grepping `src/`)
+for these signals. A matched signal turns its dimension(s) ON for test-plan generation in
+Phase 3a. Untriggered dimensions are not drafted — this is what keeps test count proportional
+to the card instead of forcing all 19 dimensions onto every run.
+
+| Signal in title/AC | Dimensions turned ON |
+|---|---|
+| login, auth, OTP, session, token, password, logout | Authentication, Security-oriented, State/Workflow (session) |
+| role, permission, admin, restricted, access level | Authorization / Permissions |
+| payment, price, amount, invoice, refund, subscription, billing, calculation | Boundary/Equivalence, Business Rules, Database, Security-oriented |
+| delete, remove, deactivate, cancel, archive | Negative, State/Workflow, Database (soft vs hard delete) |
+| upload, download, attachment, file, import, export | File Upload/Download |
+| search, filter, sort, paginate, list, table, grid | Search/Filter/Sort/Pagination |
+| API, endpoint, integration, webhook, third-party, external service, sync | API, Integration |
+| status, state, workflow, transition, approve, submit, draft, review | State/Workflow |
+| any form or input field named in the AC | Validation, Boundary/Equivalence |
+| notification, email, SMS, push, alert, toast, reminder | Notifications |
+| multi-step flow, wizard, redirect, navigation between screens | End-to-End |
+| *(always on, every card)* | Functional Positive, Functional Negative, UI/UX States |
+
+No specific signal matched → draft Functional (positive + one negative) + UI/UX States + one
+Boundary check only. Do not force File Upload tests on a card with no file field, API tests on
+a pure front-end copy change, etc.
+
+---
+
+## §3 — Coverage Dimension Catalog
+
+What each dimension actually means when drafting a test idea:
+
+- **Functional Positive** — valid input/action produces the documented expected result.
+- **Functional Negative** — invalid input, missing mandatory field, unauthorized action, wrong
+  state transition, or a dependency failure (API/network) is handled without a crash and with
+  a correct, user-facing message.
+- **Boundary/Equivalence** — see §6 templates. Values at/around a stated limit, and one
+  representative value per valid/invalid partition — not exhaustive enumeration.
+- **UI/UX States** — see §8. Initial, loading, empty, success, error, disabled states of the
+  components the card actually touches.
+- **Validation** — mandatory/optional fields, character/numeric limits, special characters,
+  whitespace, duplicate values, invalid format, field interdependencies.
+- **Business Rules** — role-based/status-based/date-based behavior, calculations, eligibility
+  and workflow-transition rules stated in the AC.
+- **Authentication** — valid/invalid credentials, empty credentials, OTP flow, session
+  expiry, logout, token expiration.
+- **Authorization / Permissions** — each distinct role named in the AC gets one test for
+  allowed and one for denied behavior; direct-URL/API access with an unauthorized session
+  should not succeed just because the UI hid the button.
+- **API** (only when the card's flow visibly depends on a request) — correct status code for
+  the scenario (200/201/204 success; 400 invalid; 401 unauthenticated; 403 unauthorized; 404
+  not found; 409 conflict/duplicate; 500 server failure), response shape sanity, not full
+  contract testing.
+- **Database** (only when the UI exposes persisted state) — does the value shown after a
+  reload match what was submitted; does a delete actually remove/soft-remove the record;
+  spot-check only, not a DB audit.
+- **Integration** — cross-system handoff visible from the UI (payment gateway redirect,
+  auth-provider callback, file-storage upload) — verify the round trip completes and failures
+  are surfaced, not the integration's internals.
+- **End-to-End** — the full journey named in the card (e.g. Login → create entity → submit →
+  see it reflected downstream), not just the single screen in the AC.
+- **File Upload/Download** — supported/unsupported type, size limit, empty/corrupted file,
+  duplicate filename, correct downloaded filename/contents.
+- **Search/Filter/Sort/Pagination** — exact match, no-match, empty query, filter
+  combination, clear filters, sort direction, first/last page, empty result page.
+- **Notifications** — correct message, correct recipient/trigger, not duplicated, and (if
+  observable within the run) sent after both success and retry-after-failure.
+- **State/Workflow** — every transition named in the AC, one attempt at an invalid transition,
+  and what the UI shows on reopening/refreshing after a transition.
+- **Security-oriented** (only for high-risk signals in §4) — direct URL access while logged
+  out or as the wrong role, sensitive data not exposed in the URL or in error text, password
+  masked, session actually ends on logout.
+- **Accessibility spot-check** — one keyboard-only pass through the card's critical path
+  (tab order reaches every control, focus is visible, no dead-end). This is a lightweight
+  spot-check, not the full WCAG audit — hand off to the `accessibility-testing` skill if the
+  card needs that level of coverage.
+- **Compatibility** — only when the card explicitly calls out a browser/viewport; otherwise
+  out of scope for a single-card manual run (covered separately, not by default here).
+
+---
+
+## §4 — Risk-Based Depth
+
+| Risk tier | Signals (from §2, or explicit in AC) | Depth |
+|---|---|---|
+| **High** | payment, auth/authz, delete, financial calculation, subscription/billing, critical third-party integration, sensitive data | Each triggered dimension gets 2–3 tests; also add Security-oriented and Database checks even if not explicitly triggered by §2 |
+| **Medium** | ordinary business feature, none of the High signals | Each triggered dimension gets 1–2 tests |
+| **Low** | copy/label/minor UI-only change | Functional (positive + one negative) plus one regression spot-check — nothing else |
+
+This tier decides **how many tests to draft per dimension**. It's separate from the
+`risk-score` toolkit call, which orders the **execution sequence** of whatever was drafted, by
+git churn + known-bug density. Run both — they answer different questions.
+
+---
+
+## §5 — Test Scenario Identification Framework
+
+While turning triggered dimensions into numbered T-01, T-02... ideas, walk these 10 questions
+once — they map straight onto §3's dimensions and stop scenario drafting from stalling out at
+"just the AC's happy path":
+
+1. What can the user do? → Functional Positive
+2. What can the user enter? → Validation, Boundary/Equivalence
+3. What can go wrong? → Functional Negative
+4. What are the limits? → Boundary
+5. Who can perform the action? → Authorization/Permissions
+6. What happens to the data? → Database/API
+7. What happens after the action? → End-to-End, Notifications
+8. What happens when the system fails? → Functional Negative (dependency failure)
+9. What existing functionality could break? → flag for qa-agent's post-phase regression
+   suggestion (Covered Flows overlap) — don't draft duplicate regression tests here
+10. What unusual behavior could a real user perform? → at most one exploratory idea, tagged
+    clearly (`[exploratory]`) so it doesn't inflate the planned-test count
+
+---
+
+## §6 — Boundary & Equivalence Quick Templates
+
+If the AC (or the answer to a §1 gap question) states a numeric/length range `[MIN, MAX]`:
+
+- Full set (High-risk fields — payments, quotas, security limits): `MIN-1` (invalid), `MIN`
+  (valid), `MIN+1` (valid), `MAX-1` (valid), `MAX` (valid), `MAX+1` (invalid) — 6 tests.
+- Collapsed set (Medium/Low-risk, wide range): `MIN` (valid), one mid-range value (valid),
+  `MAX` (valid), one just-out-of-range value (invalid) — 4 tests.
+
+Equivalence partitioning (no exact boundary stated, just a described valid category): one
+representative value below the valid range, one within it, one above it — 3 tests, not an
+enumeration of every possible value.
+
+---
+
+## §7 — Defect Record Fields (Phase 4 payload)
+
+Every bug filed from this skill should carry: Title, Environment, Preconditions, Steps to
+Reproduce, Expected Result, Actual Result, Severity, Priority, Screenshot, Test data used, and
+Build/version (the card ID + run date stands in when the product has no separate build
+number). Severity/Priority derivation stays as defined in the skill's Phase 4 table — this
+section only adds the two fields (Preconditions, Test data used) that weren't previously
+captured.
+
+---
+
+## §8 — State Validation Checklist
+
+For each key screen/component the card's test plan actually reaches, note which of these
+states were observed and their result — skip states that are genuinely unreachable within the
+test rather than forcing them:
+
+Initial · Loading · Empty · Success · Error · Disabled
+
+---
+
+## §9 — Exit Criteria Quick Check
+
+Before handing off to Phase 5 (test charter), confirm:
+
+- Every planned test executed — `🔒 BLOCKED` is an acceptable outcome, a silently skipped test
+  is not.
+- No open Critical/Blocker-severity bug among those just filed goes unmentioned — flag it
+  prominently in the final summary. This pack does not gate the pipeline on it (no release
+  authority here), it only makes sure the flag isn't buried.
+- If the product context's `Known Bugs` table (already loaded in Phase 1) lists a bug on this
+  same flow with a status other than Closed/Done, one retest of that specific bug was included
+  in the plan.
+- The regression suggestion in qa-agent Step 5 runs after this skill returns — nothing to do
+  here, just don't skip past it.

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
+```