qualiow-exploratory-testing 1.0.0 → 1.2.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 (41) hide show
  1. package/README.md +85 -0
  2. package/bin/mcli +16 -0
  3. package/bin/mobile-cli.mjs +573 -0
  4. package/bin/wadb +6 -0
  5. package/bin/wk-ios +58 -0
  6. package/bin/wkeval.mjs +44 -0
  7. package/data/knowledge/learned-patterns.md +85 -0
  8. package/data/knowledge/manifest.yml +2 -1
  9. package/data/targets/_example-mobile-emulation.yml +52 -0
  10. package/data/targets/_example-native-mobile.yml +61 -0
  11. package/data/targets/_example-sim-android-chrome.yml +81 -0
  12. package/data/targets/_example-sim-ios-safari.yml +80 -0
  13. package/dist/cli/index.js +156 -33
  14. package/dist/cli/index.js.map +1 -1
  15. package/dist/index.d.ts +260 -527
  16. package/dist/index.js +142 -12
  17. package/dist/index.js.map +1 -1
  18. package/docs/MOBILE-SETUP.md +92 -0
  19. package/package.json +33 -11
  20. package/scripts/doctor-mobile.sh +143 -0
  21. package/scripts/setup-mobile.sh +213 -0
  22. package/skills/qa-explore/SKILL.md +2 -1
  23. package/skills/qa-explore/phases/00-setup.md +22 -1
  24. package/skills/qa-explore/phases/01-auth.md +4 -0
  25. package/skills/qa-explore/phases/03-discovery.md +14 -0
  26. package/skills/qa-explore/phases/05-features.md +20 -0
  27. package/skills/qa-explore/phases/06-edge-cases.md +2 -0
  28. package/skills/qa-explore/phases/07-reporting.md +11 -0
  29. package/skills/qa-explore/references/playwright-agents-integration.md +126 -0
  30. package/skills/qa-explore-mobile/SKILL.md +146 -0
  31. package/skills/qa-explore-mobile/phases/00-setup.md +203 -0
  32. package/skills/qa-explore-mobile/phases/01-auth.md +127 -0
  33. package/skills/qa-explore-mobile/phases/02-charter.md +70 -0
  34. package/skills/qa-explore-mobile/phases/03-discovery.md +79 -0
  35. package/skills/qa-explore-mobile/phases/04-journeys.md +49 -0
  36. package/skills/qa-explore-mobile/phases/05-features.md +72 -0
  37. package/skills/qa-explore-mobile/phases/06-edge-cases.md +157 -0
  38. package/skills/qa-explore-mobile/phases/07-reporting.md +123 -0
  39. package/skills/qa-explore-mobile/references/mobile-edges.md +117 -0
  40. package/skills/qa-explore-quick/SKILL.md +7 -0
  41. package/skills/qa-target-setup/SKILL.md +12 -0
