qualiow-exploratory-testing 1.3.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. package/.claude-plugin/plugin.json +22 -0
  2. package/.env.example +27 -0
  3. package/CHANGELOG.md +194 -0
  4. package/README.md +362 -205
  5. package/agents/qa-gather-agent.md +24 -0
  6. package/{scripts → bin}/doctor-mobile.sh +57 -18
  7. package/bin/mcli +15 -9
  8. package/bin/mobile-cli.mjs +574 -286
  9. package/{scripts → bin}/setup-mobile.sh +56 -19
  10. package/bin/wadb +10 -4
  11. package/bin/wk-ios +29 -17
  12. package/bin/wkeval.mjs +7 -1
  13. package/data/domains/_default.yml +1 -1
  14. package/data/knowledge/changelog.yml +30 -12
  15. package/data/knowledge/manifest.yml +333 -127
  16. package/data/knowledge/releases/v0.1.0/entries/technique-business-logic-race-conditions.yml +1 -1
  17. package/data/knowledge/releases/v0.1.0/release.yml +8 -1
  18. package/data/knowledge/releases/v0.6.0/entries/technique-async-callback-contracts.yml +98 -0
  19. package/data/knowledge/releases/v0.6.0/entries/technique-exactly-once-verification.yml +116 -0
  20. package/data/knowledge/releases/v0.6.0/release.yml +30 -0
  21. package/data/security/SECURITY-POLICY.md +273 -0
  22. package/data/targets/_default.yml +1 -1
  23. package/data/targets/_example-api-only.yml +80 -0
  24. package/data/targets/_example-mobile-emulation.yml +2 -2
  25. package/data/targets/_example-native-mobile.yml +2 -2
  26. package/data/targets/_example-sim-android-chrome.yml +1 -1
  27. package/data/targets/_example-sim-ios-safari.yml +1 -1
  28. package/data/templates/api-probe-matrix.md +3 -3
  29. package/data/templates/bug-report.md +29 -151
  30. package/data/templates/coverage-map.md +9 -6
  31. package/data/templates/expected-behaviour.md +3 -2
  32. package/data/templates/session-charter.md +3 -0
  33. package/data/templates/session-report.md +57 -80
  34. package/dist/cli/index.js +1452 -700
  35. package/dist/index.d.ts +589 -81
  36. package/dist/index.js +1612 -227
  37. package/docs/BACKEND-VERIFICATION.md +39 -9
  38. package/docs/GETTING-STARTED.md +188 -128
  39. package/docs/MOBILE-SETUP.md +149 -18
  40. package/package.json +32 -18
  41. package/skills/qa-explore/SKILL.md +31 -25
  42. package/skills/qa-explore/phases/00-setup.md +67 -41
  43. package/skills/qa-explore/phases/01-auth.md +32 -15
  44. package/skills/qa-explore/phases/02-charter.md +16 -5
  45. package/skills/qa-explore/phases/03-discovery.md +50 -26
  46. package/skills/qa-explore/phases/04-journeys.md +2 -2
  47. package/skills/qa-explore/phases/05-features.md +39 -24
  48. package/skills/qa-explore/phases/06-edge-cases.md +24 -13
  49. package/skills/qa-explore/phases/07-reporting.md +79 -140
  50. package/skills/qa-explore/references/context-integration.md +1 -1
  51. package/skills/qa-explore/references/output-contract.md +187 -0
  52. package/skills/qa-explore/references/paths.md +84 -0
  53. package/skills/qa-explore/references/playwright-agents-integration.md +61 -84
  54. package/skills/qa-explore/references/security-rules.md +66 -25
  55. package/skills/qa-explore/references/severity-guide.md +31 -4
  56. package/skills/qa-explore-cleanup/SKILL.md +17 -6
  57. package/skills/qa-explore-feedback/SKILL.md +18 -5
  58. package/skills/qa-explore-mobile/SKILL.md +86 -64
  59. package/skills/qa-explore-mobile/phases/00-setup.md +71 -62
  60. package/skills/qa-explore-mobile/phases/01-auth.md +28 -31
  61. package/skills/qa-explore-mobile/phases/02-charter.md +8 -4
  62. package/skills/qa-explore-mobile/phases/03-discovery.md +17 -11
  63. package/skills/qa-explore-mobile/phases/04-journeys.md +6 -6
  64. package/skills/qa-explore-mobile/phases/05-features.md +9 -9
  65. package/skills/qa-explore-mobile/phases/06-edge-cases.md +35 -40
  66. package/skills/qa-explore-mobile/phases/07-reporting.md +82 -56
  67. package/skills/qa-explore-mobile/references/mobile-edges.md +26 -26
  68. package/skills/qa-explore-quick/SKILL.md +60 -25
  69. package/skills/qa-explore-report/SKILL.md +40 -34
  70. package/skills/qa-gather/SKILL.md +17 -2
  71. package/skills/qa-knowledge-add/SKILL.md +20 -9
  72. package/skills/qa-knowledge-list/SKILL.md +12 -3
  73. package/skills/qa-target-setup/SKILL.md +63 -41
  74. package/skills/qa-verify-backend/SKILL.md +26 -17
  75. package/skills/qa-verify-backend/phases/00-setup.md +57 -12
  76. package/skills/qa-verify-backend/phases/01-ac-decomposition.md +2 -2
  77. package/skills/qa-verify-backend/phases/03-live-verification.md +3 -3
  78. package/skills/qa-verify-backend/phases/03b-api-verification.md +22 -9
  79. package/skills/qa-verify-backend/phases/04-e2e-trigger.md +18 -2
  80. package/skills/qa-verify-backend/phases/05-reporting.md +38 -10
  81. package/skills/qa-verify-backend/references/api-probes.md +28 -1
  82. package/skills/qa-verify-backend/references/payload-verification.md +1 -1
  83. package/skills/qa-verify-backend/references/release-readiness.md +1 -1
  84. package/skills/qa-verify-backend/references/safety-rules.md +13 -8
  85. package/data/domains/_default.md +0 -181
  86. package/data/domains/ecommerce.md +0 -192
  87. package/data/domains/fintech.md +0 -200
  88. package/data/domains/identity.md +0 -88
  89. package/data/domains/marketing.md +0 -194
  90. package/data/domains/saas.md +0 -197
  91. package/dist/cli/index.d.ts +0 -1
  92. package/dist/cli/index.js.map +0 -1
  93. package/dist/index.js.map +0 -1
@@ -10,7 +10,8 @@ description: >
10
10
  permissions, native a11y tree). Use when user says: "test on the simulator/emulator",
11
11
  "explore the app on iOS/Android", "find bugs on mobile", "QA the mobile build", or provides
12
12
  a mobile-sim target (native or web).
