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.
- package/README.md +85 -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/knowledge/learned-patterns.md +85 -0
- package/data/knowledge/manifest.yml +2 -1
- 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/dist/cli/index.js +156 -33
- package/dist/cli/index.js.map +1 -1
- package/dist/index.d.ts +260 -527
- package/dist/index.js +142 -12
- package/dist/index.js.map +1 -1
- package/docs/MOBILE-SETUP.md +92 -0
- package/package.json +33 -11
- package/scripts/doctor-mobile.sh +143 -0
- package/scripts/setup-mobile.sh +213 -0
- package/skills/qa-explore/SKILL.md +2 -1
- package/skills/qa-explore/phases/00-setup.md +22 -1
- package/skills/qa-explore/phases/01-auth.md +4 -0
- package/skills/qa-explore/phases/03-discovery.md +14 -0
- package/skills/qa-explore/phases/05-features.md +20 -0
- package/skills/qa-explore/phases/06-edge-cases.md +2 -0
- package/skills/qa-explore/phases/07-reporting.md +11 -0
- package/skills/qa-explore/references/playwright-agents-integration.md +126 -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 +7 -0
- package/skills/qa-target-setup/SKILL.md +12 -0
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Mobile Setup — running `/qa-explore-mobile` on a fresh Mac
|
|
2
|
+
|
|
3
|
+
The mobile skill drives **real** simulator/emulator browsers and native apps via
|
|
4
|
+
`mobile-cli` (a Maestro / `xcrun simctl` / `adb` shim). Unlike the desktop web skill
|
|
5
|
+
(`/qa-explore`, which only needs `playwright-cli`), the mobile path depends on the iOS
|
|
6
|
+
and/or Android toolchains being installed on the machine. This guide gets a clean Mac to
|
|
7
|
+
the point where a session can start.
|
|
8
|
+
|
|
9
|
+
## TL;DR
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# 1. Install everything scriptable + create standard devices (idempotent, re-runnable)
|
|
13
|
+
scripts/setup-mobile.sh # or --android / --ios, add --yes for non-interactive
|
|
14
|
+
|
|
15
|
+
# 2. Confirm the machine is ready (read-only; installs nothing)
|
|
16
|
+
scripts/doctor-mobile.sh
|
|
17
|
+
|
|
18
|
+
# 3. Run a mobile session (once doctor says READY)
|
|
19
|
+
# e.g. iOS Safari against your mobile web app:
|
|
20
|
+
# drive via bin/mcli — see the target config notes in data/targets/_example-sim-*.yml
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`scripts/setup-mobile.sh` automates everything it can and **prints clear MANUAL steps**
|
|
24
|
+
for the few things it can't (Xcode + the iOS runtime). It finishes by running the doctor.
|
|
25
|
+
|
|
26
|
+
## What gets installed / created
|
|
27
|
+
|
|
28
|
+
| Component | Needed for | Auto by `setup-mobile.sh`? |
|
|
29
|
+
|-----------|-----------|----------------------------|
|
|
30
|
+
| Homebrew | base | ✅ (offers to install) |
|
|
31
|
+
| Node ≥ 18 | runs `mobile-cli.mjs` | ✅ |
|
|
32
|
+
| **Maestro** | the driver (hierarchy/tap/input) | ✅ (`get.maestro.mobile.dev`) |
|
|
33
|
+
| **JDK 17** | Android SDK tooling | ✅ `brew install openjdk@17` |
|
|
34
|
+
| Android cmdline-tools | `sdkmanager`/`avdmanager` | ✅ `brew install --cask android-commandline-tools` |
|
|
35
|
+
| platform-tools (`adb`), `emulator` | drive Android | ✅ `sdkmanager` |
|
|
36
|
+
| Google **Play** system image (API 35) | **Chrome must be present** | ✅ `sdkmanager` |
|
|
37
|
+
| SDK licenses | unblock installs | ✅ `sdkmanager --licenses` |
|
|
38
|
+
| Android AVD `qa_pixel_api35` | a device to boot | ✅ `avdmanager create avd` |
|
|
39
|
+
| **Xcode** + CLI tools | iOS simulators at all | ⚠️ **manual** (App Store, multi-GB) |
|
|
40
|
+
| iOS runtime | a simulator OS to run | ⚠️ **manual** if none installed (Xcode ▸ Settings ▸ Components) |
|
|
41
|
+
| iOS simulator device `qa-iphone` | a device to boot | ✅ `simctl create` (once Xcode + a runtime exist) |
|
|
42
|
+
| Safari / Chrome (the browsers) | web-mode SUT | ✅ preinstalled (Safari always; Chrome via the Play image) |
|
|
43
|
+
|
|
44
|
+
### The two genuinely manual iOS steps
|
|
45
|
+
Xcode can't be reliably scripted:
|
|
46
|
+
```bash
|
|
47
|
+
# After installing Xcode from the App Store:
|
|
48
|
+
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
|
|
49
|
+
sudo xcodebuild -license accept
|
|
50
|
+
# If no iOS runtime is installed:
|
|
51
|
+
xcodebuild -downloadPlatform iOS # or Xcode ▸ Settings ▸ Components
|
|
52
|
+
```
|
|
53
|
+
Then re-run `scripts/setup-mobile.sh` — it will create the `qa-iphone` device.
|
|
54
|
+
|
|
55
|
+
## Standard device names (referenced by the target configs)
|
|
56
|
+
- Android AVD: **`qa_pixel_api35`** (Google-Play API 35) — set `ANDROID_AVD_NAME` to override.
|
|
57
|
+
- iOS sim: **`qa-iphone`** — set `IOS_DEVICE_NAME` to override.
|
|
58
|
+
|
|
59
|
+
The `data/targets/_example-sim-*.yml` configs resolve the device **by name** (not a
|
|
60
|
+
hardcoded UDID) so they're portable across machines. `00-setup` boots the named device,
|
|
61
|
+
creating it if missing.
|
|
62
|
+
|
|
63
|
+
## Why a Google **Play** (or `google_apis`) Android image
|
|
64
|
+
A stock **AOSP** system image ships **no `com.android.chrome`** — only a basic AOSP
|
|
65
|
+
browser or none. Web-mode Android targets need Chrome, so `setup-mobile.sh` installs a
|
|
66
|
+
`google_apis_playstore` image. Verify on any AVD with:
|
|
67
|
+
```bash
|
|
68
|
+
adb shell pm list packages | grep chrome
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Auth reality (web targets)
|
|
72
|
+
There is **no transferable `storage_state`** for a real device browser (unlike Playwright).
|
|
73
|
+
SSO + MFA logins are done **once, interactively, by a human** in the sim/emulator browser;
|
|
74
|
+
the device persists the browser profile across launches. Never script MFA. Never
|
|
75
|
+
`relaunch-clean` a web target (it `pm clear`s the logged-in Chrome profile). See the
|
|
76
|
+
`notes:` blocks in `data/targets/_example-sim-*.yml`.
|
|
77
|
+
|
|
78
|
+
## Troubleshooting
|
|
79
|
+
- **`doctor-mobile.sh` says NOT READY** → fix each `✗` with the printed command, or run
|
|
80
|
+
`setup-mobile.sh`, then re-run the doctor.
|
|
81
|
+
- **`JAVA_HOME` / `adb` not found mid-session** → `bin/mcli` resolves JDK 17 via
|
|
82
|
+
`/usr/libexec/java_home -v 17` and defaults `ANDROID_HOME` to `~/Library/Android/sdk`.
|
|
83
|
+
Export them explicitly if your SDK lives elsewhere.
|
|
84
|
+
- **Intel Mac** → `setup-mobile.sh` selects `x86_64` system images automatically (`arm64`
|
|
85
|
+
Macs get `arm64-v8a`).
|
|
86
|
+
- **Emulator slow/flaky to boot or Chrome absent** → fall back to the iOS Safari target;
|
|
87
|
+
both engines are independent.
|
|
88
|
+
|
|
89
|
+
## Scope
|
|
90
|
+
This covers iOS Simulator + Android Emulator (browser **and** native modes). It does **not**
|
|
91
|
+
provision physical devices, CI runners, or the desktop web path (`/qa-explore`, which only
|
|
92
|
+
needs `playwright-cli`).
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "qualiow-exploratory-testing",
|
|
3
|
-
"version": "1.
|
|
4
|
-
"description": "qualiow — AI-powered exploratory testing skills using Claude Code + Playwright CLI",
|
|
3
|
+
"version": "1.2.0",
|
|
4
|
+
"description": "qualiow — AI-powered exploratory testing skills using Claude Code + Playwright CLI (web) and Maestro/mobile-cli (iOS/Android simulators)",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
7
7
|
"types": "dist/index.d.ts",
|
|
@@ -11,14 +11,24 @@
|
|
|
11
11
|
"files": [
|
|
12
12
|
"dist/",
|
|
13
13
|
"skills/",
|
|
14
|
+
"bin/",
|
|
15
|
+
"scripts/setup-mobile.sh",
|
|
16
|
+
"scripts/doctor-mobile.sh",
|
|
14
17
|
"data/domains/*.yml",
|
|
15
18
|
"data/knowledge/",
|
|
16
19
|
"data/templates/",
|
|
17
20
|
"data/targets/_default.yml",
|
|
21
|
+
"data/targets/_example-native-mobile.yml",
|
|
22
|
+
"data/targets/_example-sim-ios-safari.yml",
|
|
23
|
+
"data/targets/_example-sim-android-chrome.yml",
|
|
24
|
+
"data/targets/_example-mobile-emulation.yml",
|
|
18
25
|
"data/targets/testers-ai.yml",
|
|
19
|
-
"docs/GETTING-STARTED.md"
|
|
26
|
+
"docs/GETTING-STARTED.md",
|
|
27
|
+
"docs/MOBILE-SETUP.md"
|
|
20
28
|
],
|
|
21
29
|
"scripts": {
|
|
30
|
+
"sync:skills": "rm -rf skills && cp -R .claude/skills skills",
|
|
31
|
+
"prebuild": "npm run sync:skills",
|
|
22
32
|
"build": "tsup",
|
|
23
33
|
"dev": "tsup --watch",
|
|
24
34
|
"test": "vitest run",
|
|
@@ -33,6 +43,10 @@
|
|
|
33
43
|
"qa",
|
|
34
44
|
"testing",
|
|
35
45
|
"playwright",
|
|
46
|
+
"maestro",
|
|
47
|
+
"mobile-testing",
|
|
48
|
+
"ios-simulator",
|
|
49
|
+
"android-emulator",
|
|
36
50
|
"ai",
|
|
37
51
|
"claude",
|
|
38
52
|
"skills",
|
|
@@ -53,18 +67,26 @@
|
|
|
53
67
|
"url": "https://github.com/willcoliveira/qualiow-exploratory-testing-skills/issues"
|
|
54
68
|
},
|
|
55
69
|
"dependencies": {
|
|
56
|
-
"@playwright/cli": "
|
|
70
|
+
"@playwright/cli": "^0.1.15",
|
|
57
71
|
"chalk": "^5.3.0",
|
|
58
|
-
"commander": "^
|
|
59
|
-
"glob": "^
|
|
72
|
+
"commander": "^15.0.0",
|
|
73
|
+
"glob": "^13.0.6",
|
|
60
74
|
"handlebars": "^4.7.8",
|
|
61
|
-
"yaml": "^2.
|
|
62
|
-
"zod": "^
|
|
75
|
+
"yaml": "^2.9.0",
|
|
76
|
+
"zod": "^4.4.3"
|
|
77
|
+
},
|
|
78
|
+
"peerDependencies": {
|
|
79
|
+
"@playwright/test": "^1.59.1"
|
|
80
|
+
},
|
|
81
|
+
"peerDependenciesMeta": {
|
|
82
|
+
"@playwright/test": {
|
|
83
|
+
"optional": true
|
|
84
|
+
}
|
|
63
85
|
},
|
|
64
86
|
"devDependencies": {
|
|
65
|
-
"@types/node": "^
|
|
87
|
+
"@types/node": "^26.1.1",
|
|
66
88
|
"tsup": "^8.4.0",
|
|
67
|
-
"typescript": "^5.
|
|
68
|
-
"vitest": "^
|
|
89
|
+
"typescript": "^5.9.3",
|
|
90
|
+
"vitest": "^4.1.10"
|
|
69
91
|
}
|
|
70
92
|
}
|
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# doctor-mobile.sh — read-only preflight for the qa-explore-mobile skill.
|
|
3
|
+
#
|
|
4
|
+
# Verifies that everything mobile-cli needs to drive iOS Simulator Safari/native and
|
|
5
|
+
# Android Emulator Chrome/native is present on THIS machine. Installs NOTHING — it only
|
|
6
|
+
# reports ✓/✗ with the exact fix command for each gap. The mobile session's 00-setup
|
|
7
|
+
# phase runs this first so a fresh machine fails fast with actionable guidance instead of
|
|
8
|
+
# a cryptic error deep in a session.
|
|
9
|
+
#
|
|
10
|
+
# Usage:
|
|
11
|
+
# scripts/doctor-mobile.sh # check both platforms
|
|
12
|
+
# scripts/doctor-mobile.sh --ios # iOS only
|
|
13
|
+
# scripts/doctor-mobile.sh --android # Android only
|
|
14
|
+
# scripts/doctor-mobile.sh --quiet # only print failures + final verdict
|
|
15
|
+
#
|
|
16
|
+
# Exit code: 0 if all REQUIRED checks for the requested platform(s) pass, 1 otherwise.
|
|
17
|
+
|
|
18
|
+
set -uo pipefail
|
|
19
|
+
|
|
20
|
+
PLATFORM="both"
|
|
21
|
+
QUIET=0
|
|
22
|
+
for arg in "$@"; do
|
|
23
|
+
case "$arg" in
|
|
24
|
+
--ios) PLATFORM="ios" ;;
|
|
25
|
+
--android) PLATFORM="android" ;;
|
|
26
|
+
--quiet) QUIET=1 ;;
|
|
27
|
+
-h|--help) sed -n '2,18p' "$0"; exit 0 ;;
|
|
28
|
+
*) echo "unknown arg: $arg" >&2; exit 2 ;;
|
|
29
|
+
esac
|
|
30
|
+
done
|
|
31
|
+
|
|
32
|
+
# ---- resolution helpers (mirror what bin/mcli does, with fallbacks) ----
|
|
33
|
+
ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}"
|
|
34
|
+
JAVA_HOME_RESOLVED="${JAVA_HOME:-}"
|
|
35
|
+
if [ -z "$JAVA_HOME_RESOLVED" ] && [ -x /usr/libexec/java_home ]; then
|
|
36
|
+
JAVA_HOME_RESOLVED="$(/usr/libexec/java_home -v 17 2>/dev/null || true)"
|
|
37
|
+
fi
|
|
38
|
+
[ -z "$JAVA_HOME_RESOLVED" ] && [ -d /opt/homebrew/opt/openjdk@17 ] && JAVA_HOME_RESOLVED=/opt/homebrew/opt/openjdk@17
|
|
39
|
+
[ -z "$JAVA_HOME_RESOLVED" ] && [ -d /usr/local/opt/openjdk@17 ] && JAVA_HOME_RESOLVED=/usr/local/opt/openjdk@17
|
|
40
|
+
MAESTRO_BIN="$HOME/.maestro/bin/maestro"
|
|
41
|
+
|
|
42
|
+
PASS=0; FAIL=0; WARN=0
|
|
43
|
+
ok() { PASS=$((PASS+1)); [ "$QUIET" = 1 ] || printf ' \033[32m✓\033[0m %s\n' "$1"; }
|
|
44
|
+
bad() { FAIL=$((FAIL+1)); printf ' \033[31m✗\033[0m %s\n ↳ fix: %s\n' "$1" "$2"; }
|
|
45
|
+
warn() { WARN=$((WARN+1)); [ "$QUIET" = 1 ] || printf ' \033[33m!\033[0m %s\n ↳ %s\n' "$1" "$2"; }
|
|
46
|
+
hdr() { [ "$QUIET" = 1 ] || printf '\n\033[1m%s\033[0m\n' "$1"; }
|
|
47
|
+
|
|
48
|
+
# ============================ COMMON ============================
|
|
49
|
+
hdr "Common"
|
|
50
|
+
if [ "$(uname -s)" = "Darwin" ]; then ok "macOS ($(sw_vers -productVersion 2>/dev/null))"; else
|
|
51
|
+
bad "not macOS — iOS sims need macOS; Android may work on Linux but is unverified here" "use a Mac"; fi
|
|
52
|
+
|
|
53
|
+
if command -v brew >/dev/null 2>&1; then ok "Homebrew ($(brew --version 2>/dev/null | head -1))"; else
|
|
54
|
+
bad "Homebrew not found" '/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'; fi
|
|
55
|
+
|
|
56
|
+
if command -v node >/dev/null 2>&1; then
|
|
57
|
+
NV="$(node -v | sed 's/^v//')"; NMAJ="${NV%%.*}"
|
|
58
|
+
if [ "${NMAJ:-0}" -ge 18 ]; then ok "Node $NV (>=18)"; else bad "Node $NV is < 18" "brew install node (or nvm install --lts)"; fi
|
|
59
|
+
else bad "Node not found" "brew install node"; fi
|
|
60
|
+
|
|
61
|
+
if [ -x "$MAESTRO_BIN" ] || command -v maestro >/dev/null 2>&1; then
|
|
62
|
+
ok "Maestro present ($MAESTRO_BIN)"
|
|
63
|
+
else bad "Maestro not found" 'curl -Ls "https://get.maestro.mobile.dev" | bash'; fi
|
|
64
|
+
|
|
65
|
+
# ============================ ANDROID ============================
|
|
66
|
+
if [ "$PLATFORM" = "both" ] || [ "$PLATFORM" = "android" ]; then
|
|
67
|
+
hdr "Android"
|
|
68
|
+
# JDK 17
|
|
69
|
+
if [ -n "$JAVA_HOME_RESOLVED" ] && [ -x "$JAVA_HOME_RESOLVED/bin/java" ]; then
|
|
70
|
+
JV="$("$JAVA_HOME_RESOLVED/bin/java" -version 2>&1 | head -1)"
|
|
71
|
+
case "$JV" in *\"17.*) ok "JDK 17 ($JAVA_HOME_RESOLVED)";; *) warn "Java found but not 17: $JV" "Android SDK tools expect JDK 17 — brew install openjdk@17";; esac
|
|
72
|
+
else bad "JDK 17 not found" "brew install openjdk@17"; fi
|
|
73
|
+
|
|
74
|
+
# SDK root
|
|
75
|
+
if [ -d "$ANDROID_HOME" ]; then ok "Android SDK root ($ANDROID_HOME)"; else
|
|
76
|
+
bad "Android SDK not found at $ANDROID_HOME" "scripts/setup-mobile.sh (installs cmdline-tools + SDK)"; fi
|
|
77
|
+
|
|
78
|
+
# adb / emulator / sdkmanager / avdmanager
|
|
79
|
+
for tuple in \
|
|
80
|
+
"platform-tools/adb:adb:sdkmanager 'platform-tools'" \
|
|
81
|
+
"emulator/emulator:emulator:sdkmanager 'emulator'" ; do
|
|
82
|
+
rel="${tuple%%:*}"; rest="${tuple#*:}"; label="${rest%%:*}"; fix="${rest#*:}"
|
|
83
|
+
if [ -x "$ANDROID_HOME/$rel" ]; then ok "$label ($ANDROID_HOME/$rel)"; else bad "$label missing" "$fix"; fi
|
|
84
|
+
done
|
|
85
|
+
SDKMGR="$(ls "$ANDROID_HOME"/cmdline-tools/*/bin/sdkmanager 2>/dev/null | head -1)"
|
|
86
|
+
AVDMGR="$(ls "$ANDROID_HOME"/cmdline-tools/*/bin/avdmanager 2>/dev/null | head -1)"
|
|
87
|
+
if [ -n "$SDKMGR" ]; then ok "sdkmanager present"; else bad "sdkmanager (cmdline-tools) missing" "brew install --cask android-commandlinetools (or Android Studio)"; fi
|
|
88
|
+
[ -n "$AVDMGR" ] && ok "avdmanager present"
|
|
89
|
+
|
|
90
|
+
# AVD existing? (Chrome needs a Google Play system image)
|
|
91
|
+
if [ -x "$ANDROID_HOME/emulator/emulator" ]; then
|
|
92
|
+
AVDS="$("$ANDROID_HOME/emulator/emulator" -list-avds 2>/dev/null)"
|
|
93
|
+
if [ -n "$AVDS" ]; then ok "AVD(s) available: $(echo "$AVDS" | tr '\n' ' ')"; else
|
|
94
|
+
bad "no Android AVD created" "scripts/setup-mobile.sh (creates a Google-Play API-35 AVD)"; fi
|
|
95
|
+
fi
|
|
96
|
+
warn "Chrome-on-Android needs a Google **Play** (or google_apis) system image" "AOSP images have no com.android.chrome — verify with: adb shell pm list packages | grep chrome"
|
|
97
|
+
fi
|
|
98
|
+
|
|
99
|
+
# ============================ iOS ============================
|
|
100
|
+
if [ "$PLATFORM" = "both" ] || [ "$PLATFORM" = "ios" ]; then
|
|
101
|
+
hdr "iOS"
|
|
102
|
+
# Command Line Tools are the floor (xcode-select/xcrun exist at all); full Xcode is
|
|
103
|
+
# still required on top of them for simulators.
|
|
104
|
+
if xcode-select -p >/dev/null 2>&1; then
|
|
105
|
+
ok "Xcode Command Line Tools path set ($(xcode-select -p))"
|
|
106
|
+
else
|
|
107
|
+
bad "Xcode Command Line Tools not installed" "xcode-select --install"
|
|
108
|
+
fi
|
|
109
|
+
if ! command -v xcrun >/dev/null 2>&1; then
|
|
110
|
+
bad "xcrun not found (no Xcode command line tools)" "xcode-select --install"
|
|
111
|
+
else
|
|
112
|
+
XPATH="$(xcode-select -p 2>/dev/null)"
|
|
113
|
+
case "$XPATH" in
|
|
114
|
+
*Xcode*.app*|*/Xcode/*) ok "Full Xcode selected ($XPATH)";;
|
|
115
|
+
*) bad "only Command Line Tools selected ($XPATH) — full Xcode is required for simulators" "install Xcode from the App Store, then: sudo xcode-select -s /Applications/Xcode.app && sudo xcodebuild -license accept";;
|
|
116
|
+
esac
|
|
117
|
+
if xcodebuild -version >/dev/null 2>&1; then ok "xcodebuild ($(xcodebuild -version 2>/dev/null | head -1))"; else
|
|
118
|
+
warn "xcodebuild not runnable (license not accepted?)" "sudo xcodebuild -license accept"; fi
|
|
119
|
+
RT="$(xcrun simctl list runtimes 2>/dev/null | grep -i 'iOS' | head -1)"
|
|
120
|
+
if [ -n "$RT" ]; then ok "iOS runtime: $(echo "$RT" | sed 's/ (.*//')"; else
|
|
121
|
+
bad "no iOS simulator runtime installed" "Xcode ▸ Settings ▸ Components ▸ install an iOS runtime (or: xcodebuild -downloadPlatform iOS)"; fi
|
|
122
|
+
# A usable simulator device
|
|
123
|
+
DEV="$(xcrun simctl list devices available 2>/dev/null | grep -iE 'iPhone' | head -1 | sed 's/^[[:space:]]*//')"
|
|
124
|
+
if [ -n "$DEV" ]; then ok "iPhone simulator available: ${DEV%% (*}"; else
|
|
125
|
+
bad "no available iPhone simulator device" "scripts/setup-mobile.sh (creates one), or: xcrun simctl create qa-iphone com.apple.CoreSimulator.SimDeviceType.iPhone-16 <runtime>"; fi
|
|
126
|
+
# Safari is always preinstalled on iOS sims — no check needed.
|
|
127
|
+
# WebKit DOM bridge (bin/wk-ios): restores JS eval / DOM assertions in sim Safari.
|
|
128
|
+
if command -v ios_webkit_debug_proxy >/dev/null 2>&1; then
|
|
129
|
+
ok "ios-webkit-debug-proxy present (bin/wk-ios DOM bridge)"
|
|
130
|
+
else
|
|
131
|
+
warn "ios-webkit-debug-proxy missing — bin/wk-ios (Safari JS/DOM eval) unavailable" "brew install ios-webkit-debug-proxy"
|
|
132
|
+
fi
|
|
133
|
+
fi
|
|
134
|
+
fi
|
|
135
|
+
|
|
136
|
+
# ============================ VERDICT ============================
|
|
137
|
+
printf '\n\033[1mSummary:\033[0m %d ok, %d warning(s), %d failure(s)\n' "$PASS" "$WARN" "$FAIL"
|
|
138
|
+
if [ "$FAIL" -gt 0 ]; then
|
|
139
|
+
printf '\033[31mNOT READY\033[0m — resolve the ✗ items above (or run: scripts/setup-mobile.sh) then re-run this doctor.\n'
|
|
140
|
+
exit 1
|
|
141
|
+
fi
|
|
142
|
+
printf '\033[32mREADY\033[0m — mobile-cli can drive the requested platform(s).\n'
|
|
143
|
+
exit 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."
|
|
@@ -7,7 +7,7 @@ description: >
|
|
|
7
7
|
and writes bug reports that executives act on.
|
|
8
8
|
Use when user says: "explore", "test this site", "find bugs", "QA check", "exploratory session",
|
|
9
9
|
or provides a URL to test.
|
|
10
|
-
allowed-tools: Bash(playwright-cli:*), Bash(npx playwright-cli:*), Read, Write, Glob, Grep
|
|
10
|
+
allowed-tools: Bash(playwright-cli:*), Bash(npx playwright-cli:*), Bash(npx playwright:*), Read, Write, Glob, Grep
|
|
11
11
|
---
|
|
12
12
|
|
|
13
13
|
# Exploratory Testing Session (v2)
|
|
@@ -68,3 +68,4 @@ Consult these as needed throughout the session:
|
|
|
68
68
|
- **`references/severity-guide.md`** — Severity definitions (Critical/High/Medium/Low) and the "when in doubt go LOWER" rule
|
|
69
69
|
- **`references/session-rules.md`** — 20 testing discipline rules: 45-min cap, one bug one report, evidence, risk-proportional time, adapt mid-session, log WHY, AI bias avoidance
|
|
70
70
|
- **`references/context-integration.md`** — How `--context` changes the session (context file, inline context, blind mode)
|
|
71
|
+
- **`references/playwright-agents-integration.md`** — Opt-in handoff to Playwright Test Agents (planner / generator / healer, 1.56+) when a reproducible bug should become a regression test. Requires the `@playwright/test` peer dependency.
|
|
@@ -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
|
|
|
@@ -87,6 +94,20 @@ Append to `session-log.md`:
|
|
|
87
94
|
[<timestamp>] [PHASE] Setup complete — session initialized
|
|
88
95
|
```
|
|
89
96
|
|
|
97
|
+
## Step 6: Optional — Bootstrap Playwright Test Agents (opt-in)
|
|
98
|
+
|
|
99
|
+
**Skip this step entirely if `@playwright/test` is not installed as a peer dep OR `playwright.config.*` is not present.** This is an additive capability for consumers who want to pair an exploratory session with the Playwright Test Agents framework (planner / generator / healer, Playwright 1.56+).
|
|
100
|
+
|
|
101
|
+
If both prerequisites are present AND the user has opted in (via target config or inline context), you MAY offer to scaffold the agent workspace:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
npx playwright init-agents --loop=claude
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
This generates agent definition files that later phases can hand off to — most usefully in phase 5 (features), where a reproducible bug can be converted into a regression test by the generator agent. See `references/playwright-agents-integration.md` for the full workflow.
|
|
108
|
+
|
|
109
|
+
**Never block the session on this step.** If the user declines, if the prerequisites are missing, or if the command fails, log a note in `session-log.md` and continue to Phase 1 normally.
|
|
110
|
+
|
|
90
111
|
**IMPORTANT: After EVERY phase completion, update progress.json and append to session-log.md.** This is how the user monitors session progress. Use this pattern at the end of each phase:
|
|
91
112
|
|
|
92
113
|
```
|
|
@@ -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
|
|
@@ -37,6 +37,20 @@ On every page during discovery:
|
|
|
37
37
|
- `playwright-cli network` -- note any failed requests (4xx, 5xx)
|
|
38
38
|
- Watch for mixed content warnings (HTTP resources on HTTPS pages)
|
|
39
39
|
|
|
40
|
+
### API-level observation helpers (optional, Playwright 1.56+)
|
|
41
|
+
|
|
42
|
+
If the session has access to the `@playwright/test` peer dep AND is running inside a Playwright test context (rare for qa-explore, common for bug-reproduction follow-ups), the following 1.56 retrieval methods can be used alongside the CLI commands above:
|
|
43
|
+
|
|
44
|
+
- `await page.consoleMessages()` — returns all console messages captured so far on the page. Useful when you need the full history rather than the most-recent tail.
|
|
45
|
+
- `await page.pageErrors()` — returns runtime page errors (uncaught exceptions). More reliable than filtering `console error` output.
|
|
46
|
+
- `await page.requests()` — returns all network requests issued by the page, with status, resource type, and timing. Use this for a single network snapshot instead of parsing `playwright-cli network` output twice.
|
|
47
|
+
|
|
48
|
+
These are OPTIONAL and only apply when exploratory testing is done from a Playwright test harness. The bash `playwright-cli` commands above remain the primary path for the skill.
|
|
49
|
+
|
|
50
|
+
### Service Workers (Playwright 1.56+)
|
|
51
|
+
|
|
52
|
+
Playwright 1.56 added Service Worker network routing. If `playwright-cli network` shows requests you cannot account for on the main document, assume a Service Worker is intercepting them and flag this as a high-risk area worth re-testing with the route filter.
|
|
53
|
+
|
|
40
54
|
## After Discovery
|
|
41
55
|
|
|
42
56
|
1. Write findings to `phase-1-discovery.md`
|
|
@@ -47,6 +47,26 @@ After testing each feature, explicitly ask:
|
|
|
47
47
|
|
|
48
48
|
If you notice an inconsistency (e.g., "Bill Pay validates but Transfer doesn't"), **follow that thread** -- don't move on. The inconsistency is a signal.
|
|
49
49
|
|
|
50
|
+
### Locator Stabilization Helpers (Playwright 1.59+, optional)
|
|
51
|
+
|
|
52
|
+
When testing a feature produces flaky snapshots because a locator isn't uniquely addressable, the following 1.59 helpers can harden the repro before you file a bug. They require the `@playwright/test` peer dep.
|
|
53
|
+
|
|
54
|
+
- `page.pickLocator()` — interactive locator picker. Use this when your current locator matches multiple elements and you need to find the one the user actually sees.
|
|
55
|
+
- `locator.normalize()` — returns a cleaned-up, canonical form of a locator. Use before copying a locator into a bug report so the reproduction is portable across runs.
|
|
56
|
+
|
|
57
|
+
These are diagnostic aids, not required steps. The bash `playwright-cli` flow above is the primary path.
|
|
58
|
+
|
|
59
|
+
### Test Agents Handoff (optional, Playwright 1.56+)
|
|
60
|
+
|
|
61
|
+
When feature testing produces a **reproducible** bug (you can trigger it twice in a row, same steps, same result), you may hand off to the Playwright Test Agents **generator** to convert the reproduction into a regression test case:
|
|
62
|
+
|
|
63
|
+
1. Finish writing the bug report with exact steps (see phase 07).
|
|
64
|
+
2. If the session's Step 6 bootstrapped Test Agents, pass the repro steps to the generator agent.
|
|
65
|
+
3. The generator produces a `tests/repro-<bug-id>.spec.ts` you can commit alongside the bug report.
|
|
66
|
+
4. The **healer** agent can later be used by the team if the test becomes flaky.
|
|
67
|
+
|
|
68
|
+
Full workflow in `../references/playwright-agents-integration.md`. This handoff is **opt-in** — it does not replace the bug report and is skipped entirely when `@playwright/test` is not installed.
|
|
69
|
+
|
|
50
70
|
## After Feature Testing
|
|
51
71
|
|
|
52
72
|
Write to `phase-3-feature-testing.md`. Include reasoning for each test.
|