package/bin/wkeval.mjs ADDED
@@ -0,0 +1,44 @@
1
+ // wkeval.mjs — evaluate JS in iOS Simulator Safari via WebKit Remote Inspector (through iwdp)
2
+ // Modern WebKit uses a Target-wrapped protocol: commands go via Target.sendMessageToTarget,
3
+ // responses come back via Target.dispatchMessageFromTarget.
4
+ // Usage: node wkeval.mjs '<js-expression>'
5
+ const WS_URL = process.env.WK_WS || 'ws://localhost:9222/devtools/page/1';
6
+ const expr = process.argv[2];
7
+ if (!expr) { console.error('need a JS expression arg'); process.exit(2); }
8
+
9
+ const ws = new WebSocket(WS_URL);
10
+ let outerId = 0, innerId = 0, targetId = null;
11
+ const innerPending = new Map();
12
+
13
+ function rawSend(method, params = {}) { ws.send(JSON.stringify({ id: ++outerId, method, params })); }
14
+ function targetSend(method, params = {}) {
15
+ return new Promise((resolve) => {
16
+ const mid = ++innerId;
17
+ innerPending.set(mid, resolve);
18
+ rawSend('Target.sendMessageToTarget', { targetId, message: JSON.stringify({ id: mid, method, params }) });
19
+ });
20
+ }
21
+
22
+ const timeout = setTimeout(() => { console.error('TIMEOUT'); process.exit(3); }, 20000);
23
+
24
+ ws.addEventListener('message', async (ev) => {
25
+ let msg; try { msg = JSON.parse(ev.data); } catch { return; }
26
+ if (msg.method === 'Target.targetCreated' && !targetId) {
27
+ targetId = msg.params.targetInfo.targetId;
28
+ try {
29
+ await targetSend('Runtime.enable');
30
+ const wrapped = `(function(){ try { var __r = (${expr}); return (typeof __r==='undefined')?'undefined':__r; } catch(e){ return 'ERR: '+e.message; } })()`;
31
+ const res = await targetSend('Runtime.evaluate', { expression: wrapped, returnByValue: true, awaitPromise: true });
32
+ clearTimeout(timeout);
33
+ const r = res && res.result && res.result.result ? res.result.result : (res && res.result);
34
+ if (r && 'value' in r) console.log(typeof r.value === 'object' ? JSON.stringify(r.value) : String(r.value));
35
+ else console.log(JSON.stringify(r));
36
+ process.exit(0);
37
+ } catch (e) { console.error('EVAL_FAIL', e.message || e); process.exit(5); }
38
+ }
39
+ if (msg.method === 'Target.dispatchMessageFromTarget') {
40
+ let inner; try { inner = JSON.parse(msg.params.message); } catch { return; }
41
+ if (inner.id && innerPending.has(inner.id)) { innerPending.get(inner.id)(inner); innerPending.delete(inner.id); }
42
+ }
43
+ });
44
+ ws.addEventListener('error', (e) => { console.error('WS_ERROR', e.message || e); process.exit(4); });
@@ -30,6 +30,91 @@ _None yet — patterns added here will be skipped in future sessions._
30
30
  - Price calculations: test with discounts, tax, multiple quantities, $0 totals
31
31
  - Test ALL user personas if multiple exist — each may have different bugs
32
32
 