13
- allowed-tools: Bash(node:*), Bash(adb:*), Bash(xcrun:*), Bash(maestro:*), Read, Write, Glob, Grep
13
+ argument-hint: "--target <id> [--context <file>] [--rebuild]"
14
+ allowed-tools: Bash(qa/bin/mcli:*), Bash(bin/mcli:*), Bash(mcli:*), Bash(${CLAUDE_SKILL_DIR}/../../bin/mcli:*), Bash(qa/bin/wadb:*), Bash(bin/wadb:*), Bash(wadb:*), Bash(${CLAUDE_SKILL_DIR}/../../bin/wadb:*), Bash(qa/bin/wk-ios:*), Bash(bin/wk-ios:*), Bash(wk-ios:*), Bash(${CLAUDE_SKILL_DIR}/../../bin/wk-ios:*), Bash(qa/bin/doctor-mobile.sh:*), Bash(bin/doctor-mobile.sh:*), Bash(qualiow-doctor-mobile:*), Bash(${CLAUDE_SKILL_DIR}/../../bin/doctor-mobile.sh:*), Bash(xcrun:*), Bash(adb:*), Bash(maestro:*), Bash(node:*), Bash(sleep:*), Bash(python3:*), Bash(git:*), Read, Write, Glob, Grep
14
15
  ---
15
16
 
16
17
  # Mobile Exploratory Testing Session
@@ -25,88 +26,111 @@ This skill works in **two modes, both co-equal, selected from the target config*
25
26
  `com.android.chrome`) plus a `web.base_url`. The browser is just the driver; the web URL
