qualiow-exploratory-testing 1.1.0 → 1.3.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.
- package/README.md +177 -0
- package/bin/mcli +16 -0
- package/bin/mobile-cli.mjs +573 -0
- package/bin/wadb +6 -0
- package/bin/wk-ios +58 -0
- package/bin/wkeval.mjs +44 -0
- package/data/domains/_default.md +181 -0
- package/data/domains/ecommerce.md +192 -0
- package/data/domains/fintech.md +200 -0
- package/data/domains/identity.md +88 -0
- package/data/domains/identity.yml +138 -0
- package/data/domains/marketing.md +194 -0
- package/data/domains/saas.md +197 -0
- package/data/knowledge/changelog.yml +86 -0
- package/data/knowledge/learned-patterns.md +172 -1
- package/data/knowledge/manifest.yml +210 -4
- package/data/knowledge/releases/v0.2.0/entries/technique-contract-narrowing.yml +150 -0
- package/data/knowledge/releases/v0.2.0/entries/technique-test-suite-audit.yml +116 -0
- package/data/knowledge/releases/v0.2.0/release.yml +20 -0
- package/data/knowledge/releases/v0.3.0/entries/technique-functional-diff-analysis.yml +119 -0
- package/data/knowledge/releases/v0.3.0/entries/technique-llm-output-verification.yml +102 -0
- package/data/knowledge/releases/v0.3.0/entries/technique-verification-mode-selection.yml +153 -0
- package/data/knowledge/releases/v0.3.0/release.yml +25 -0
- package/data/knowledge/releases/v0.4.0/entries/technique-authenticated-api-probing.yml +137 -0
- package/data/knowledge/releases/v0.4.0/entries/technique-environment-fingerprinting.yml +113 -0
- package/data/knowledge/releases/v0.4.0/entries/technique-silent-failure-audit.yml +86 -0
- package/data/knowledge/releases/v0.4.0/entries/technique-ui-api-differential.yml +97 -0
- package/data/knowledge/releases/v0.4.0/release.yml +28 -0
- package/data/knowledge/releases/v0.5.0/entries/technique-config-surface-verification.yml +77 -0
- package/data/knowledge/releases/v0.5.0/entries/technique-derived-value-verification.yml +81 -0
- package/data/knowledge/releases/v0.5.0/entries/technique-expected-behaviour-specification.yml +97 -0
- package/data/knowledge/releases/v0.5.0/entries/technique-presentation-integrity.yml +78 -0
- package/data/knowledge/releases/v0.5.0/entries/technique-release-readiness-verification.yml +110 -0
- package/data/knowledge/releases/v0.5.0/release.yml +33 -0
- package/data/targets/_example-backend.yml +123 -0
- package/data/targets/_example-mobile-emulation.yml +52 -0
- package/data/targets/_example-native-mobile.yml +61 -0
- package/data/targets/_example-sim-android-chrome.yml +81 -0
- package/data/targets/_example-sim-ios-safari.yml +80 -0
- package/data/templates/api-probe-matrix.md +99 -0
- package/data/templates/coverage-map.md +14 -0
- package/data/templates/expected-behaviour.md +93 -0
- package/dist/cli/index.js +137 -5
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +350 -527
- package/dist/index.js +144 -5
- package/dist/index.js.map +1 -1
- package/docs/BACKEND-VERIFICATION.md +277 -0
- package/docs/MOBILE-SETUP.md +92 -0
- package/package.json +26 -12
- package/scripts/doctor-mobile.sh +143 -0
- package/scripts/setup-mobile.sh +213 -0
- package/skills/qa-explore/phases/00-setup.md +8 -1
- package/skills/qa-explore/phases/01-auth.md +4 -0
- package/skills/qa-explore-mobile/SKILL.md +146 -0
- package/skills/qa-explore-mobile/phases/00-setup.md +203 -0
- package/skills/qa-explore-mobile/phases/01-auth.md +127 -0
- package/skills/qa-explore-mobile/phases/02-charter.md +70 -0
- package/skills/qa-explore-mobile/phases/03-discovery.md +79 -0
- package/skills/qa-explore-mobile/phases/04-journeys.md +49 -0
- package/skills/qa-explore-mobile/phases/05-features.md +72 -0
- package/skills/qa-explore-mobile/phases/06-edge-cases.md +157 -0
- package/skills/qa-explore-mobile/phases/07-reporting.md +123 -0
- package/skills/qa-explore-mobile/references/mobile-edges.md +117 -0
- package/skills/qa-explore-quick/SKILL.md +6 -0
- package/skills/qa-verify-backend/SKILL.md +163 -0
- package/skills/qa-verify-backend/phases/00-setup.md +97 -0
- package/skills/qa-verify-backend/phases/01-ac-decomposition.md +58 -0
- package/skills/qa-verify-backend/phases/02-static-review.md +71 -0
- package/skills/qa-verify-backend/phases/03-live-verification.md +62 -0
- package/skills/qa-verify-backend/phases/03b-api-verification.md +157 -0
- package/skills/qa-verify-backend/phases/04-e2e-trigger.md +66 -0
- package/skills/qa-verify-backend/phases/05-reporting.md +135 -0
- package/skills/qa-verify-backend/references/api-probes.md +141 -0
- package/skills/qa-verify-backend/references/aws-readonly-probes.md +156 -0
- package/skills/qa-verify-backend/references/environment-fingerprinting.md +104 -0
- package/skills/qa-verify-backend/references/payload-verification.md +112 -0
- package/skills/qa-verify-backend/references/release-readiness.md +97 -0
- package/skills/qa-verify-backend/references/safety-rules.md +90 -0
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# setup-mobile.sh — idempotent bootstrap for the qa-explore-mobile skill on a fresh Mac.
|
|
3
|
+
#
|
|
4
|
+
# Installs everything mobile-cli needs that CAN be scripted, and creates standard-named
|
|
5
|
+
# devices the target configs expect. Re-runnable: every step checks before acting.
|
|
6
|
+
#
|
|
7
|
+
# What it can do automatically:
|
|
8
|
+
# - Homebrew (offers to install if missing), Node, JDK 17, Maestro
|
|
9
|
+
# - Android: cmdline-tools, platform-tools, emulator, a Google-Play system image,
|
|
10
|
+
# license acceptance, and a standard AVD ($ANDROID_AVD_NAME, default qa_pixel_api35)
|
|
11
|
+
# - iOS: a standard simulator device ($IOS_DEVICE_NAME, default qa-iphone) from an
|
|
12
|
+
# installed iOS runtime
|
|
13
|
+
#
|
|
14
|
+
# What stays MANUAL (printed as guidance, never silently skipped):
|
|
15
|
+
# - Xcode itself (multi-GB App Store install) + `xcodebuild -license accept`
|
|
16
|
+
# - iOS runtime download (Xcode ▸ Settings ▸ Components) if none is installed
|
|
17
|
+
#
|
|
18
|
+
# Usage:
|
|
19
|
+
# scripts/setup-mobile.sh # both platforms
|
|
20
|
+
# scripts/setup-mobile.sh --android # Android only
|
|
21
|
+
# scripts/setup-mobile.sh --ios # iOS only
|
|
22
|
+
# scripts/setup-mobile.sh --yes # non-interactive (assume yes to prompts)
|
|
23
|
+
#
|
|
24
|
+
# After it finishes it runs doctor-mobile.sh to confirm the result.
|
|
25
|
+
|
|
26
|
+
set -uo pipefail
|
|
27
|
+
|
|
28
|
+
PLATFORM="both"; ASSUME_YES=0
|
|
29
|
+
for arg in "$@"; do
|
|
30
|
+
case "$arg" in
|
|
31
|
+
--android) PLATFORM="android" ;;
|
|
32
|
+
--ios) PLATFORM="ios" ;;
|
|
33
|
+
--yes|-y) ASSUME_YES=1 ;;
|
|
34
|
+
-h|--help) sed -n '2,28p' "$0"; exit 0 ;;
|
|
35
|
+
*) echo "unknown arg: $arg" >&2; exit 2 ;;
|
|
36
|
+
esac
|
|
37
|
+
done
|
|
38
|
+
|
|
39
|
+
HERE="$(cd "$(dirname "$0")" && pwd)"
|
|
40
|
+
ARCH="$(uname -m)" # arm64 | x86_64
|
|
41
|
+
ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}"
|
|
42
|
+
ANDROID_AVD_NAME="${ANDROID_AVD_NAME:-qa_pixel_api35}"
|
|
43
|
+
ANDROID_API="${ANDROID_API:-35}"
|
|
44
|
+
IOS_DEVICE_NAME="${IOS_DEVICE_NAME:-qa-iphone}"
|
|
45
|
+
if [ "$ARCH" = "arm64" ]; then ABI="arm64-v8a"; else ABI="x86_64"; fi
|
|
46
|
+
SYS_IMAGE="system-images;android-${ANDROID_API};google_apis_playstore;${ABI}"
|
|
47
|
+
|
|
48
|
+
say() { printf '\n\033[1m▸ %s\033[0m\n' "$1"; }
|
|
49
|
+
info() { printf ' %s\n' "$1"; }
|
|
50
|
+
skip() { printf ' \033[32m✓ already present:\033[0m %s\n' "$1"; }
|
|
51
|
+
manual(){ printf ' \033[33m⚠ MANUAL STEP:\033[0m %s\n' "$1"; }
|
|
52
|
+
confirm() {
|
|
53
|
+
[ "$ASSUME_YES" = 1 ] && return 0
|
|
54
|
+
printf ' %s [y/N] ' "$1"; read -r ans </dev/tty 2>/dev/null || ans=n
|
|
55
|
+
case "$ans" in y|Y|yes) return 0;; *) return 1;; esac
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
# ----------------------------------------------------------------- Homebrew
|
|
59
|
+
say "Homebrew"
|
|
60
|
+
if command -v brew >/dev/null 2>&1; then skip "brew $(brew --version | head -1)"; else
|
|
61
|
+
if confirm "Homebrew not found. Install it now?"; then
|
|
62
|
+
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
|
|
63
|
+
else manual "Install Homebrew, then re-run: https://brew.sh"; fi
|
|
64
|
+
fi
|
|
65
|
+
BREW="$(command -v brew || true)"
|
|
66
|
+
[ -z "$BREW" ] && [ -x /opt/homebrew/bin/brew ] && BREW=/opt/homebrew/bin/brew
|
|
67
|
+
[ -z "$BREW" ] && [ -x /usr/local/bin/brew ] && BREW=/usr/local/bin/brew
|
|
68
|
+
|
|
69
|
+
# ----------------------------------------------------------------- Node
|
|
70
|
+
say "Node.js (>=18)"
|
|
71
|
+
if command -v node >/dev/null 2>&1 && [ "$(node -v | sed 's/v//;s/\..*//')" -ge 18 ]; then
|
|
72
|
+
skip "node $(node -v)"
|
|
73
|
+
elif [ -n "$BREW" ]; then info "installing node..."; "$BREW" install node || manual "brew install node failed — install Node >=18 manually"; fi
|
|
74
|
+
|
|
75
|
+
# ----------------------------------------------------------------- Maestro
|
|
76
|
+
say "Maestro"
|
|
77
|
+
if [ -x "$HOME/.maestro/bin/maestro" ] || command -v maestro >/dev/null 2>&1; then
|
|
78
|
+
skip "maestro present"
|
|
79
|
+
else
|
|
80
|
+
if confirm "Install Maestro now?"; then curl -Ls "https://get.maestro.mobile.dev" | bash || manual 'curl -Ls "https://get.maestro.mobile.dev" | bash'; fi
|
|
81
|
+
fi
|
|
82
|
+
|
|
83
|
+
# ============================================================ ANDROID
|
|
84
|
+
if [ "$PLATFORM" = "both" ] || [ "$PLATFORM" = "android" ]; then
|
|
85
|
+
say "Android — JDK 17"
|
|
86
|
+
if /usr/libexec/java_home -v 17 >/dev/null 2>&1; then skip "JDK 17 ($(/usr/libexec/java_home -v 17))"; else
|
|
87
|
+
if [ -n "$BREW" ]; then info "installing openjdk@17..."; "$BREW" install openjdk@17 || manual "brew install openjdk@17"; fi
|
|
88
|
+
fi
|
|
89
|
+
JAVA_HOME_17="$(/usr/libexec/java_home -v 17 2>/dev/null || echo /opt/homebrew/opt/openjdk@17)"
|
|
90
|
+
export JAVA_HOME="$JAVA_HOME_17"
|
|
91
|
+
|
|
92
|
+
say "Android — SDK command-line tools"
|
|
93
|
+
if ls "$ANDROID_HOME"/cmdline-tools/*/bin/sdkmanager >/dev/null 2>&1; then skip "cmdline-tools present"; else
|
|
94
|
+
if [ -n "$BREW" ] && confirm "Install android-commandlinetools via Homebrew?"; then
|
|
95
|
+
"$BREW" install --cask android-commandlinetools || manual "install Android Studio or cmdline-tools manually"
|
|
96
|
+
else manual "Install Android cmdline-tools (Android Studio ▸ SDK Manager, or brew install --cask android-commandlinetools)"; fi
|
|
97
|
+
fi
|
|
98
|
+
SDKMGR="$(ls "$ANDROID_HOME"/cmdline-tools/*/bin/sdkmanager 2>/dev/null | head -1)"
|
|
99
|
+
# Homebrew installs the cask under its own prefix (share/android-commandlinetools,
|
|
100
|
+
# older cask versions used share/android-commandline-tools) and links the binaries
|
|
101
|
+
# into $(brew --prefix)/bin — fall back through those locations. ANDROID_HOME stays
|
|
102
|
+
# at its default: packages are installed there via --sdk_root, matching what
|
|
103
|
+
# bin/mcli, bin/wadb and doctor-mobile.sh expect.
|
|
104
|
+
if [ -z "$SDKMGR" ]; then
|
|
105
|
+
for CASK_SHARE in /opt/homebrew/share/android-commandlinetools /opt/homebrew/share/android-commandline-tools /usr/local/share/android-commandlinetools /usr/local/share/android-commandline-tools; do
|
|
106
|
+
CAND="$(ls "$CASK_SHARE"/cmdline-tools/*/bin/sdkmanager 2>/dev/null | head -1)"
|
|
107
|
+
if [ -n "$CAND" ]; then SDKMGR="$CAND"; break; fi
|
|
108
|
+
done
|
|
109
|
+
fi
|
|
110
|
+
[ -z "$SDKMGR" ] && command -v sdkmanager >/dev/null 2>&1 && SDKMGR="$(command -v sdkmanager)"
|
|
111
|
+
AVDMGR="$(dirname "${SDKMGR:-/x}")/avdmanager"
|
|
112
|
+
[ ! -x "$AVDMGR" ] && command -v avdmanager >/dev/null 2>&1 && AVDMGR="$(command -v avdmanager)"
|
|
113
|
+
|
|
114
|
+
if [ -n "$SDKMGR" ] && [ -x "$SDKMGR" ]; then
|
|
115
|
+
say "Android — SDK packages + licenses (into $ANDROID_HOME)"
|
|
116
|
+
export ANDROID_SDK_ROOT="$ANDROID_HOME"
|
|
117
|
+
mkdir -p "$ANDROID_HOME"
|
|
118
|
+
# yes exits via SIGPIPE when sdkmanager closes stdin — under `set -o pipefail`
|
|
119
|
+
# that marks the pipeline failed even though sdkmanager succeeded, so run the
|
|
120
|
+
# licenses pipe with pipefail off, and the installs with no pipe at all
|
|
121
|
+
# (licenses are already accepted; </dev/null prevents any interactive hang).
|
|
122
|
+
info "accepting licenses..."; ( set +o pipefail; yes 2>/dev/null | "$SDKMGR" --sdk_root="$ANDROID_HOME" --licenses >/dev/null 2>&1 ) || true
|
|
123
|
+
# cmdline-tools;latest goes FIRST: it puts sdkmanager/avdmanager INSIDE the SDK
|
|
124
|
+
# root. avdmanager resolves the SDK from its own install location, so the copy
|
|
125
|
+
# under the brew cask prefix cannot see packages installed into $ANDROID_HOME
|
|
126
|
+
# ("Package path is not valid ... null") — the in-SDK copy can.
|
|
127
|
+
for pkg in "cmdline-tools;latest" "platform-tools" "emulator" "platforms;android-${ANDROID_API}" "$SYS_IMAGE"; do
|
|
128
|
+
info "ensuring: $pkg"; "$SDKMGR" --sdk_root="$ANDROID_HOME" "$pkg" >/dev/null 2>&1 </dev/null || manual "sdkmanager --sdk_root=\"$ANDROID_HOME\" \"$pkg\" failed — install via Android Studio SDK Manager"
|
|
129
|
+
done
|
|
130
|
+
# Prefer the in-SDK binaries from here on (see comment above).
|
|
131
|
+
IN_SDK_SDKMGR="$(ls "$ANDROID_HOME"/cmdline-tools/*/bin/sdkmanager 2>/dev/null | head -1)"
|
|
132
|
+
[ -n "$IN_SDK_SDKMGR" ] && SDKMGR="$IN_SDK_SDKMGR" && AVDMGR="$(dirname "$SDKMGR")/avdmanager"
|
|
133
|
+
|
|
134
|
+
say "Android — standard AVD ($ANDROID_AVD_NAME)"
|
|
135
|
+
if "$ANDROID_HOME/emulator/emulator" -list-avds 2>/dev/null | grep -qx "$ANDROID_AVD_NAME"; then
|
|
136
|
+
skip "AVD $ANDROID_AVD_NAME"
|
|
137
|
+
elif [ -x "$AVDMGR" ]; then
|
|
138
|
+
info "creating AVD $ANDROID_AVD_NAME from $SYS_IMAGE..."
|
|
139
|
+
echo "no" | "$AVDMGR" create avd -n "$ANDROID_AVD_NAME" -k "$SYS_IMAGE" -d "pixel_7" \
|
|
140
|
+
&& info "created $ANDROID_AVD_NAME" \
|
|
141
|
+
|| manual "avdmanager create avd -n $ANDROID_AVD_NAME -k \"$SYS_IMAGE\" -d pixel_7"
|
|
142
|
+
else manual "avdmanager not found — create an AVD in Android Studio using a Google Play API-$ANDROID_API image"; fi
|
|
143
|
+
fi
|
|
144
|
+
fi
|
|
145
|
+
|
|
146
|
+
# ============================================================ iOS
|
|
147
|
+
if [ "$PLATFORM" = "both" ] || [ "$PLATFORM" = "ios" ]; then
|
|
148
|
+
say "iOS — Xcode Command Line Tools"
|
|
149
|
+
if xcode-select -p >/dev/null 2>&1; then
|
|
150
|
+
skip "CLT/Xcode path selected ($(xcode-select -p))"
|
|
151
|
+
else
|
|
152
|
+
if confirm "Xcode Command Line Tools not found. Trigger the install now? (opens a GUI dialog)"; then
|
|
153
|
+
xcode-select --install 2>/dev/null || true
|
|
154
|
+
manual "Complete the Command Line Tools install dialog, then re-run this script."
|
|
155
|
+
else
|
|
156
|
+
manual "xcode-select --install"
|
|
157
|
+
fi
|
|
158
|
+
fi
|
|
159
|
+
|
|
160
|
+
say "iOS — WebKit DOM bridge (ios-webkit-debug-proxy for bin/wk-ios)"
|
|
161
|
+
if command -v ios_webkit_debug_proxy >/dev/null 2>&1; then
|
|
162
|
+
skip "ios-webkit-debug-proxy present"
|
|
163
|
+
elif [ -n "$BREW" ]; then
|
|
164
|
+
info "installing ios-webkit-debug-proxy..."
|
|
165
|
+
"$BREW" install ios-webkit-debug-proxy || manual "brew install ios-webkit-debug-proxy (enables bin/wk-ios JS/DOM eval in sim Safari)"
|
|
166
|
+
else
|
|
167
|
+
manual "brew install ios-webkit-debug-proxy (enables bin/wk-ios JS/DOM eval in sim Safari)"
|
|
168
|
+
fi
|
|
169
|
+
|
|
170
|
+
say "iOS — Xcode"
|
|
171
|
+
XPATH="$(xcode-select -p 2>/dev/null || true)"
|
|
172
|
+
case "$XPATH" in
|
|
173
|
+
*Xcode*.app*|*/Xcode/*) skip "full Xcode ($XPATH)";;
|
|
174
|
+
*) manual "Install Xcode from the App Store (multi-GB), then run:"
|
|
175
|
+
manual " sudo xcode-select -s /Applications/Xcode.app/Contents/Developer"
|
|
176
|
+
manual " sudo xcodebuild -license accept" ;;
|
|
177
|
+
esac
|
|
178
|
+
|
|
179
|
+
if command -v xcrun >/dev/null 2>&1 && xcodebuild -version >/dev/null 2>&1; then
|
|
180
|
+
say "iOS — runtime + simulator device ($IOS_DEVICE_NAME)"
|
|
181
|
+
RUNTIME_ID="$(xcrun simctl list runtimes 2>/dev/null | grep -i 'iOS' | grep -oE 'com\.apple\.CoreSimulator\.SimRuntime\.iOS[^ ]*' | head -1)"
|
|
182
|
+
if [ -z "$RUNTIME_ID" ]; then
|
|
183
|
+
manual "No iOS runtime installed. Install one via Xcode ▸ Settings ▸ Components (or: xcodebuild -downloadPlatform iOS), then re-run."
|
|
184
|
+
else
|
|
185
|
+
if xcrun simctl list devices 2>/dev/null | grep -q "$IOS_DEVICE_NAME"; then
|
|
186
|
+
skip "simulator device $IOS_DEVICE_NAME"
|
|
187
|
+
else
|
|
188
|
+
# devicetypes are listed NEWEST FIRST, and modern ids have non-numeric
|
|
189
|
+
# suffixes (iPhone-17-Pro, iPhone-Air, iPhone-16e) — take the first match.
|
|
190
|
+
DTYPE="$(xcrun simctl list devicetypes 2>/dev/null | grep -oE 'com\.apple\.CoreSimulator\.SimDeviceType\.iPhone-[0-9A-Za-z-]+' | head -1)"
|
|
191
|
+
[ -z "$DTYPE" ] && DTYPE="com.apple.CoreSimulator.SimDeviceType.iPhone-16"
|
|
192
|
+
info "creating simulator $IOS_DEVICE_NAME ($DTYPE)..."
|
|
193
|
+
xcrun simctl create "$IOS_DEVICE_NAME" "$DTYPE" "$RUNTIME_ID" >/dev/null 2>&1 \
|
|
194
|
+
&& info "created $IOS_DEVICE_NAME" \
|
|
195
|
+
|| manual "xcrun simctl create $IOS_DEVICE_NAME $DTYPE $RUNTIME_ID"
|
|
196
|
+
fi
|
|
197
|
+
fi
|
|
198
|
+
else
|
|
199
|
+
manual "Xcode not runnable yet — finish the Xcode steps above, then re-run scripts/setup-mobile.sh"
|
|
200
|
+
fi
|
|
201
|
+
fi
|
|
202
|
+
|
|
203
|
+
# ----------------------------------------------------------------- verify
|
|
204
|
+
say "Verifying with doctor-mobile.sh"
|
|
205
|
+
DOCTOR_ARGS=""; [ "$PLATFORM" = "ios" ] && DOCTOR_ARGS="--ios"; [ "$PLATFORM" = "android" ] && DOCTOR_ARGS="--android"
|
|
206
|
+
bash "$HERE/doctor-mobile.sh" $DOCTOR_ARGS || {
|
|
207
|
+
echo
|
|
208
|
+
echo "Some checks still fail — resolve the MANUAL steps above (Xcode / iOS runtime are the usual ones) and re-run."
|
|
209
|
+
exit 1
|
|
210
|
+
}
|
|
211
|
+
echo
|
|
212
|
+
echo "Done. Standard devices: Android AVD '$ANDROID_AVD_NAME', iOS sim '$IOS_DEVICE_NAME'."
|
|
213
|
+
echo "Target configs (data/targets/_example-sim-*.yml) reference these names."
|
|
@@ -9,7 +9,14 @@ Extract from user message:
|
|
|
9
9
|
- **time_box**: Session duration (default: 45 min, max: 45 min)
|
|
10
10
|
- **context**: Path to requirements file OR inline context text (optional)
|
|
11
11
|
|
|
12
|
-
Resolve target config
|
|
12
|
+
Resolve target config in this order:
|
|
13
|
+
1. If `--target <name>` given → load from skill `data/targets/<name>.yml`
|
|
14
|
+
2. Else if CWD contains `qa/target.yml` → load it as the target config
|
|
15
|
+
3. Else fall back to `data/targets/_default.yml`
|
|
16
|
+
|
|
17
|
+
If loaded from `qa/target.yml`, also check `qa/.env` in CWD for credential env var values before falling back to the skill root `.env`.
|
|
18
|
+
|
|
19
|
+
Read domain config from `data/domains/`.
|
|
13
20
|
|
|
14
21
|
## Step 2: Load Context (if provided)
|
|
15
22
|
|
|
@@ -11,6 +11,10 @@ playwright-cli goto <base_url>
|
|
|
11
11
|
|
|
12
12
|
## Credentials (adaptive -- uses snapshot to find form fields)
|
|
13
13
|
|
|
14
|
+
Before filling credentials, resolve their values:
|
|
15
|
+
1. If `qa/.env` exists in CWD, read it — use the values for the env var names specified in `auth.credentials.username` / `auth.credentials.password` in the target config
|
|
16
|
+
2. Otherwise read from the skill root `.env`
|
|
17
|
+
|
|
14
18
|
```bash
|
|
15
19
|
playwright-cli open <login_url>
|
|
16
20
|
playwright-cli snapshot
|
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: qa-explore-mobile
|
|
3
|
+
description: >
|
|
4
|
+
Run a full AI-driven exploratory testing session on a simulator/emulator — works for
|
|
5
|
+
BOTH a NATIVE app (the installed app is the system under test) and a WEB app loaded in
|
|
6
|
+
the real device browser (iOS Simulator Safari / Android emulator Chrome). The mode is
|
|
7
|
+
selected from the target config. Same Principal-QA mindset as /qa-explore, but the driver
|
|
8
|
+
is Maestro (via the mobile-cli shim) instead of Playwright, and the phases are adapted for
|
|
9
|
+
mobile concerns (app/browser lifecycle, rotation, on-screen keyboard, deep links, offline,
|
|
10
|
+
permissions, native a11y tree). Use when user says: "test on the simulator/emulator",
|
|
11
|
+
"explore the app on iOS/Android", "find bugs on mobile", "QA the mobile build", or provides
|
|
12
|
+
a mobile-sim target (native or web).
|
|
13
|
+
allowed-tools: Bash(node:*), Bash(adb:*), Bash(xcrun:*), Bash(maestro:*), Read, Write, Glob, Grep
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
# Mobile Exploratory Testing Session
|
|
17
|
+
|
|
18
|
+
You are a **Principal QA Engineer** running an exploratory session on a simulator/emulator.
|
|
19
|
+
This skill works in **two modes, both co-equal, selected from the target config**:
|
|
20
|
+
|
|
21
|
+
- **NATIVE mode** — the target declares an installable app (`app.bundle_id`/`app.package` +
|
|
22
|
+
`app.app_paths`/`apk_paths`, optionally a `source_repo` with `build_commands`). The
|
|
23
|
+
installed app is the system under test; you drive it directly.
|
|
24
|
+
- **WEB mode** — the target declares a browser as the app (`app: com.apple.mobilesafari` /
|
|
25
|
+
`com.android.chrome`) plus a `web.base_url`. The browser is just the driver; the web URL
|
|
26
|
+
(the app's mobile site, e.g. `https://staging.m.example.com`) is the system under test.
|
|
27
|
+
|
|
28
|
+
The mindset and reporting standards are identical to `/qa-explore` — what changes is the
|
|
29
|
+
driver (Maestro via `mobile-cli`) and the failure modes (app/browser lifecycle, on-screen
|
|
30
|
+
keyboard, rotation, permissions, native a11y tree instead of console/network).
|
|
31
|
+
|
|
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.
|
|
37
|
+
|
|
38
|
+
Why Maestro/`mobile-cli` instead of Playwright? Playwright **cannot** drive a native app at
|
|
39
|
+
all, and it **cannot** drive iOS Simulator Safari (its "webkit" is desktop macOS WebKit, not
|
|
40
|
+
the simulator's engine). The Maestro/simctl/adb route used by `mobile-cli` is the only way to
|
|
41
|
+
exercise either a real native app or the genuine mobile-browser engine.
|
|
42
|
+
|
|
43
|
+
## The Driver — mobile-cli
|
|
44
|
+
|
|
45
|
+
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):
|
|
48
|
+
|
|
49
|
+
```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.
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Command surface (mirrors playwright-cli where it makes sense):
|
|
61
|
+
|
|
62
|
+
| Command | Purpose |
|
|
63
|
+
|---|---|
|
|
64
|
+
| `set-device <udid>` | `emulator-5554` for Android, iOS sim UDID for iOS — sets platform |
|
|
65
|
+
| `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.** |
|
|
67
|
+
| `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`):
|
|
82
|
+
|
|
83
|
+
```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
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Use it whenever the a11y snapshot is not enough: exact-DOM verification (counts, attribute
|
|
91
|
+
values, hidden state), reading values the a11y tree collapses, or checking a suspected
|
|
92
|
+
rendering/JS failure. It is the same power as `playwright-cli eval`, but on the REAL iOS
|
|
93
|
+
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`.
|
|
95
|
+
|
|
96
|
+
## What's Dropped vs Playwright
|
|
97
|
+
|
|
98
|
+
Both modes are driven through the device **accessibility tree, not a DOM** — native views and
|
|
99
|
+
web content alike are surfaced to a11y (headings, links, buttons, inputs and visible text
|
|
100
|
+
become tappable refs). Versus Playwright you LOSE, in BOTH modes:
|
|
101
|
+
|
|
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.
|
|
110
|
+
|
|
111
|
+
## Mobile-Specific Heuristics (added on top of FEW HICCUPPS / SFDIPOT)
|
|
112
|
+
|
|
113
|
+
When charter-selecting heuristics in Phase 2, consider these mobile dimensions (most apply to
|
|
114
|
+
both modes; mode-specific ones are tagged):
|
|
115
|
+
|
|
116
|
+
- **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
|
+
- **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
|
+
- **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.
|
|
120
|
+
- **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.
|
|
123
|
+
|
|
124
|
+
## Session Phases
|
|
125
|
+
|
|
126
|
+
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.
|
|
128
|
+
|
|
129
|
+
| Phase | File | Summary |
|
|
130
|
+
|-------|------|---------|
|
|
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. |
|
|
139
|
+
|
|
140
|
+
## References
|
|
141
|
+
|
|
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).
|
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
# Phase 0: Mobile Session Setup (mode-aware)
|
|
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.
|
|
6
|
+
|
|
7
|
+
## Step 0 — Preflight (fail fast on a fresh machine)
|
|
8
|
+
|
|
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:
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
scripts/doctor-mobile.sh # or --ios / --android to scope to one platform
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
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`.
|
|
20
|
+
|
|
21
|
+
## Step 1 — Parse target + DETECT MODE
|
|
22
|
+
|
|
23
|
+
From the user message or the target config in `data/targets/`, extract:
|
|
24
|
+
|
|
25
|
+
- **platform**: `android` | `ios` (required).
|
|
26
|
+
- **device**: emulator/sim identifier.
|
|
27
|
+
- Android: AVD name (from `device.avd`) or `emulator-5554` if already booted.
|
|
28
|
+
- iOS: simulator name (e.g. `iPhone 17`) or UDID.
|
|
29
|
+
- **app id**: `app.bundle_id` (iOS) / `app.package` (Android).
|
|
30
|
+
- **mode** — derive it:
|
|
31
|
+
- **WEB mode** if the app id is a known browser bundle (`com.apple.mobilesafari` /
|
|
32
|
+
`com.android.chrome`) AND the config has a `web.base_url`. The browser is the driver; the
|
|
33
|
+
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:`
|
|
35
|
+
blocks document the web setup).
|
|
36
|
+
- **NATIVE mode** otherwise — i.e. a non-browser app id with installable artifacts
|
|
37
|
+
(`app.app_paths` / `app.apk_paths`), optionally a `source_repo` with `build_commands`.
|
|
38
|
+
The installed app is the SUT. Template: `data/targets/_example-native-mobile.yml`.
|
|
39
|
+
- **WEB only**: `web.base_url` / `web.start_url`.
|
|
40
|
+
- **NATIVE only**: `app.app_paths`/`apk_paths` (artifact to verify/install), and optional
|
|
41
|
+
`source_repo.path` + `source_repo.build_commands`.
|
|
42
|
+
|
|
43
|
+
Record `mode` — every later step branches on it.
|
|
44
|
+
|
|
45
|
+
## Step 2 — Boot the simulator/emulator if needed (shared)
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
# 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
|
|
55
|
+
|
|
56
|
+
# iOS — check first, only boot if no sim booted
|
|
57
|
+
xcrun simctl list devices booted
|
|
58
|
+
# If empty:
|
|
59
|
+
# xcrun simctl boot <UDID-or-name>
|
|
60
|
+
# open -a Simulator
|
|
61
|
+
```
|
|
62
|
+
|
|
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.
|
|
65
|
+
|
|
66
|
+
Set the driver state for the rest of the phase:
|
|
67
|
+
|
|
68
|
+
```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>
|
|
72
|
+
```
|
|
73
|
+
|
|
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
|
+
---
|
|
78
|
+
|
|
79
|
+
## Step 3 — NATIVE branch: verify / install / (optional rebuild) / launch
|
|
80
|
+
|
|
81
|
+
Skip this whole step in WEB mode.
|
|
82
|
+
|
|
83
|
+
### 3a. Verify the app is installed
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
# Android
|
|
87
|
+
bin/wadb shell pm list packages | grep <app.package>
|
|
88
|
+
# iOS
|
|
89
|
+
xcrun simctl get_app_container <udid> <app.bundle_id> 2>/dev/null
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### 3b. Install if missing
|
|
93
|
+
|
|
94
|
+
If not installed and the config provides an artifact path, install from it:
|
|
95
|
+
- Android: `bin/wadb install -r <app.apk_paths[...]>`
|
|
96
|
+
- iOS: `xcrun simctl install <udid> <app.app_paths[...]>`
|
|
97
|
+
|
|
98
|
+
If not installed and no artifact path is configured, **stop and ask the user** how to obtain
|
|
99
|
+
a build (point them at the target's `source_repo.build_commands` if defined). Do NOT invent a
|
|
100
|
+
build command.
|
|
101
|
+
|
|
102
|
+
### 3c. OPTIONAL refresh against latest source
|
|
103
|
+
|
|
104
|
+
**Skip unless the user passed `--rebuild` OR the session goal explicitly mentions "latest" /
|
|
105
|
+
"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
|
|
107
|
+
target config provides:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
# 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
|
|
113
|
+
|
|
114
|
+
# 2. Decide WITH the user before pulling:
|
|
115
|
+
# clean + behind → safe to pull then rebuild; dirty → ask (stash/commit/build-as-is);
|
|
116
|
+
# intentionally pinned branch → do NOT switch branches.
|
|
117
|
+
|
|
118
|
+
# 3. Run the platform build command verbatim from source_repo.build_commands
|
|
119
|
+
# (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
|
|
124
|
+
|
|
125
|
+
# 4. After install, cold-start fresh: $MCLI relaunch-clean (Android) or stop+launch (iOS)
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Always log the source state in the report** (branch + sha + clean/dirty) so readers know
|
|
129
|
+
what code the session ran against.
|
|
130
|
+
|
|
131
|
+
### 3d. Launch the app
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
$MCLI set-app <app.bundle_id OR app.package>
|
|
135
|
+
$MCLI launch
|
|
136
|
+
$MCLI snapshot # sanity check — first screen renders
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
## Step 4 — WEB branch: set browser, open URL, snapshot
|
|
142
|
+
|
|
143
|
+
Skip this step in NATIVE mode.
|
|
144
|
+
|
|
145
|
+
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
|
+
|
|
148
|
+
```bash
|
|
149
|
+
bin/wadb shell pm list packages | grep chrome # expect: package:com.android.chrome
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
If `com.android.chrome` is absent, use a Play-image AVD (or fall back to the iOS Safari
|
|
153
|
+
target) rather than assuming Chrome is installed. Do not attempt to install a browser.
|
|
154
|
+
|
|
155
|
+
```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
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
On a fresh Chrome profile you may see a one-time first-run / "Open tabs" promo bubble —
|
|
163
|
+
`mobile-cli` filters the routine promo out of snapshots, but if a full-screen
|
|
164
|
+
first-run/sign-in-to-Chrome interstitial appears, it must be dismissed once by hand.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Step 5 — Session directory (shared)
|
|
169
|
+
|
|
170
|
+
Same as qa-explore but include `platform` in the dir name:
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
output/sessions/<YYYY-MM-DD-HHmm>-<target>-<platform>/
|
|
174
|
+
charter.md
|
|
175
|
+
session-log.md
|
|
176
|
+
screenshots/
|
|
177
|
+
bugs/
|
|
178
|
+
videos/ # mobile-only — for record-start output
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Step 6 — progress.json additions (shared)
|
|
182
|
+
|
|
183
|
+
Same base schema as qa-explore. Add a `platform` key including the resolved `mode`:
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
"platform": {
|
|
187
|
+
"mode": "native",
|
|
188
|
+
"os": "android",
|
|
189
|
+
"device": "emulator-5554",
|
|
190
|
+
"app_id": "com.example.myapp",
|
|
191
|
+
"app_version": "<from `adb shell dumpsys package <pkg> | grep versionName`>",
|
|
192
|
+
"target_url": null
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
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).
|
|
198
|
+
|
|
199
|
+
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).
|
|
201
|
+
|
|
202
|
+
**Skip qa-explore's Step 6 (Playwright Test Agents bootstrap) entirely — not applicable when
|
|
203
|
+
the driver is mobile-cli/Maestro.**
|