33
+ ### Checkout Interaction Patterns (from production monitoring + 100+ historical bugs)
34
+
35
+ **Session & Basket State:**
36
+ - **Modal dismiss + navigate back**: Reserve seat → dismiss login modal (X) → navigate back. Check: "failed to delete basket" console errors? Seats released?
37
+ - **Multiple tabs**: Open checkout in 2 tabs → ticket/site branding mismatches, theme changes, session conflicts - **Session timer off-focus**: Minimize browser → timer may slow down or stop counting
38
+ - **Session expiry modal**: Let timer expire → "Cancel Order" button should NOT navigate to 404
39
+ - **Session TTL**: Orders may be deleted before user completes if session TTL is too short
40
+ - **Basket refetch on focus**: After switching tabs and coming back, basket view may not update
41
+
42
+ **Payment Patterns:**
43
+ - **Duplicate payment callbacks**: PayPal or 3DS can trigger multiple callbacks → duplicate payments
44
+ - **3DS with no paymentMethodId**: 3DS callback called without payment method → fails
45
+ - **3DS retry after failure**: Cancel 3DS → retry → check "payment method not found" errors
46
+ - **Apple Pay failures**: Indefinite loading when Apple Pay fails
47
+ - **Google Pay**: May not work on certain environments
48
+ - **Zero value basket**: Free tickets → billing should show "Confirm your order" and actually work
49
+ - **Voucher + retry**: Selecting voucher on retry page may incorrectly show PayPal button
50
+ - **Payment form issues**: Amex CVV placeholder may be wrong
51
+ - **Payment options accessibility**: Payment selector may not be keyboard accessible
52
+
53
+ **Navigation & Back Button:**
54
+ - **Back button Safari/Firefox**: Browser back may fail to trigger seat release
55
+ - **Back from payment**: May cause endless loop
56
+ - **Back from contacts**: Never loads seatmap, gets stuck
57
+ - **Back from calendar**: May redirect to homepage or 404
58
+ - **Auto scroll persists**: Page scroll position carries over from previous page
59
+
60
+ **Login & Auth:**
61
+ - **Page refresh after login**: Form loses user details, profile icon shows logged-out, CPS 400 errors
62
+ - **New accounts**: May get stuck in endless loop during checkout
63
+ - **Required login flow**: Can trigger "Unexpected Application Error!" on contacts page intermittently
64
+ - **Guest → login transition**: On voucher flow, refresh after login breaks the form
65
+
66
+ **Delivery & Contacts:**
67
+ - **Skip contacts page**: Reaching payment without delivery method selection → "delivery method ID missing" errors
68
+ - **Customer country data**: May create customer record with wrong country
69
+ - **Delivery method misalignment**: Methods may not match what's expected
70
+
71
+ **Upsells & Extras:**
72
+ - **Upsell removal race condition**: If basket refetches while upsell removal is in-flight, removed upsell reappears and can't be removed
73
+ - **Lounge toggle quantity**: Toggle should add packages × ticket count, not just 1
74
+ - **Unavailable upsells**: Should notify user, not silently fail
75
+ - **Slow lounge addition**: Large ticket count → upsell reservation times out
76
+ - **Upsell ordering**: Should match CMS configuration, not random
77
+ - **Last upsell removal**: Removing the last non-ticket upsell may delete the entire AV session
78
+
79
+ **Ticket Protection:**
80
+ - **TP links wrong region**: UK shows US terms, US shows UK terms
81
+ - **TP purchased multiple times**: Should only be purchasable once
82
+ - **TP skip/redirect**: May skip TP page due to timer expiry logic
83
+ - **TP endless loading**: Can get stuck between TP and payment
84
+ - **TP error handling**: TP service errors should let user continue to payment
85
+ - **TP blocking checkout**: Basket update during TP should block progression until complete
86
+
87
+ **Fees & Pricing:**
88
+ - **Fee copy when no fees**: Shows fee text even when there are no fees
89
+ - **Fees display incorrect**: Basket summary may show wrong fee amounts
90
+ - **Decimal price rejection**: Some tickets rejected because basket API doesn't accept decimal totals
91
+ - **Currency symbol wrong region**: £ symbol showing in US totals
92
+ - **Upsell prices misaligned**: Price formatting inconsistent
93
+
94
+ **Themes & Branding:**
95
+ - **Theme changes post-seatmap**: Theme may reset after navigating back
96
+ - **Theme loading delay**: Visible flash of wrong theme
97
+ - **US domains redirecting to UK**: Links in footer, confirmation, error pages go to UK
98
+ - **Favicons**: Should show new ATG Entertainment logo
99
+
100
+ **Confirmation & Post-Purchase:**
101
+ - **Confirmation page guard**: Should NOT be accessible without completing payment
102
+ - **Confirmation header not clickable**: Users get locked in
103
+ - **Continue to checkout button on confirmation**: Should not appear
104
+ - **Order confirmation CTA**: Should go to correct region MyAccount
105
+
106
+ **Copy & Legal:**
107
+ - **Basket expired modal copy**: Should be correct for all shows/themes
108
+ - **Payment retry phone numbers**: Must be correct per US region
109
+ - **Legal links with www**: Should not have www prefix
110
+ - **Error page phone numbers**: Must be region-appropriate
111
+ - **Voucher copy**: Gift card terminology for US
112
+
113
+ **Security:**
114
+ - **OWASP A01 Broken Access Control**: Basket summary had access control issue
115
+ - **XSS in calendar service**: ReDoS vulnerability
116
+ - **Comp ticket exposure**: Internal pricing visible to regular users
117
+
33
118
  ### Fintech
34
119
  - Session IDs should never appear in URLs (security risk)
35
120
  - Admin pages should require authentication
@@ -28,7 +28,8 @@ loading_strategy:
28
28
  - heuristic-goldilocks
29
29
  - technique-boundary-testing
30
30
  by_domain:
31
- ecommerce: []
31
+ ecommerce:
32
+ - atg-checkout-historical-bugs
32
33
  saas: []
33
34
  fintech: []
34
35
  by_tag:
@@ -0,0 +1,52 @@
1
+ # Template target — MOBILE-WEB EMULATION via Playwright (desktop engine, mobile device
2
+ # descriptor). This is the /qa-explore path, NOT /qa-explore-mobile — no simulator needed.
3
+ #
4
+ # WHEN TO USE WHICH:
5
+ # - This template (Playwright emulation): fast, supports storage_state auth, full
6
+ # console/network/eval — but the engine is desktop Chromium/WebKit pretending to be
7
+ # a phone. Good for layout, flows, and most functional bugs.
8
+ # - _example-sim-ios-safari.yml / _example-sim-android-chrome.yml (real sim browsers via
9
+ # /qa-explore-mobile): the genuine mobile engines — required for engine-identity
10
+ # behavior (UA/feature detection, real keyboard/viewport behavior, Safari quirks).
11
+ # Playwright's "webkit" is desktop macOS WebKit, NOT iOS Safari.
12
+ id: example-mobile-emulation
13
+ name: "Example Mobile Web App — Playwright Mobile Emulation (WebKit)"
14
+ base_url: "https://staging.m.example.com"
15
+ domain: _default
16
+ auth:
17
+ strategy: storage_state
18
+ state_file: ".auth/example-mobile-emulation.json"
19
+ login_url: "https://staging.m.example.com/login"
20
+ browser:
21
+ headless: false
22
+ engine: webkit # webkit (Safari-like) | chromium (Chrome-like)
23
+ channel: webkit
24
+ device: "iPhone 15" # Playwright device descriptor — sets mobile UA + viewport + touch
25
+ viewport: { width: 390, height: 844 }
26
+ safety:
27
+ read_only: false
28
+ no_form_submit: false
29
+ scope:
30
+ start_pages:
31
+ - "/"
32
+ max_depth: 3
33
+ exclude_patterns:
34
+ - "/auth/*"
35
+ - "/api/*"
36
+ - "**/*.pdf"
37
+ notes: |
38
+ Mobile-web emulation target: Playwright with a mobile device descriptor. Closest proxy
39
+ to real mobile browsers that Playwright offers (caveat: WebKit != Safari — no Apple Pay,
40
+ ITP nuances differ; Chromium != Android Chrome).
41
+
42
+ The device descriptor matters: many mobile hosts redirect desktop UAs to the desktop
43
+ site — viewport resize alone is NOT enough; the descriptor sets the mobile UA. Launch:
44
+ PLAYWRIGHT_MCP_DEVICE="iPhone 15" PLAYWRIGHT_MCP_BROWSER="webkit" playwright-cli ...
45
+ or pass --browser=webkit --device="iPhone 15" explicitly.
46
+
47
+ Create a chromium twin of this config to cross-check engine-specific behavior. WebKit
48
+ and Chromium maintain independent cookie jars — state files are NOT interchangeable
49
+ between engine variants; each needs its own one-time login via /qa-target-setup.
50
+
51
+ For bugs that depend on the real engine identity (browser detection, install prompts,
52
+ engine-specific rendering), escalate to the real-sim targets and /qa-explore-mobile.
@@ -0,0 +1,61 @@
1
+ # Example target — NATIVE-MODE mobile app on a simulator/emulator.
2
+ # Copy this file, rename it, and fill in the values for your app. This documents the
3
+ # fields /qa-explore-mobile reads to run in NATIVE mode (the app itself is the system
4
+ # under test, driven via Maestro + adb / xcrun simctl through bin/mobile-cli.mjs).
5
+ #
6
+ # For WEB mode (a real device browser pointed at a URL), see the committed examples
7
+ # _example-sim-ios-safari.yml / _example-sim-android-chrome.yml instead.
8
+ #
9
+ # MODE DETECTION (done in phases/00-setup.md):
10
+ # - WEB mode -> app is a browser bundle (com.apple.mobilesafari / com.android.chrome)
11
+ # AND a web.base_url is present.
12
+ # - NATIVE mode -> app is a non-browser bundle/package with installable artifact paths
13
+ # (app_paths / apk_paths), no web.base_url.
14
+
15
+ id: example-native-mobile
16
+ name: "Example Native App (simulator/emulator)"
17
+ domain: _default
18
+ platform: ios # ios | android (required)
19
+
20
+ device:
21
+ # iOS: a simulator name or UDID. Android: an AVD name and/or a booted serial.
22
+ name: "iPhone 17" # iOS sim label
23
+ udid: "REPLACE-WITH-SIM-UDID" # iOS sim UDID (from `xcrun simctl list devices`)
24
+ # avd: my_test_avd # Android AVD name (created via Android Studio / avdmanager)
25
+ # serial: emulator-5554 # Android serial once the AVD is booted
26
+
27
+ app:
28
+ # The app under test (NOT a browser). Use whichever id matches the platform.
29
+ bundle_id: com.example.myapp # iOS bundle id
30
+ # package: com.example.myapp # Android application id
31
+ #
32
+ # Installable artifact(s) used to verify/install the build on the device. If the app is
33
+ # already installed and you don't need to (re)install, these can be omitted.
34
+ app_paths: # iOS .app bundle(s) (simulator build)
35
+ - "/absolute/path/to/MyApp.app"
36
+ # apk_paths: # Android APK(s)
37
+ # - "/absolute/path/to/myapp-release.apk"
38
+
39
+ # OPTIONAL — only needed if you want /qa-explore-mobile to be able to rebuild from source.
40
+ # Skipped unless the user passes --rebuild or the session goal mentions "latest"/"fresh".
41
+ # build_commands are referenced generically by 00-setup.md — put the EXACT commands your
42
+ # project uses here (no framework is assumed by the skill).
43
+ # source_repo:
44
+ # path: "/absolute/path/to/app-source"
45
+ # build_commands:
46
+ # # Each command should build AND install onto the configured device.
47
+ # android_release: "..." # e.g. your project's release build+install command
48
+ # ios_debug: "..." # e.g. your project's sim build+install command
49
+ # refresh: "git fetch && git status -sb" # used to detect upstream drift before rebuild
50
+
51
+ auth:
52
+ # in-app -> account creation / login happens inside the app (see phases/01-auth.md).
53
+ # none -> no auth.
54
+ strategy: in-app
55
+ # For staging/test builds that accept a fixed one-time code, record it here so the
56
+ # auth phase can use it instead of a real OTP. Leave unset for real OTP delivery.
57
+ # static_otp: "000000"
58
+ # test_email_pattern: "qa+{unique}@example.com" # if the app needs a unique email per signup
59
+
60
+ scope:
61
+ start_screen: launch # the app's first screen after launch
@@ -0,0 +1,81 @@
1
+ # Template target — WEB-MODE mobile app in the REAL Android Emulator Chrome.
2
+ # Copy this file, rename it, and point web.base_url at your mobile web app.
3
+ # For NATIVE mode (an installed app under test), see _example-native-mobile.yml.
4
+ id: example-sim-android-chrome
5
+ name: "Example Mobile Web App — Android Emulator Chrome"
6
+ platform: android
7
+ domain: _default
8
+ # This target drives a WEB app through a real mobile browser on a real emulator.
9
+ # The "app" is just Chrome; the system under test is the web app served at web.base_url.
10
+ # mobile-cli treats Chrome like any other app: set-app -> launch -> open-url -> snapshot.
11
+ device:
12
+ avd: qa_pixel_api35 # standard AVD created by scripts/setup-mobile.sh (Google-Play API 35). Override to any existing AVD (run: emulator -list-avds).
13
+ serial: emulator-5554 # populated once the AVD is booted
14
+ app:
15
+ # The browser IS the app. No native build/install needed — Chrome is preinstalled on
16
+ # Google-Play emulator images, so there is no apk_paths / build step here.
17
+ # NOTE: stock AOSP / non-Play emulator images may NOT ship Chrome — they often have only
18
+ # a basic AOSP browser or none. If `adb shell pm list packages | grep chrome` shows no
19
+ # com.android.chrome, use a Google-APIs/Play image AVD rather than assuming it's present.
20
+ package: com.android.chrome
21
+ web:
22
+ base_url: "https://staging.m.example.com"
23
+ start_url: "https://staging.m.example.com/login"
24
+ # Many mobile hosts enforce a mobile User-Agent and redirect desktop UAs to the desktop
25
+ # host. A real emulator Chrome sends a genuine mobile UA, so this is a non-issue.
26
+ auth:
27
+ strategy: interactive-sso # interactive SSO + MFA — cannot be automated
28
+ identity_provider: "your IdP (e.g. Microsoft Entra, Okta, Auth0)"
29
+ login_url: "https://staging.m.example.com/login"
30
+ # One-time interactive login, then the browser profile persists the session.
31
+ # Do NOT attempt to script the MFA challenge. Use strategy: none for public apps.
32
+ scope:
33
+ start_screen: login
34
+ start_url: "https://staging.m.example.com/login"
35
+ notes: |
36
+ WHAT THIS IS
37
+ A browser-as-app target: Android Emulator Chrome pointed at a mobile web app. The
38
+ Maestro/adb route used by mobile-cli drives the real Android Chrome engine.
39
+
40
+ NO NATIVE BUILD NEEDED (but verify Chrome exists — see app.package note above)
41
+ Boot the AVD, then:
42
+ bin/wadb devices # boot `emulator -avd <your-avd> ...` first if empty
43
+ bin/wadb shell pm list packages | grep chrome # confirm com.android.chrome is present
44
+ export MOBILE_CLI_STATE=/tmp/<target>-state.json
45
+ bin/mcli set-device emulator-5554
46
+ bin/mcli set-app com.android.chrome
47
+ bin/mcli launch
48
+ bin/mcli open-url <web.base_url>
49
+ bin/mcli snapshot
50
+ Use a dedicated MOBILE_CLI_STATE so you don't clobber another target's default state.
51
+ On a fresh Chrome profile you may see a one-time first-run / "Open tabs" promo bubble —
52
+ mobile-cli filters the promo (com.android.chrome:id/message) out of snapshots; if a
53
+ full-screen first-run/sign-in-to-Chrome interstitial appears, dismiss it once by hand.
54
+
55
+ A11Y-vs-DOM LIMITATION (document, do not try to solve)
56
+ snapshot reads the accessibility tree, not the DOM. Web content IS exposed to a11y —
57
+ headings, links, buttons, inputs and visible text become tappable refs. But versus
58
+ playwright-cli you LOSE: CSS/DOM selectors, console & network introspection, route-based
59
+ mocking, and reliable exact-DOM assertions. You drive purely by visible/accessible labels
60
+ and tap coordinates.
61
+ mobile-cli auto-filters Chrome's own chrome (omnibox/URL bar, tab switcher, menu, toolbar,
62
+ infobars/promos) from snapshots when the app id is a known browser, so the ref tree is the
63
+ page, not the browser furniture. The generic android:id/content root and the system status
64
+ bar may still appear (no stable app-specific id to filter on).
65
+
66
+ AUTH REALITY — SSO + MFA (do NOT automate)
67
+ If the app logs in via an interactive IdP with MFA: unlike Playwright, there is NO
68
+ transferable storage_state you can inject into a real emulator browser. The practical
69
+ approach is a ONE-TIME INTERACTIVE LOGIN performed by a human in the emulator's Chrome:
70
+ open the start_url, complete the username/password + MFA prompt by hand once. The
71
+ emulator persists Chrome's profile (cookies/session) across app launches and across
72
+ mobile-cli `launch`/`open-url` calls (as long as the AVD is not wiped / `pm clear`ed), so
73
+ subsequent exploration reuses that session without re-authenticating until it expires.
74
+ Never script the MFA step. Avoid `relaunch-clean` on this target — `pm clear
75
+ com.android.chrome` wipes the logged-in profile and forces a fresh SSO+MFA login.
76
+
77
+ EMULATOR / EXPLORATION NOTES
78
+ Android Chrome DOES expose the live page to uiautomator/Maestro's hierarchy, so snapshot
79
+ refs map to real web elements. Hardware BACK works here (`press BACK`) unlike iOS. If the
80
+ emulator is slow/flaky to boot or Chrome is absent on the chosen image, document that and
81
+ fall back to the iOS Safari target rather than blocking — the two engines are independent.
@@ -0,0 +1,80 @@
1
+ # Template target — WEB-MODE mobile app in the REAL iOS Simulator Safari.
2
+ # Copy this file, rename it, and point web.base_url at your mobile web app.
3
+ # For NATIVE mode (an installed app under test), see _example-native-mobile.yml.
4
+ id: example-sim-ios-safari
5
+ name: "Example Mobile Web App — iOS Simulator Safari"
6
+ platform: ios
7
+ domain: _default
8
+ # This target drives a WEB app through a real mobile browser on a real simulator.
9
+ # The "app" is just Safari; the system under test is the web app served at web.base_url.
10
+ # mobile-cli treats Safari like any other app: set-app -> launch -> open-url -> snapshot.
11
+ device:
12
+ # Resolve by NAME, not a hardcoded UDID (UDIDs are per-machine). scripts/setup-mobile.sh
13
+ # creates a standard sim named "qa-iphone"; on a machine that already has sims you can set
14
+ # this to any available iPhone (see: xcrun simctl list devices available). 00-setup boots
15
+ # the named device (creating it if missing) and resolves its UDID at runtime.
16
+ name: "qa-iphone"
17
+ # udid: optional — if set, takes precedence over name. Leave unset for portability.
18
+ app:
19
+ # The browser IS the app. No native build/install needed — Safari is preinstalled
20
+ # on every iOS simulator runtime, so there is no app_paths / build step here.
21
+ bundle_id: com.apple.mobilesafari
22
+ web:
23
+ base_url: "https://staging.m.example.com"
24
+ start_url: "https://staging.m.example.com/login"
25
+ # Many mobile hosts enforce a mobile User-Agent and redirect desktop UAs to the desktop
26
+ # host. A real simulator Safari already sends a genuine mobile UA, so this is a non-issue
27
+ # here (it only bites Playwright/desktop browsers).
28
+ auth:
29
+ strategy: interactive-sso # interactive SSO + MFA — cannot be automated
30
+ identity_provider: "your IdP (e.g. Microsoft Entra, Okta, Auth0)"
31
+ login_url: "https://staging.m.example.com/login"
32
+ # One-time interactive login, then the browser profile persists the session.
33
+ # Do NOT attempt to script the MFA challenge. Use strategy: none for public apps.
34
+ scope:
35
+ start_screen: login
36
+ start_url: "https://staging.m.example.com/login"
37
+ notes: |
38
+ WHAT THIS IS
39
+ A browser-as-app target: iOS Simulator Safari pointed at a mobile web app. The genuine
40
+ engine matters here — Playwright CANNOT drive iOS Simulator Safari, and Playwright's
41
+ "webkit" is desktop macOS WebKit, NOT the simulator's WebKit. The Maestro/simctl route
42
+ used by mobile-cli is the only way to exercise the real iOS engine.
43
+
44
+ NO NATIVE BUILD NEEDED
45
+ Safari ships with every simulator runtime — nothing to build or install. Just boot the
46
+ sim (`xcrun simctl boot <udid>; open -a Simulator`), then:
47
+ export MOBILE_CLI_STATE=/tmp/<target>-state.json
48
+ bin/mcli set-device <udid>
49
+ bin/mcli set-app com.apple.mobilesafari
50
+ bin/mcli launch
51
+ bin/mcli open-url <web.base_url>
52
+ bin/mcli snapshot
53
+ Use a dedicated MOBILE_CLI_STATE so you don't clobber another target's default state.
54
+
55
+ A11Y-vs-DOM LIMITATION (document, do not try to solve)
56
+ snapshot reads the accessibility tree, not the DOM. Web content IS exposed to a11y —
57
+ headings, links, buttons, inputs and visible text become tappable refs. But versus
58
+ playwright-cli you LOSE: CSS/DOM selectors, console & network introspection, route-based
59
+ mocking, and reliable exact-DOM assertions. You drive purely by visible/accessible labels
60
+ and tap coordinates.
61
+ mobile-cli auto-filters Safari's own chrome (URL/address bar, tabs, toolbar, on-screen
62
+ keyboard) from snapshots when the app id is a known browser, so the ref tree is the page,
63
+ not the browser furniture. Residual non-app noise that has no stable a11y id (the iOS
64
+ status bar clock/wifi/battery and transient "NN%" page-load progress) may still appear.
65
+
66
+ AUTH REALITY — SSO + MFA (do NOT automate)
67
+ If the app logs in via an interactive IdP with MFA: unlike Playwright, there is NO
68
+ transferable storage_state you can inject into a real simulator browser. The practical
69
+ approach is a ONE-TIME INTERACTIVE LOGIN performed by a human in the sim's Safari:
70
+ open the start_url, complete the username/password + MFA prompt by hand once. The
71
+ simulator persists Safari's profile (cookies/session) across app launches and across
72
+ mobile-cli `launch`/`open-url` calls, so subsequent exploration reuses that session
73
+ without re-authenticating (until the session expires or the sim is erased). Never script
74
+ the MFA step. If you land on the IdP domain mid-session, that just means the session
75
+ lapsed — hand back to a human for re-login.
76
+
77
+ iOS SIM CONSTRAINTS (inherited from the native iOS target)
78
+ No hardware BACK key (use an on-screen/web back control via snapshot+click), no biometric
79
+ flow, no easy CLI rotation. iOS a11y can also aggregate sibling nodes into one comma-joined
80
+ label on some screens — tap by coordinates from a `snapshot --full` when that happens.