26
27
  (the app's mobile site, e.g. `https://staging.m.example.com`) is the system under test.
27
28
 
28
- The mindset and reporting standards are identical to `/qa-explore` — what changes is the
29
+ The mindset and reporting standards are identical to `/qa-explore`; what changes is the
29
30
  driver (Maestro via `mobile-cli`) and the failure modes (app/browser lifecycle, on-screen
30
31
  keyboard, rotation, permissions, native a11y tree instead of console/network).
31
32
 
32
- **Mode detection** is done in `phases/00-setup.md`: if the target's `app` id is a known
33
- browser bundle AND a `web.base_url` is present → WEB mode; otherwise (non-browser app id
34
- with installable artifacts) → NATIVE mode. Everything downstream (the snapshot→click→fill
35
- loop, charter, discovery, journeys, features, edges, reporting) is shared and generic; each
36
- phase notes the few places native vs web diverge.
33
+ **Mode detection** is done in `${CLAUDE_SKILL_DIR}/phases/00-setup.md`: if the target's `app`
34
+ id is a known browser bundle AND a `web.base_url` is present → WEB mode; otherwise
35
+ (non-browser app id with installable artifacts) → NATIVE mode. Everything downstream (the
36
+ snapshot→click→fill loop, charter, discovery, journeys, features, edges, reporting) is
37
+ shared and generic; each phase notes the few places native vs web diverge.
37
38
 
38
39
  Why Maestro/`mobile-cli` instead of Playwright? Playwright **cannot** drive a native app at
39
40
  all, and it **cannot** drive iOS Simulator Safari (its "webkit" is desktop macOS WebKit, not
40
41
  the simulator's engine). The Maestro/simctl/adb route used by `mobile-cli` is the only way to
41
42
  exercise either a real native app or the genuine mobile-browser engine.
42
43
 
44
+ ## Rules that apply as-is
45
+
46
+ - `${CLAUDE_SKILL_DIR}/../qa-explore/references/paths.md` — target, data, credential and **driver** resolution; session-directory scheme; index rows
47
+ - `${CLAUDE_SKILL_DIR}/../qa-explore/references/output-contract.md` — bug-report, session-report and `stats.json` format
48
+ - `${CLAUDE_SKILL_DIR}/../qa-explore/references/security-rules.md` — production rule (applied to `web.base_url` or the environment in the target), redaction, confidentiality header
49
+ - `${CLAUDE_SKILL_DIR}/../qa-explore/references/severity-guide.md`, `session-rules.md` — the 45-min cap matters even more on mobile because emulator/sim latency adds up
50
+
43
51
  ## The Driver — mobile-cli
44
52
 
45
53
  A single shim wraps Maestro and `adb` / `xcrun simctl` to present a playwright-cli–shaped
46
- command surface. Call it through the `bin/mcli` wrapper (it sets `JAVA_HOME` / `ANDROID_HOME`
47
- / `PATH` for you, so you don't need an export block):
54
+ command surface. Resolve it **once, in phase 0**, in the order from `paths.md`
55
+ (`qa/bin/mcli` after `qualiow init` → `bin/mcli` in a checkout of this repository → `mcli`
56
+ on PATH for global or marketplace installs → the plugin's `bin/`), then write that literal
57
+ prefix in every command. **The phase files show `qa/bin/mcli`; substitute yours.** Never
58
+ call it through a shell variable: permission rules match the first literal token.
59
+
60
+ The wrapper sets `JAVA_HOME` / `ANDROID_HOME` / `PATH` for you. Device and app state live in
61
+ a **per-device** state file chosen at `set-device` (`~/.mobile-cli/<device>.json`). Two
62
+ sessions driving the *same* device share that file and will overwrite each other's refs and
63
+ app id, so give each concurrent session its own `--state <file>` on every command. Raw adb
64
+ goes through the `qa/bin/wadb` wrapper.
48
65
 
49
66
  ```bash
50
- # Isolate this session's device/app state so you don't clobber another target's state.
51
- export MOBILE_CLI_STATE=/tmp/<target>-state.json
52
- MCLI="$PWD/bin/mcli" # run from the repo root
53
- # Then:
54
- $MCLI snapshot
55
- $MCLI click e7
56
- $MCLI fill e9 "user@example.com"
57
- # For raw adb (logcat, am start, pm) that mcli doesn't wrap, use the bin/wadb wrapper.
67
+ qa/bin/mcli set-device emulator-5554 --platform android # or a sim UDID / name with --platform ios
68
+ qa/bin/mcli set-app com.example.app
69
+ qa/bin/mcli launch
70
+ qa/bin/mcli snapshot
71
+ qa/bin/mcli click e7
72
+ qa/bin/mcli fill e9 "user@example.com"
58
73
  ```
59
74
 
60
75
  Command surface (mirrors playwright-cli where it makes sense):
61
76
 
62
77
  | Command | Purpose |
63
78
  |---|---|
64
- | `set-device <udid>` | `emulator-5554` for Android, iOS sim UDID for iOS — sets platform |
79
+ | `set-device <id> [--platform ios\|android]` | `emulator-5554` / an adb serial for Android; a sim UDID or name for iOS (names resolve to a UDID). Auto-detects the platform from `adb devices` / `simctl list`; pass `--platform` when in doubt. |
65
80
  | `set-app <id>` | NATIVE: the app's bundle id / package. WEB: the browser bundle `com.apple.mobilesafari` / `com.android.chrome`. |
66
- | `launch` / `stop` / `relaunch-clean` | App/browser lifecycle. `relaunch-clean` is Android-only (force-stop + pm clear) — fine for a cold native start, but **avoid it in WEB mode, it wipes the logged-in browser profile.** |
81
+ | `boot <avd\|sim-name\|udid>` | Boot an emulator / simulator. iOS: safe to re-run against an already-booted sim. Android: always spawns a NEW emulator process — run it only when no device is attached, or it blocks 180 s and then fails. |
82
+ | `info` / `version` / `running` | Current device/app state; driver version; the foreground app. |
83
+ | `launch` / `stop` / `relaunch-clean` | App/browser lifecycle. `relaunch-clean` is Android-only (force-stop + pm clear + launch): fine for a cold native start, but **avoid it in WEB mode, it wipes the logged-in browser profile.** |
67
84
  | `open-url <url>` / `deep-link <url>` | `simctl openurl` / `am start -a VIEW -d`. WEB mode: your "address bar" to load `base_url`. NATIVE mode: fire the app's deep links. |
68
- | `snapshot [--full]` | Parses Maestro's a11y hierarchy, assigns refs `e1…eN`, prints a tree. In WEB mode the browser chrome (URL bar, tabs, toolbar, keyboard) is auto-filtered. `--full` includes non-interactive nodes. KNOWN QUIRK (Android Chrome): after keyboard show/dismiss the a11y export can go stale — the WebView shows as one empty "Web View" group. Recover with `screenshot` + a coordinate tap (`bin/wadb shell input tap <x> <y>`), or `open-url` the page again to refresh the tree. |
69
- | `click <ref>` | Tap by ref. Uses `adb input tap x y` on Android, `maestro tap --point` on iOS. |
70
- | `fill <ref> <text>` | Tap then `adb input text` / `maestro input`. Appends to existing text — `clear` first if the field is pre-filled. Filling opens the on-screen keyboard, which SHIFTS the layout — refs cached before the keyboard are stale afterwards. Always re-`snapshot` after the last `fill` before clicking a submit control (and `press BACK` on Android first to dismiss the keyboard — with the keyboard closed BACK becomes page-back/history, so only use it while the keyboard is up). |
71
- | `clear <ref>` | Tap then erase the field's existing text (Maestro `eraseText`). |
72
- | `press <BACK\|ENTER\|HOME\|TAB\|ESCAPE>` | Android keyevents. iOS supports ENTER + HOME (via Maestro `pressKey`); iOS has no hardware BACK — use an in-app/on-page back control via snapshot. |
73
- | `screenshot <path>` | Save PNG. |
74
- | `logs [--since <sec>] [--errors]` | logcat tail (Android) / `simctl spawn log show` (iOS), filtered to the app/browser process. Replaces playwright-cli `console error`. In WEB mode it is the BROWSER's process log, not the page's JS console. |
75
- | `record-start <path>` / `record-stop` | Video. Replaces playwright-cli tracing. |
76
- | `running` | Foreground app — sanity check the app/browser is frontmost. |
77
-
78
- ### Safari DOM bridge — `bin/wk-ios` (iOS WEB mode only)
79
-
80
- For iOS Safari web targets, `bin/wk-ios` restores real JS/DOM access via WebKit Remote
81
- Inspector (through `ios-webkit-debug-proxy`, installed by `scripts/setup-mobile.sh`):
85
+ | `snapshot [--full]` | Parses Maestro's a11y hierarchy, assigns refs `e1…eN` to on-screen elements, prints a tree. In WEB mode the browser chrome (URL bar, tabs, toolbar, keyboard) is auto-filtered. `--full` includes non-interactive nodes. Refs expire after 60 s (`click` refuses a stale ref; re-snapshot). KNOWN QUIRK (Android Chrome): after keyboard show/dismiss the a11y export can go stale (the WebView shows as one empty "Web View" group). Recover with `screenshot` + a coordinate tap (`qa/bin/wadb shell input tap <x> <y>`), or `open-url` the page again. |
86
+ | `click <ref>` | Tap by ref: Android `adb input tap x y`; iOS a Maestro `tapOn: point` flow. |
87
+ | `tap-id <testID>` | Tap by accessibility/test id directly (no snapshot needed). |
88
+ | `fill <ref> <text>` | Tap, then type through a Maestro `inputText` flow on both platforms (avoids per-character re-renders). Appends to existing text; `clear` first if the field is pre-filled. Typing opens the on-screen keyboard, which SHIFTS the layout, so refs cached before the keyboard are stale afterwards: always re-`snapshot` after the last `fill` before tapping a submit control (and `press BACK` on Android first to dismiss the keyboard; with the keyboard closed BACK becomes page-back, so only use it while the keyboard is up). |
89
+ | `fill-id <testID> <text>` | Tap by id + type in one Maestro flow (fastest combination). |
90
+ | `clear <ref>` | Tap, then erase the field's existing text (Maestro `eraseText`, **up to 200 characters** — snapshot to confirm on longer values). |
91
+ | `wait-text <substring> [timeout-sec]` | Poll the hierarchy until text appears (default 10 s). Use it instead of `sleep` after navigation. |
92
+ | `press <BACK\|ENTER\|HOME\|TAB\|ESCAPE>` | Android keyevents. iOS supports ENTER and HOME (Maestro `pressKey`); iOS has no hardware BACK: use an in-app back control via snapshot. |
93
+ | `screenshot <path>` | Save a PNG. |
94
+ | `logs [--since <sec>] [--errors]` / `logs-clear` | logcat tail (Android) / `simctl spawn log show` (iOS). **iOS is scoped to the app/browser process; Android is the whole-device logcat** at `*:E` (`--errors`) or `*:W`, last 400 lines — other packages' lines appear, so correlate by tag/pid before blaming the app. Replaces playwright-cli `console error`. In WEB mode it is the BROWSER's process log, not the page's JS console. |
95
+ | `record-start <path.mp4>` / `record-stop` | Video (a real `.mp4` on both platforms). **Android caps one recording at 180 s** (`screenrecord --time-limit 180`) and drops everything after it, silently — restart it per journey rather than recording the whole session; iOS has no cap. Replaces playwright-cli tracing. |
96
+
97
+ Exit codes: `0` ok · `1` the device command failed · `2` usage · `3` stale or unknown ref
98
+ (re-snapshot) · `4` no device or app set. Treat anything non-zero as "the action did not
99
+ happen"; never assume a tap landed.
100
+
101
+ ### Safari DOM bridge — `qa/bin/wk-ios` (iOS WEB mode only)
102
+
103
+ For iOS Safari web targets, `qa/bin/wk-ios` restores real JS/DOM access via WebKit Remote
104
+ Inspector (through `ios-webkit-debug-proxy`, installed by `qa/bin/setup-mobile.sh`; needs
105
+ `python3` and Node ≥ 22.4, which `doctor-mobile.sh` checks):
82
106
 
83
107
  ```bash
84
- bin/wk-ios 'document.title' # eval any JS in the sim's Safari page
85
- bin/wk-ios 'document.querySelectorAll(".cart_item").length' # exact-DOM assertions
86
- bin/wk-ios --url # print the page's WebSocket debugger URL
87
- bin/wk-ios --stop # stop the background proxy when the session ends
108
+ qa/bin/wk-ios 'document.title' # eval any JS in the sim's Safari page
109
+ qa/bin/wk-ios 'document.querySelectorAll(".cart_item").length' # exact-DOM assertions
110
+ qa/bin/wk-ios --url # print the page's WebSocket debugger URL
111
+ qa/bin/wk-ios --stop # stop the background proxy when the session ends
88
112
  ```
89
113
 
90
114
  Use it whenever the a11y snapshot is not enough: exact-DOM verification (counts, attribute
91
115
  values, hidden state), reading values the a11y tree collapses, or checking a suspected
92
116
  rendering/JS failure. It is the same power as `playwright-cli eval`, but on the REAL iOS
93
117
  engine. Requirements: a booted simulator with Safari on a page (`open-url` first). There is
94
- no Android equivalent wired up in v1 — on Android, drive by a11y refs and `logs`.
118
+ no Android equivalent; on Android, drive by a11y refs and `logs`.
95
119
 
96
120
  ## What's Dropped vs Playwright
97
121
 
98
- Both modes are driven through the device **accessibility tree, not a DOM** — native views and
122
+ Both modes are driven through the device **accessibility tree, not a DOM**: native views and
99
123
  web content alike are surfaced to a11y (headings, links, buttons, inputs and visible text
100
124
  become tappable refs). Versus Playwright you LOSE, in BOTH modes:
101
125
 
102
- - **CSS / DOM selectors** — you drive purely by visible/accessible labels and tap coordinates (native has no DOM at all; WEB mode has one but `snapshot` doesn't read it). EXCEPTION: iOS Safari web targets can READ the DOM via `bin/wk-ios` (see above) — driving/tapping still goes through refs.
103
- - **eval / JS injection** — no script context on native or Android Chrome. EXCEPTION: iOS Safari web targets get full JS eval via `bin/wk-ios`.
104
- - **console & network introspection** — `logs` is the app/browser process log, not a page console; there is no network panel. (iOS WEB: `bin/wk-ios` can read `window`-level state, but there is still no console/network history.)
105
- - **route / network mocking** — would need mitmproxy. Out of scope for v1; flag in the report if a test required it.
106
- - **state-save / state-load (storage_state)** — no transferable cookie jar. Auth happens on the device (NATIVE: in-app login/signup; WEB: a one-time interactive login the browser profile persists — see Phase 1).
107
- - **resize** — sim viewport is fixed. Use rotation instead.
108
- - **multi-session race conditions** — would need two emulators. Defer to a future enhancement.
109
- - **XSS payload assertions (WEB)** — without DOM/console you can't reliably confirm execution; you can still observe gross misbehavior (crash, broken render). Generic input edges (long strings, emoji, paste, RTL, control chars) still apply in both modes.
126
+ - **CSS / DOM selectors** — you drive purely by visible/accessible labels and tap coordinates (native has no DOM at all; WEB mode has one but `snapshot` doesn't read it). EXCEPTION: iOS Safari web targets can READ the DOM via `qa/bin/wk-ios`; driving/tapping still goes through refs.
127
+ - **eval / JS injection** — no script context on native or Android Chrome. EXCEPTION: iOS Safari web targets get full JS eval via `qa/bin/wk-ios`.
128
+ - **console & network introspection** — `logs` is the app/browser process log, not a page console; there is no network panel. (iOS WEB: `qa/bin/wk-ios` can read `window`-level state, but there is still no console/network history.)
129
+ - **route / network mocking** — would need mitmproxy. Out of scope; flag in the report if a test required it.
130
+ - **state-save / state-load (storage_state)** — no transferable cookie jar. Auth happens on the device (NATIVE: in-app login/signup; WEB: a one-time interactive login the browser profile persists; see Phase 1).
131
+ - **resize** — the sim viewport is fixed. Use rotation instead.
132
+ - **multi-session race conditions** — would need two emulators. Deferred.
133
+ - **XSS payload assertions (WEB)** — without DOM/console you can't reliably confirm execution; you can still observe gross misbehaviour (crash, broken render). Generic input edges (long strings, emoji, paste, RTL, control chars) still apply in both modes.
110
134
 
111
135
  ## Mobile-Specific Heuristics (added on top of FEW HICCUPPS / SFDIPOT)
112
136
 
@@ -116,31 +140,29 @@ both modes; mode-specific ones are tagged):
116
140
  - **Lifecycle:** background the app/browser → foreground after 10 min, kill → relaunch, OS-initiated suspend mid-flow. Does state survive? Is the session still valid? (WEB: does the page reload and lose input?)
117
141
  - **Permissions (mostly NATIVE):** deny camera / notifications / contacts / location / biometrics on first prompt; revoke and re-grant. In WEB mode this surfaces as the browser's permission prompts (getUserMedia, geolocation, notifications).
118
142
  - **Connectivity:** airplane mode mid-action, slow 3G, captive-portal Wi-Fi, IPv6-only.
119
- - **Hardware / display:** rotation, dark mode, dynamic type / large font, low-battery (≤15%), on-screen keyboard show/hide jank and input occlusion.
143
+ - **Hardware / display:** rotation, dark mode, dynamic type / large font, low battery (≤15%), on-screen keyboard show/hide jank and input occlusion.
120
144
  - **Deep links / URLs:** legitimate inbound link/intent, malformed scheme or query, foreign-app intent injection, very long URL.
121
- - **Native a11y:** VoiceOver/TalkBack focus order, contrast, dynamic type, RTL layout — driven through the device a11y tree.
122
- - **Storage / profile:** NATIVE — fresh install vs upgrade, force-clear app data mid-flow; WEB — fresh profile vs returning profile, cleared cookies, first-run interstitials.
145
+ - **Native a11y:** VoiceOver/TalkBack focus order, contrast, dynamic type, RTL layout, driven through the device a11y tree.
146
+ - **Storage / profile:** NATIVE: fresh install vs upgrade, force-clear app data mid-flow; WEB: fresh profile vs returning profile, cleared cookies, first-run interstitials.
123
147
 
124
148
  ## Session Phases
125
149
 
126
150
  Execute each phase in order. Each phase doc points at the platform-agnostic guidance in
127
- `../qa-explore/phases/` and lists the mobile-specific replacements/additions.
151
+ `${CLAUDE_SKILL_DIR}/../qa-explore/phases/` and lists the mobile-specific replacements/additions.
128
152
 
129
153
  | Phase | File | Summary |
130
154
  |-------|------|---------|
131
- | **Setup** | `phases/00-setup.md` | Resolve target + **detect mode**, boot sim; NATIVE: verify/install/launch the app; WEB: set browser, open base_url; init session dir |
132
- | **Auth** | `phases/01-auth.md` | NATIVE: in-app login/signup (static OTP from config on staging). WEB: one-time interactive SSO/MFA the profile persists — never automate MFA |
133
- | **Charter** | `phases/02-charter.md` | Business context + journeys + risk ranking + heuristic selection |
134
- | **Discovery** | `phases/03-discovery.md` | Map screens/views (not raw DOM); app/browser logs instead of console; flag a11y aggregation (iOS) |
135
- | **Journeys** | `phases/04-journeys.md` | E2E user journeys with data verification across views |
136
- | **Features** | `phases/05-features.md` | Deep feature testing — same SFDIPOT, no eval-based tampering |
137
- | **Edge Cases** | `phases/06-edge-cases.md` | Mobile edges: lifecycle, permissions, rotation, keyboard, deep links, offline (mode-tagged) |
138
- | **Reporting** | `phases/07-reporting.md` | Same report format. Use video instead of trace. |
155
+ | **Setup** | `${CLAUDE_SKILL_DIR}/phases/00-setup.md` | Preflight, resolve target + driver + **detect mode**, boot sim; NATIVE: verify/install/launch the app; WEB: set browser, open base_url; init session dir |
156
+ | **Auth** | `${CLAUDE_SKILL_DIR}/phases/01-auth.md` | NATIVE: in-app login/signup (static OTP from config on staging). WEB: one-time interactive SSO/MFA the profile persists; never automate MFA |
157
+ | **Charter** | `${CLAUDE_SKILL_DIR}/phases/02-charter.md` | Business context + journeys + risk ranking + heuristic selection; start recording |
158
+ | **Discovery** | `${CLAUDE_SKILL_DIR}/phases/03-discovery.md` | Map screens/views (not raw DOM); app/browser logs instead of console; flag a11y aggregation (iOS) |
159
+ | **Journeys** | `${CLAUDE_SKILL_DIR}/phases/04-journeys.md` | E2E user journeys with data verification across views |
160
+ | **Features** | `${CLAUDE_SKILL_DIR}/phases/05-features.md` | Deep feature testing: same SFDIPOT, no eval-based tampering |
161
+ | **Edge Cases** | `${CLAUDE_SKILL_DIR}/phases/06-edge-cases.md` | Mobile edges: lifecycle, permissions, rotation, keyboard, deep links, offline (mode-tagged) |
162
+ | **Reporting** | `${CLAUDE_SKILL_DIR}/phases/07-reporting.md` | Same report format. Video instead of trace. |
139
163
 
140
164
  ## References
141
165
 
142
- - `references/mobile-edges.md` — checklist of mobile-only edge cases, tagged by mode (rotation, keyboard, deep links, offline, permissions, biometrics, a11y).
143
- - Content is matched by **visible text / accessibility labels** from `snapshot` (and tap coordinates when a11y aggregates nodes). There is no fixed selector/testID catalog — read the live snapshot tree each time.
144
- - `../qa-explore/references/security-rules.md` — applies as-is.
145
- - `../qa-explore/references/severity-guide.md` — applies as-is.
146
- - `../qa-explore/references/session-rules.md` — applies as-is (the 45-min cap matters even more on mobile because emulator/sim latency adds up).
166
+ - `${CLAUDE_SKILL_DIR}/references/mobile-edges.md` — checklist of mobile-only edge cases, tagged by mode (rotation, keyboard, deep links, offline, permissions, biometrics, a11y).
167
+ - Content is matched by **visible text / accessibility labels** from `snapshot` (and tap coordinates when a11y aggregates nodes). There is no fixed selector/testID catalog; read the live snapshot tree each time.
168
+ - `${CLAUDE_SKILL_DIR}/../qa-explore/references/security-rules.md`, `severity-guide.md`, `session-rules.md`, `paths.md`, `output-contract.md` — apply as-is.
@@ -1,79 +1,83 @@
1
1
  # Phase 0: Mobile Session Setup (mode-aware)
2
2
 
3
- Follow `../../qa-explore/phases/00-setup.md` for the general structure (parse input, load
4
- context, load knowledge, create session dir, init progress.json). The mobile differences,
5
- and the native-vs-web branch, are below.
3
+ Follow `${CLAUDE_SKILL_DIR}/../qa-explore/phases/00-setup.md` for the general structure (parse
4
+ input, load context, load knowledge, create the session dir, init progress.json). The mobile
5
+ differences, and the native-vs-web branch, are below. There is no playwright-cli session and
6
+ therefore no `-s=<sid>` on mobile.
6
7
 
7
- ## Step 0 — Preflight (fail fast on a fresh machine)
8
+ ## Step 0 — Resolve the driver, then preflight (fail fast on a fresh machine)
8
9
 
9
- Before anything else, verify the toolchain exists — the mobile path needs Maestro plus the
10
- iOS and/or Android SDKs, which are NOT installed by default and are easy to assume present:
10
+ Resolve the driver prefix once, in the order from
11
+ `${CLAUDE_SKILL_DIR}/../qa-explore/references/paths.md`: `qa/bin/mcli` (after `qualiow init`)
12
+ → `bin/mcli` (a checkout of this repository) → `mcli` on PATH → the plugin's `bin/mcli`.
13
+ Write that literal prefix in every command for the rest of the session. **This and every
14
+ other phase file show `qa/bin/mcli` and `qa/bin/wadb`; substitute yours.**
15
+
16
+ Then verify the toolchain exists (Maestro plus the iOS and/or Android SDKs, which are NOT
17
+ installed by default and are easy to assume present):
11
18
 
12
19
  ```bash
13
- scripts/doctor-mobile.sh # or --ios / --android to scope to one platform
20
+ qa/bin/doctor-mobile.sh # or --ios / --android to scope to one platform
14
21
  ```
15
22
 
16
23
  If it prints **NOT READY**, STOP: surface the `✗` items to the user and point them at
17
- `scripts/setup-mobile.sh` (auto-installs the scriptable prerequisites; Xcode + the iOS
18
- runtime are guided-manual). Do NOT start a session on a half-provisioned machine — a missing
19
- `adb` / `maestro` / runtime fails cryptically deep in the run. Full guide: `docs/MOBILE-SETUP.md`.
24
+ `qa/bin/setup-mobile.sh` (same prefix you resolved above; auto-installs the scriptable prerequisites; Xcode + the iOS runtime
25
+ are guided-manual). Do NOT start a session on a half-provisioned machine; a missing `adb` /
26
+ `maestro` / runtime fails cryptically deep in the run. Full guide: `docs/MOBILE-SETUP.md`.
20
27
 
21
28
  ## Step 1 — Parse target + DETECT MODE
22
29
 
23
- From the user message or the target config in `data/targets/`, extract:
30
+ Resolve the target as `paths.md` says (`--target <id>` → `data/targets/<id>.yml`; no
31
+ `--target` → `qa/target.yml`), then extract:
24
32
 
25
33
  - **platform**: `android` | `ios` (required).
26
34
  - **device**: emulator/sim identifier.
27
35
  - Android: AVD name (from `device.avd`) or `emulator-5554` if already booted.
28
- - iOS: simulator name (e.g. `iPhone 17`) or UDID.
36
+ - iOS: simulator name (e.g. `qa-iphone`) or UDID (`device.name` / `device.udid`).
29
37
  - **app id**: `app.bundle_id` (iOS) / `app.package` (Android).
30
- - **mode** — derive it:
38
+ - **mode**, derived:
31
39
  - **WEB mode** if the app id is a known browser bundle (`com.apple.mobilesafari` /
32
40
  `com.android.chrome`) AND the config has a `web.base_url`. The browser is the driver; the
33
41
  web URL is the SUT. Templates: `data/targets/_example-sim-ios-safari.yml`,
34
- `data/targets/_example-sim-android-chrome.yml` (read the matching one — their `notes:`
42
+ `data/targets/_example-sim-android-chrome.yml` (read the matching one; their `notes:`
35
43
  blocks document the web setup).
36
- - **NATIVE mode** otherwise — i.e. a non-browser app id with installable artifacts
44
+ - **NATIVE mode** otherwise: a non-browser app id with installable artifacts
37
45
  (`app.app_paths` / `app.apk_paths`), optionally a `source_repo` with `build_commands`.
38
46
  The installed app is the SUT. Template: `data/targets/_example-native-mobile.yml`.
39
47
  - **WEB only**: `web.base_url` / `web.start_url`.
40
48
  - **NATIVE only**: `app.app_paths`/`apk_paths` (artifact to verify/install), and optional
41
49
  `source_repo.path` + `source_repo.build_commands`.
42
50
 
43
- Record `mode` — every later step branches on it.
51
+ Record `mode`; every later step branches on it. Apply the **production rule** from
52
+ `security-rules.md` to `web.base_url` (WEB) or to the target's `environment`/`notes` (NATIVE)
53
+ and carry read-only mode through the session if it fires.
44
54
 
45
55
  ## Step 2 — Boot the simulator/emulator if needed (shared)
46
56
 
47
57
  ```bash
48
58
  # Android — check first, only boot if no device attached
49
- bin/wadb devices
50
- # If empty:
51
- # export ANDROID_HOME=$HOME/Library/Android/sdk
52
- # export PATH=$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH
53
- # nohup emulator -avd <avd-name> -no-snapshot -no-boot-anim -memory 4096 -gpu auto & disown
54
- # adb wait-for-device
59
+ qa/bin/wadb devices
60
+ qa/bin/mcli boot <avd-name> # ONLY if the line above listed no device
55
61
 
56
62
  # iOS — check first, only boot if no sim booted
57
63
  xcrun simctl list devices booted
58
- # If empty:
59
- # xcrun simctl boot <UDID-or-name>
60
- # open -a Simulator
64
+ qa/bin/mcli boot <sim-name-or-UDID> # boots and opens Simulator.app
61
65
  ```
62
66
 
63
- **Do NOT reboot a sim/emulator that's already running** — preserve installed apps and (WEB
64
- mode) the persisted browser profile that holds the logged-in session.
67
+ **Do NOT reboot a sim/emulator that's already running**: preserve installed apps and (WEB
68
+ mode) the persisted browser profile that holds the logged-in session. On iOS `boot` is safe
69
+ to re-run (an already-booted sim is accepted); on **Android it always spawns a NEW emulator
70
+ process** and, if that AVD is already up, blocks for 180 s and then fails. Check first.
65
71
 
66
- Set the driver state for the rest of the phase:
72
+ Point the driver at the device (this also picks a **per-device** state file,
73
+ `~/.mobile-cli/<device>.json`). If another session is driving the same device, pass your own
74
+ `--state <file>` on every command or the two will overwrite each other's refs:
67
75
 
68
76
  ```bash
69
- export MOBILE_CLI_STATE=/tmp/<target>-state.json # isolate this session's device/app state
70
- MCLI="$PWD/bin/mcli" # run from the repo root
71
- $MCLI set-device <emulator-5554 OR ios-udid>
77
+ qa/bin/mcli set-device <emulator-5554 | ios sim name or UDID> --platform <android|ios>
78
+ qa/bin/mcli info
72
79
  ```
73
80
 
74
- Use a dedicated `MOBILE_CLI_STATE` file per target so concurrent/sequential sessions don't
75
- clobber each other's device/app state.
76
-
77
81
  ---
78
82
 
79
83
  ## Step 3 — NATIVE branch: verify / install / (optional rebuild) / launch
@@ -84,7 +88,7 @@ Skip this whole step in WEB mode.
84
88
 
85
89
  ```bash
86
90
  # Android
87
- bin/wadb shell pm list packages | grep <app.package>
91
+ qa/bin/wadb shell pm list packages | grep <app.package>
88
92
  # iOS
89
93
  xcrun simctl get_app_container <udid> <app.bundle_id> 2>/dev/null
90
94
  ```
@@ -92,7 +96,7 @@ xcrun simctl get_app_container <udid> <app.bundle_id> 2>/dev/null
92
96
  ### 3b. Install if missing
93
97
 
94
98
  If not installed and the config provides an artifact path, install from it:
95
- - Android: `bin/wadb install -r <app.apk_paths[...]>`
99
+ - Android: `qa/bin/wadb install -r <app.apk_paths[...]>`
96
100
  - iOS: `xcrun simctl install <udid> <app.app_paths[...]>`
97
101
 
98
102
  If not installed and no artifact path is configured, **stop and ask the user** how to obtain
@@ -103,13 +107,12 @@ build command.
103
107
 
104
108
  **Skip unless the user passed `--rebuild` OR the session goal explicitly mentions "latest" /
105
109
  "fresh" / "newest" build.** Otherwise run against whatever is installed (faster, preserves
106
- state). This skill does **not** assume any build framework — it runs the EXACT commands the
110
+ state). This skill does **not** assume any build framework; it runs the EXACT commands the
107
111
  target config provides:
108
112
 
109
113
  ```bash
110
114
  # 1. Drift check (using the target's source_repo.build_commands.refresh, if defined)
111
- cd <source_repo.path>
112
- git status -sb && git fetch && git log HEAD..@{u} --oneline
115
+ git -C <source_repo.path> status -sb && git -C <source_repo.path> fetch && git -C <source_repo.path> log HEAD..@{u} --oneline
113
116
 
114
117
  # 2. Decide WITH the user before pulling:
115
118
  # clean + behind → safe to pull then rebuild; dirty → ask (stash/commit/build-as-is);
@@ -117,12 +120,10 @@ git status -sb && git fetch && git log HEAD..@{u} --oneline
117
120
 
118
121
  # 3. Run the platform build command verbatim from source_repo.build_commands
119
122
  # (e.g. build_commands.android_release / build_commands.ios_debug). These are
120
- # project-defined; the skill does not hardcode them. Long builds: run in the
121
- # background and PID-wait so you get notified on completion:
122
- # nohup <the configured build command> > /tmp/mobile-build.log 2>&1 &
123
- # BUILD_PID=$!; until ! kill -0 $BUILD_PID 2>/dev/null; do sleep 15; done
123
+ # project-defined; the skill does not hardcode them. Run long builds in the
124
+ # background and wait for completion before installing.
124
125
 
125
- # 4. After install, cold-start fresh: $MCLI relaunch-clean (Android) or stop+launch (iOS)
126
+ # 4. After install, cold-start fresh: qa/bin/mcli relaunch-clean (Android) or stop + launch (iOS)
126
127
  ```
127
128
 
128
129
  **Always log the source state in the report** (branch + sha + clean/dirty) so readers know
@@ -131,9 +132,9 @@ what code the session ran against.
131
132
  ### 3d. Launch the app
132
133
 
133
134
  ```bash
134
- $MCLI set-app <app.bundle_id OR app.package>
135
- $MCLI launch
136
- $MCLI snapshot # sanity check — first screen renders
135
+ qa/bin/mcli set-app <app.bundle_id OR app.package>
136
+ qa/bin/mcli launch
137
+ qa/bin/mcli snapshot # sanity check — first screen renders
137
138
  ```
138
139
 
139
140
  ---
@@ -143,23 +144,24 @@ $MCLI snapshot # sanity check — first scre
143
144
  Skip this step in NATIVE mode.
144
145
 
145
146
  On Android, confirm the browser exists first (Safari ships with every iOS runtime; Chrome is
146
- only guaranteed on **Google-APIs/Play** images — stock AOSP images may lack it):
147
+ only guaranteed on **Google-APIs/Play** images; stock AOSP images may lack it):
147
148
 
148
149
  ```bash
149
- bin/wadb shell pm list packages | grep chrome # expect: package:com.android.chrome
150
+ qa/bin/wadb shell pm list packages | grep chrome # expect: package:com.android.chrome
150
151
  ```
151
152
 
152
153
  If `com.android.chrome` is absent, use a Play-image AVD (or fall back to the iOS Safari
153
154
  target) rather than assuming Chrome is installed. Do not attempt to install a browser.
154
155
 
155
156
  ```bash
156
- $MCLI set-app <com.apple.mobilesafari OR com.android.chrome>
157
- $MCLI launch
158
- $MCLI open-url <web.base_url or web.start_url>
159
- $MCLI snapshot # sanity check — the page renders
157
+ qa/bin/mcli set-app <com.apple.mobilesafari OR com.android.chrome>
158
+ qa/bin/mcli launch
159
+ qa/bin/mcli open-url <web.base_url or web.start_url>
160
+ qa/bin/mcli wait-text "<a word from the landing page>" 15
161
+ qa/bin/mcli snapshot # sanity check — the page renders
160
162
  ```
161
163
 
162
- On a fresh Chrome profile you may see a one-time first-run / "Open tabs" promo bubble —
164
+ On a fresh Chrome profile you may see a one-time first-run / "Open tabs" promo bubble;
163
165
  `mobile-cli` filters the routine promo out of snapshots, but if a full-screen
164
166
  first-run/sign-in-to-Chrome interstitial appears, it must be dismissed once by hand.
165
167
 
@@ -167,20 +169,27 @@ first-run/sign-in-to-Chrome interstitial appears, it must be dismissed once by h
167
169
 
168
170
  ## Step 5 — Session directory (shared)
169
171
 
170
- Same as qa-explore but include `platform` in the dir name:
172
+ Per the scheme in `paths.md`, with the platform in the slug:
171
173
 
172
174
  ```
173
- output/sessions/<YYYY-MM-DD-HHmm>-<target>-<platform>/
175
+ output/sessions/<YYYY-MM-DD-HHmm>-mobile-<target>-<android|ios>/
174
176
  charter.md
175
177
  session-log.md
178
+ progress.json
176
179
  screenshots/
177
180
  bugs/
178
- videos/ # mobile-only — for record-start output
181
+ videos/ # record-start output (.mp4)
182
+ logs/ # process-log excerpts per bug (logs/BUG-NNN.log)
179
183
  ```
180
184
 
185
+ Create all four subdirectories now — `screenshots/`, `bugs/`, `videos/` **and `logs/`**.
186
+ Phase 7 redirects log output into `logs/` with `>`, which fails outright if the directory
187
+ does not exist.
188
+
181
189
  ## Step 6 — progress.json additions (shared)
182
190
 
183
- Same base schema as qa-explore. Add a `platform` key including the resolved `mode`:
191
+ Same base schema as qa-explore with `"kind": "mobile"`. Add a `platform` key including the
192
+ resolved `mode`:
184
193
 
185
194
  ```json
186
195
  "platform": {
@@ -188,16 +197,16 @@ Same base schema as qa-explore. Add a `platform` key including the resolved `mod
188
197
  "os": "android",
189
198
  "device": "emulator-5554",
190
199
  "app_id": "com.example.myapp",
191
- "app_version": "<from `adb shell dumpsys package <pkg> | grep versionName`>",
200
+ "app_version": "<from `qa/bin/wadb shell dumpsys package <pkg> | grep versionName`>",
192
201
  "target_url": null
193
202
  }
194
203
  ```
195
204
 
196
205
  For WEB mode, set `"mode": "web"`, `app_id` to the browser bundle, and `target_url` to the
197
- `base_url` (leave `app_version` null — it's the browser's, not the SUT's).
206
+ `base_url` (leave `app_version` null; it's the browser's, not the SUT's).
198
207
 
199
208
  The `console_errors` counter from qa-explore becomes `app_log_errors` (app/browser-process
200
- ERROR-level log matches — coarser than a real JS console, see Phase 3).
209
+ ERROR-level log matches; coarser than a real JS console, see Phase 3).
201
210
 
202
- **Skip qa-explore's Step 6 (Playwright Test Agents bootstrap) entirely — not applicable when
211
+ **Skip qa-explore's Step 6 (Playwright Test Agents bootstrap) entirely; not applicable when
203
212
  the driver is mobile-cli/Maestro.**
@@ -8,12 +8,7 @@ the device. Pick the branch by the target's `auth.strategy`:
8
8
  human login the browser profile persists).
9
9
  - `auth.strategy: none` → skip this phase.
10
10
 
11
- Set up once per Bash block:
12
-
13
- ```bash
14
- export MOBILE_CLI_STATE=/tmp/<target>-state.json
15
- MCLI="$PWD/bin/mcli" # run from the repo root
16
- ```
11
+ Credential values come from `qa/.env`, else `.env` (see `paths.md`); never echo them.
17
12
 
18
13
  ---
19
14
 
@@ -27,14 +22,14 @@ the app each run (or reuse an existing account already on the device).
27
22
 
28
23
  ```bash
29
24
  # Optional cold start (Android): relaunch-clean wipes app data, then cold-starts.
30
- $MCLI relaunch-clean
31
-
32
- $MCLI snapshot # welcome / landing
33
- $MCLI click <create-account / sign-up ref>
34
- $MCLI snapshot # email / details screen
35
- $MCLI fill <email input ref> "<config test_email_pattern, e.g. qa+$(date +%s)@example.com>"
36
- $MCLI click <continue ref>
37
- $MCLI snapshot # OTP / verification screen
25
+ qa/bin/mcli relaunch-clean
26
+
27
+ qa/bin/mcli snapshot # welcome / landing
28
+ qa/bin/mcli click <create-account / sign-up ref>
29
+ qa/bin/mcli snapshot # email / details screen
30
+ qa/bin/mcli fill <email input ref> "<config test_email_pattern, e.g. qa+$(date +%s)@example.com>"
31
+ qa/bin/mcli click <continue ref>
32
+ qa/bin/mcli snapshot # OTP / verification screen
38
33
  ```
39
34
 
40
35
  **OTP on staging:** if the target config records a fixed code (`auth.static_otp`), use it
@@ -42,21 +37,23 @@ instead of waiting for a real OTP. Multi-cell OTP inputs often **do not accept a
42
37
  `fill`** — tap each cell and send one digit at a time:
43
38
 
44
39
  ```bash
45
- $MCLI snapshot # find the per-cell OTP refs
46
40
  for d in <digits of static_otp>; do
47
- $MCLI click <next-cell-ref>
48
- $MCLI fill <that-ref> "$d"
41
+ qa/bin/mcli snapshot # refs expire after 60 s — re-read per cell
42
+ qa/bin/mcli fill <next-cell-ref> "$d"
49
43
  done
50
44
  ```
51
45
 
46
+ Each `fill` spawns a Maestro flow (~3-5 s), so six digits can outlast the 60 s ref TTL and
47
+ abort with exit 3. Re-`snapshot` inside the loop as above, or raise `MCLI_REF_TTL_MS`.
48
+
52
49
  ### Existing-user login (faster for post-auth flows)
53
50
 
54
51
  ```bash
55
- $MCLI launch # do NOT relaunch-clean — preserves the existing account
56
- $MCLI snapshot # if on landing, tap Log In
57
- $MCLI click <login ref>
58
- $MCLI fill <email/username input ref> "<existing test account>"
59
- $MCLI click <continue ref>
52
+ qa/bin/mcli launch # do NOT relaunch-clean — preserves the existing account
53
+ qa/bin/mcli snapshot # if on landing, tap Log In
54
+ qa/bin/mcli click <login ref>
55
+ qa/bin/mcli fill <email/username input ref> "<existing test account>"
56
+ qa/bin/mcli click <continue ref>
60
57
  # OTP same as above (static_otp on staging)
61
58
  ```
62
59
 
@@ -75,10 +72,10 @@ Google Workspace, Auth0, …) — see the web target templates (`_example-sim-io
75
72
  `_example-sim-android-chrome.yml`).
76
73
 
77
74
  ```bash
78
- $MCLI launch # do NOT relaunch-clean — that wipes the profile
79
- $MCLI open-url <web.start_url e.g. .../auth/login>
80
- $MCLI snapshot # login surface / SSO button
81
- $MCLI click <sign-in / SSO button ref>
75
+ qa/bin/mcli launch # do NOT relaunch-clean — that wipes the profile
76
+ qa/bin/mcli open-url <web.start_url e.g. .../auth/login>
77
+ qa/bin/mcli snapshot # login surface / SSO button
78
+ qa/bin/mcli click <sign-in / SSO button ref>
82
79
  # → hands off to the identity provider (e.g. login.microsoftonline.com, your Okta org, …).
83
80
  # A HUMAN completes username + password + MFA by hand in the sim/emulator UI.
84
81
  ```
@@ -90,9 +87,9 @@ reappears mid-session, the session lapsed — hand back to a human; do not fill
90
87
  ### Returning session (already logged in)
91
88
 
92
89
  ```bash
93
- $MCLI launch
94
- $MCLI open-url <web.base_url>
95
- $MCLI snapshot # expect an authenticated landing view, not login
90
+ qa/bin/mcli launch
91
+ qa/bin/mcli open-url <web.base_url>
92
+ qa/bin/mcli snapshot # expect an authenticated landing view, not login
96
93
  ```
97
94
 
98
95
  If you see the login screen or IdP domain, re-do the interactive login above.
@@ -107,14 +104,14 @@ If you see the login screen or IdP domain, re-do the interactive login above.
107
104
 
108
105
  ## Verify Auth (shared)
109
106
 
110
- After auth, `$MCLI snapshot` and confirm authenticated indicators are present:
107
+ After auth, `qa/bin/mcli snapshot` and confirm authenticated indicators are present:
111
108
  - NATIVE: the app's post-login home/landing controls.
112
109
  - WEB: a known post-login heading, nav, or the user's name.
113
110
 
114
111
  If stuck on a login/IdP screen, capture the log:
115
112
 
116
113
  ```bash
117
- $MCLI logs --errors --since 60
114
+ qa/bin/mcli logs --errors --since 60
118
115
  ```
119
116
 
120
117
  **Auth issues to flag as bugs (not session blockers):**