agentic-mobile-kit 0.7.16 → 0.7.18
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/bin/cli.js +1 -1
- package/lib/init.js +122 -20
- package/package.json +1 -1
- package/stacks/react-native/expo/.agents/skills/THIRD_PARTY.md +1 -1
- package/stacks/react-native/expo/AGENTS.md +6 -3
- package/stacks/react-native/expo/docs/amk/expo.md +60 -4
- package/stacks/react-native/new-app/ErrorBoundary.tsx +61 -0
- package/stacks/react-native/new-app/error-boundary.tsx +30 -0
- package/stacks/react-native/template/.agents/skills/m-feature/SKILL.md +6 -5
- package/stacks/react-native/template/.agents/skills/m-prototype/SKILL.md +4 -3
- package/stacks/react-native/template/.agents/skills/m-review/SKILL.md +10 -6
- package/stacks/react-native/template/.github/workflows/e2e.yml +3 -0
- package/stacks/react-native/template/.rulesync/subagents/m-device-checker.md +2 -2
- package/stacks/react-native/template/.rulesync/subagents/m-reviewer.md +3 -3
- package/stacks/react-native/template/AGENTS.md +5 -2
- package/stacks/react-native/template/docs/amk/react-native.md +58 -3
- package/stacks/react-native/template/scripts/amk/a11y.js +78 -0
- package/stacks/react-native/template/scripts/amk/release-check.js +149 -2
- package/stacks/react-native/template/scripts/amk/report.js +78 -0
- package/stacks/react-native/template/scripts/amk/rn-check.js +435 -0
- package/stacks/react-native/template/scripts/amk/verify.sh +139 -15
- package/stacks/react-native/template/specs/_templates/design.md +16 -0
- package/stacks/react-native/template/specs/_templates/flow.yaml +8 -0
- package/stacks/react-native/template/specs/_templates/subflow.yaml +36 -0
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
# one per device, in rounds when they don't all fit, the flows split into parts when there's room
|
|
14
14
|
# --spec <id> run .maestro/<id>*.yaml and save evidence in .amk/evidence/<id>/
|
|
15
15
|
# --flow <file> run only this flow: a path in the project, or anywhere (an absolute path)
|
|
16
|
+
# --tags <list> only the flows with one of these tags in their header (tags: [smoke]), comma-separated
|
|
16
17
|
# --label <n> evidence folder name (default: the spec id, or no-spec)
|
|
17
18
|
# --flavor <name> Android product flavor to check (default: the first one in build.gradle)
|
|
18
19
|
# --scheme <name> iOS scheme to check (default: the one named like the workspace)
|
|
@@ -33,10 +34,13 @@
|
|
|
33
34
|
# AMK_IOS_TABLET (iPad simulator, or a connected iPad: name or UDID), AMK_ANDROID_TABLET_AVD (tablet emulator),
|
|
34
35
|
# AMK_ANDROID_TABLET (serial), AMK_IOS_TEAM (the Apple team ID that signs builds for real iPhones and iPads;
|
|
35
36
|
# default: the project's), AMK_PARALLEL (1 or 0: overrides plan's choice), AMK_MEMORY_GB (the memory plan
|
|
36
|
-
# counts on: this machine's; less when other emulators stay open),
|
|
37
|
-
#
|
|
37
|
+
# counts on: this machine's; less when other emulators stay open), AMK_DISK_GB (the free disk it counts on: this
|
|
38
|
+
# folder's), AMK_A11Y (0: no view-tree steps on Android, so no accessibility warnings. The steps go in a copy
|
|
39
|
+
# of each flow, .maestro/.amk-<screen>-<flow>.yaml, where ${MAESTRO_FILENAME} is the copy's name),
|
|
40
|
+
# AMK_DEVICES (how many devices plan checks at once: one per 6 GB beyond 4), AMK_DEVICE_WAIT (minutes to wait for a
|
|
38
41
|
# device in use, 30), AMK_LOCK_DIR (where runs on this machine claim devices; /tmp/agentic-mobile-kit-<user id>),
|
|
39
|
-
# AMK_EVIDENCE_KEEP (how many evidence folders stay, newest first: 5; 0 keeps them all
|
|
42
|
+
# AMK_EVIDENCE_KEEP (how many evidence folders stay, newest first: 5; 0 keeps them all; a prototype's and those of a
|
|
43
|
+
# spec in progress always stay)
|
|
40
44
|
# A device in use by another run (any project on this machine) is skipped for a free one of the same kind, or waited
|
|
41
45
|
# for when it was named or none is free.
|
|
42
46
|
# Real iPhones and iPads (iOS 17 or later): Maestro doesn't run on them, so their flows run through maestro-runner, with
|
|
@@ -49,6 +53,7 @@ mode=${1:-all}
|
|
|
49
53
|
args=$* # for the commands plan prints
|
|
50
54
|
spec=""
|
|
51
55
|
flow=""
|
|
56
|
+
tags=""
|
|
52
57
|
label=""
|
|
53
58
|
flavor=${AMK_ANDROID_FLAVOR:-}
|
|
54
59
|
only=${AMK_SCREENS:-}
|
|
@@ -59,6 +64,7 @@ while [ $# -gt 0 ]; do
|
|
|
59
64
|
case $1 in
|
|
60
65
|
--spec) spec=$2; shift 2 ;;
|
|
61
66
|
--flow) flow=$2; shift 2 ;;
|
|
67
|
+
--tags) tags=$2; shift 2 ;;
|
|
62
68
|
--label) label=$2; shift 2 ;;
|
|
63
69
|
--flavor) flavor=$2; shift 2 ;;
|
|
64
70
|
--scheme) AMK_IOS_SCHEME=$2; export AMK_IOS_SCHEME; shift 2 ;;
|
|
@@ -86,16 +92,26 @@ case $flow in "" | /* | [A-Za-z]:/*) ;; *) flow=$root/$flow ;; esac
|
|
|
86
92
|
evidence="$root/.amk/evidence/${label:-${spec:-no-spec}}"
|
|
87
93
|
mkdir -p "$evidence"
|
|
88
94
|
# Evidence stays on this machine (.amk/ is out of git): the newest AMK_EVIDENCE_KEEP folders stay, this one among
|
|
89
|
-
# them, and older ones go (5; 0 keeps them all). A prototype's folder (<id>-prototype, material for a demo)
|
|
90
|
-
#
|
|
95
|
+
# them, and older ones go (5; 0 keeps them all). A prototype's folder (<id>-prototype, material for a demo) and those
|
|
96
|
+
# of a spec in progress (its progress.md isn't done: its evidence table points there) always stay and aren't counted.
|
|
97
|
+
# Kits before 0.7.12 gave each run without a spec a folder named after its time: those go first
|
|
91
98
|
touch "$evidence"
|
|
92
99
|
keep=${AMK_EVIDENCE_KEEP:-5}
|
|
93
100
|
if [ "$keep" -gt 0 ] 2> /dev/null; then
|
|
94
|
-
|
|
101
|
+
open=$(for p in "$root"/specs/*/progress.md; do
|
|
102
|
+
case $p in (*/specs/_templates/* | */specs/current/*) continue ;; esac
|
|
103
|
+
if [ -f "$p" ] && ! grep -qi -E '^Status:[[:space:]]*done' "$p"; then basename "$(dirname "$p")"; fi
|
|
104
|
+
done)
|
|
105
|
+
all=$(ls -dt "$root"/.amk/evidence/*/ 2> /dev/null | grep -v -- '-prototype/$' | while IFS= read -r d; do
|
|
106
|
+
for s in $open; do case $(basename "$d") in ("$s" | "$s"-*) continue 2 ;; esac; done
|
|
107
|
+
echo "$d"
|
|
108
|
+
done)
|
|
109
|
+
timed='/[0-9]{8}-[0-9]{6}/$'
|
|
110
|
+
old=$({ echo "$all" | grep -v -E "$timed" || true; echo "$all" | grep -E "$timed" || true; } | grep . | tail -n +$((keep + 1)))
|
|
95
111
|
if [ -n "$old" ]; then
|
|
96
112
|
# another run on this machine (a part, a round) may have just removed the same folder
|
|
97
113
|
echo "$old" | while IFS= read -r d; do rm -r "${d:?}" 2> /dev/null || true; done
|
|
98
|
-
echo "evidence: removed $(echo "$old" |
|
|
114
|
+
echo "evidence: removed $(echo "$old" | awk -F/ 'NR <= 5 { s = s (NR > 1 ? ", " : "") $(NF - 1) } END { print s (NR > 5 ? " and " NR - 5 " more" : "") }') from .amk/evidence, keeping the newest $keep and those of specs in progress (AMK_EVIDENCE_KEEP sets how many; 0 keeps them all)"
|
|
99
115
|
fi
|
|
100
116
|
fi
|
|
101
117
|
status=0
|
|
@@ -103,10 +119,27 @@ status=0
|
|
|
103
119
|
flow_files() {
|
|
104
120
|
{
|
|
105
121
|
if [ -n "$flow" ]; then echo "$flow"
|
|
106
|
-
elif [ -n "$spec" ]; then find "$root/.maestro" -maxdepth 1 -iname "$spec*.yaml" 2>/dev/null | sort
|
|
107
|
-
else find "$root/.maestro" -maxdepth 1 -name '*.yaml' 2>/dev/null | sort
|
|
122
|
+
elif [ -n "$spec" ]; then find "$root/.maestro" -maxdepth 1 -iname "$spec*.yaml" ! -name '.amk-*' 2>/dev/null | sort
|
|
123
|
+
else find "$root/.maestro" -maxdepth 1 -name '*.yaml' ! -name '.amk-*' 2>/dev/null | sort
|
|
108
124
|
fi
|
|
109
|
-
} | awk -v k="$part_k" -v n="$part_n" '(NR - 1) % n == k - 1'
|
|
125
|
+
} | with_tags | awk -v k="$part_k" -v n="$part_n" '(NR - 1) % n == k - 1'
|
|
126
|
+
}
|
|
127
|
+
# the flows (a path a line) with one of --tags in their header: tags: [smoke, login], or one tag a line below tags:
|
|
128
|
+
with_tags() {
|
|
129
|
+
if [ -z "$tags" ]; then cat; return; fi
|
|
130
|
+
TAGS=$tags node -e '
|
|
131
|
+
const fs = require("fs");
|
|
132
|
+
const want = process.env.TAGS.split(",").map(s => s.trim()).filter(Boolean);
|
|
133
|
+
for (const f of fs.readFileSync(0, "utf8").split("\n").filter(Boolean)) {
|
|
134
|
+
const head = fs.readFileSync(f, "utf8").split(/^---\s*$/m)[0].split("\n");
|
|
135
|
+
const at = head.findIndex(l => /^tags\s*:/.test(l));
|
|
136
|
+
if (at < 0) continue;
|
|
137
|
+
const inline = head[at].replace(/^tags\s*:/, "").trim();
|
|
138
|
+
const below = [];
|
|
139
|
+
for (let i = at + 1; i < head.length && /^\s+-\s*\S/.test(head[i]); i++) below.push(head[i].replace(/^\s+-\s*/, ""));
|
|
140
|
+
const tags = (inline ? inline.replace(/^\[|\]$/g, "").split(",") : below).map(s => s.trim().replace(/^["\x27]|["\x27]$/g, ""));
|
|
141
|
+
if (tags.some(s => want.includes(s))) console.log(f);
|
|
142
|
+
}'
|
|
110
143
|
}
|
|
111
144
|
|
|
112
145
|
# the screens to check on a platform: the ones the app supports, narrowed by --screens
|
|
@@ -154,7 +187,8 @@ claim() {
|
|
|
154
187
|
unclaim() { l=$(lock_path "$1"); rm -f "$l/owner"; rmdir "$l" 2> /dev/null || true; held=$(echo "$held" | sed "s| $l||"); }
|
|
155
188
|
release() { for l in $held; do rm -f "$l/owner"; rmdir "$l" 2> /dev/null || true; done; held=""; }
|
|
156
189
|
temps="" # the temporary devices this run made for a part of the flows (--part), deleted at its end
|
|
157
|
-
|
|
190
|
+
tree_flow="" # the copy of a flow with view-tree steps (Android), next to it while it runs
|
|
191
|
+
trap 'release; drop_temps; [ -z "$tree_flow" ] || rm -f "$tree_flow"' EXIT
|
|
158
192
|
trap 'exit 130' INT TERM
|
|
159
193
|
holder() {
|
|
160
194
|
l=$(lock_path "$1")
|
|
@@ -179,8 +213,17 @@ run_flow() { # screen device app_id file name orientation
|
|
|
179
213
|
[ ! -d "$debug" ] || rm -r "$debug"
|
|
180
214
|
mkdir -p "$debug" "$out/screenshots"
|
|
181
215
|
target=$4
|
|
216
|
+
# Android: after each screenshot, Maestro saves the screen's view tree (an optional step that can't pass, half a
|
|
217
|
+
# second), from which a11y.js lists tappable elements without a label or under 48 dp. Maestro runs a copy of the flow
|
|
218
|
+
# with those steps, next to it so its subflows' paths still work, deleted after. AMK_A11Y=0 turns it off
|
|
219
|
+
tree_flow=""
|
|
220
|
+
if [ "${1%%-*}" = android ] && [ "${AMK_A11Y:-1}" != 0 ]; then
|
|
221
|
+
tree_flow=$(dirname "$4")/.amk-$1-$5.yaml
|
|
222
|
+
with_trees "$4" > "$tree_flow"
|
|
223
|
+
target=$tree_flow
|
|
224
|
+
fi
|
|
182
225
|
# Maestro reads the path in the flows below itself, so it's a native path (a Windows path in Git Bash)
|
|
183
|
-
native=$(cd "$(dirname "$
|
|
226
|
+
native=$(cd "$(dirname "$target")" && { pwd -W 2> /dev/null || pwd; })/$(basename "$target")
|
|
184
227
|
if is_real "$2"; then
|
|
185
228
|
# on a real device every flow runs inside one, first: the first launchApp maestro-runner finds in a flow decides
|
|
186
229
|
# whether it answers alerts itself, and for most it does (for permission prompts, which it can't allow ahead),
|
|
@@ -223,7 +266,8 @@ run_flow() { # screen device app_id file name orientation
|
|
|
223
266
|
pngs "$@" > "$debug/.pngs"
|
|
224
267
|
# with the app's build: on a real device, clearState installs the app again
|
|
225
268
|
MAESTRO_RUNNER_NO_TELEMETRY=1 DO_NOT_TRACK=1 npx -y "$runner" --platform ios --driver wda --device "$2" \
|
|
226
|
-
--team-id "$team" --wda-bundle-id "$3.wda" --app-file "$device_app" test -e APP_ID="$3"
|
|
269
|
+
--team-id "$team" --wda-bundle-id "$3.wda" --app-file "$device_app" test -e APP_ID="$3" \
|
|
270
|
+
-e ORIENTATION="$([ "$6" = PORTRAIT ] && echo PORTRAIT || echo landscape)" --output "$debug" \
|
|
227
271
|
--flatten "$target" > "$out/$5.log" 2>&1 || rc=$?
|
|
228
272
|
pngs "$@" | comm -13 "$debug/.pngs" - | while IFS= read -r f; do mv "$f" "$debug/"; done
|
|
229
273
|
# its takeScreenshot files, not the ones of a step that failed (<step>-after.png)
|
|
@@ -232,9 +276,18 @@ run_flow() { # screen device app_id file name orientation
|
|
|
232
276
|
fi
|
|
233
277
|
# screenshots use relative names: older Maestro saves them in the current folder, then in --test-output-dir, and
|
|
234
278
|
# from 2.7 in the debug output under <flow>/takeScreenshot/, from where they join the screen's evidence
|
|
279
|
+
# ORIENTATION: how this screen turned the device, for a flow to turn it back after another app's portrait-only screen
|
|
280
|
+
# (a call, the camera) turned it
|
|
235
281
|
(cd "$out" && maestro --device "$2" test --test-output-dir "$out" --debug-output "$debug" --flatten-debug-output \
|
|
236
|
-
-e APP_ID="$3" "$target" > "$out/$5.log" 2>&1) || rc=$?
|
|
282
|
+
-e APP_ID="$3" -e ORIENTATION="$6" "$target" > "$out/$5.log" 2>&1) || rc=$?
|
|
237
283
|
find "$debug" -path '*/takeScreenshot/*.png' -exec cp {} "$out/screenshots/" \;
|
|
284
|
+
if [ -n "$tree_flow" ]; then
|
|
285
|
+
rm -f "$tree_flow"
|
|
286
|
+
tree_flow=""
|
|
287
|
+
# Maestro named the flow's folder after the copy, a hidden name: the flow's own, as on iOS
|
|
288
|
+
[ ! -d "$debug/.amk-$1-$5" ] || [ -e "$debug/$5" ] || mv "$debug/.amk-$1-$5" "$debug/$5"
|
|
289
|
+
node scripts/amk/a11y.js "$debug" "$density" "$5" >> "$out/.a11y" 2> /dev/null || true
|
|
290
|
+
fi
|
|
238
291
|
return $rc
|
|
239
292
|
}
|
|
240
293
|
|
|
@@ -253,6 +306,39 @@ steady() {
|
|
|
253
306
|
[ "$in_row" -ge 3 ] || sleep 10
|
|
254
307
|
done
|
|
255
308
|
}
|
|
309
|
+
# why flow $2 failed on the device $1, in a line: the step and what Maestro said (on a real device, maestro-runner's report)
|
|
310
|
+
why_failed() {
|
|
311
|
+
if is_real "$1"; then
|
|
312
|
+
node -e 'try { const e = ((JSON.parse(require("fs").readFileSync(process.argv[1], "utf8")).flows || [])[0] || {}).error;
|
|
313
|
+
if (e) console.log(`with: ${e.split("\n")[0]}`); } catch {}' "$debug/report.json"
|
|
314
|
+
else
|
|
315
|
+
# the first step that failed is the innermost; Maestro's message comes after the subflows that failed around it
|
|
316
|
+
# (Run <subflow>... FAILED) and the steps onFlowComplete ran
|
|
317
|
+
awk '/\.\.\. FAILED[[:space:]]*$/ { step = $0; sub(/\.\.\. FAILED[[:space:]]*$/, "", step); sub(/^[[:space:]]+/, "", step)
|
|
318
|
+
said = ""
|
|
319
|
+
while ((getline line) > 0) if (line ~ /[^[:space:]]/ && line !~ /\.\.\. [A-Z]+[[:space:]]*$/) { said = line; break }
|
|
320
|
+
sub(/^[[:space:]]+/, "", said)
|
|
321
|
+
printf "at \"%s\"%s\n", step, (said == "" ? "" : ": " said); exit }' "$out/$2.log"
|
|
322
|
+
fi
|
|
323
|
+
}
|
|
324
|
+
# the screen when a flow failed on the device $1: the last screenshot of a failing step (Maestro's, or maestro-runner's),
|
|
325
|
+
# not one of the view-tree steps', which Maestro takes too
|
|
326
|
+
failure_shot() {
|
|
327
|
+
if is_real "$1"; then find "$debug" -name '*-after.png' | sort | tail -n 1
|
|
328
|
+
else find "$debug" -path '*/screenshots/*.png' ! -name '*amk-view-tree*' | sort | tail -n 1; fi
|
|
329
|
+
}
|
|
330
|
+
# flow $1 with a step after each screenshot (takeScreenshot: <name>) that makes Maestro save the screen's view tree,
|
|
331
|
+
# named after the screenshot: it waits 1 ms for an element that isn't there, and doesn't fail the flow
|
|
332
|
+
with_trees() {
|
|
333
|
+
awk '{ print }
|
|
334
|
+
/^[[:space:]]*-[[:space:]]*takeScreenshot:[[:space:]]*[^[:space:]#]/ {
|
|
335
|
+
match($0, /^[[:space:]]*/); ind = substr($0, 1, RLENGTH)
|
|
336
|
+
name = $0; sub(/^[[:space:]]*-[[:space:]]*takeScreenshot:[[:space:]]*/, "", name); sub(/[[:space:]]+#.*$/, "", name)
|
|
337
|
+
sub(/[[:space:]]+$/, "", name) # and a Windows line end
|
|
338
|
+
gsub(/["\047]/, "", name); gsub(/[^A-Za-z0-9_-]/, "-", name)
|
|
339
|
+
printf "%s- extendedWaitUntil:\n%s visible:\n%s id: \"amk-view-tree-%s\"\n%s timeout: 1\n%s optional: true\n", ind, ind, ind, name, ind, ind
|
|
340
|
+
}' "$1"
|
|
341
|
+
}
|
|
256
342
|
run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to turn it) [again]
|
|
257
343
|
out="$evidence/$1"
|
|
258
344
|
# a part of the flows has a folder of its own in the screen's, as the parts run at the same time: part 1 clears what
|
|
@@ -272,9 +358,14 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
|
|
|
272
358
|
mkdir -p "$out"
|
|
273
359
|
# this run's screenshots are the ones newer than this; the status before it, for running the screen again
|
|
274
360
|
: > "$out/.started"
|
|
361
|
+
# each flow's result, and what the view trees showed (Android), for the report
|
|
362
|
+
: > "$out/.flows"
|
|
363
|
+
: > "$out/.a11y"
|
|
364
|
+
[ "${1%%-*}" != android ] || density=$(device_density "$2")
|
|
275
365
|
[ -n "${5:-}" ] || before=$status
|
|
276
366
|
files=$(flow_files)
|
|
277
367
|
if [ -z "$files" ]; then
|
|
368
|
+
[ -z "$tags" ] || echo " $1: no flow has the tag $tags, so this is a check that the app opens"
|
|
278
369
|
# launchApp returns before the app has drawn, and a splash screen stays up until the JavaScript has loaded:
|
|
279
370
|
# a fixed wait (for text that never appears), then for the screen to settle, so the screenshot shows the app
|
|
280
371
|
printf 'appId: %s\n---\n- launchApp\n- extendedWaitUntil:\n visible: "agentic-mobile-kit: waiting for the app to draw"\n timeout: 5000\n optional: true\n- waitForAnimationToEnd\n- takeScreenshot: smoke-launch\n' "$3" > "$out/smoke.yaml"
|
|
@@ -285,7 +376,8 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
|
|
|
285
376
|
for f in $files; do
|
|
286
377
|
total=$((total + 1))
|
|
287
378
|
name=$(basename "$f" .yaml)
|
|
288
|
-
ok=0
|
|
379
|
+
ok=0 why="" shot=""
|
|
380
|
+
: > "$out/.flow-started"
|
|
289
381
|
run_flow "$1" "$2" "$3" "$f" "$name" "$4" || ok=$?
|
|
290
382
|
# Maestro now and then stops before a flow starts (it printed nothing), and an emulator sometimes drops its adb
|
|
291
383
|
# connection for a moment: run the flow once more (after reconnecting)
|
|
@@ -322,6 +414,19 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
|
|
|
322
414
|
echo " $1: flow $name failed, see ${out#"$root"/}/$name.log and Maestro's own log ${debug#"$root"/}/maestro.log"
|
|
323
415
|
status=1
|
|
324
416
|
fi
|
|
417
|
+
if [ "$ok" != 0 ]; then
|
|
418
|
+
why=$(why_failed "$2" "$name" | tr '\t' ' ')
|
|
419
|
+
# a step the device dropped out of has no FAILED line: say so, or it reads as the flow's own failure
|
|
420
|
+
[ -n "$why" ] || [ "${1%%-*}" != android ] || ! lost_device "$out/$name.log" ||
|
|
421
|
+
why="when the device went offline, on each try (an emulator under load drops out: check again with fewer devices open)"
|
|
422
|
+
shot=$(failure_shot "$2")
|
|
423
|
+
[ -z "$why" ] || echo " failed $why"
|
|
424
|
+
[ -z "$shot" ] || echo " the screen when it failed: ${shot#"$root"/}"
|
|
425
|
+
fi
|
|
426
|
+
# for the report: the flow, its result, why it failed, the screenshots it took, and the screen when it failed
|
|
427
|
+
printf '%s\t%s\t%s\t%s\t%s\n' "$name" "$([ "$ok" = 0 ] && echo passed || echo failed)" "$why" \
|
|
428
|
+
"$(find "$out" -name '*.png' -newer "$out/.flow-started" | sed "s|^$evidence/||" | sort | tr '\n' ',' | sed 's/,$//')" \
|
|
429
|
+
"${shot#"$evidence"/}" >> "$out/.flows"
|
|
325
430
|
done
|
|
326
431
|
# iOS saves a turned screen's screenshots at the device's upright size, with a tag that tells viewers to turn them,
|
|
327
432
|
# and some viewers ignore it: save them turned (through BMP, which keeps no tag), so every viewer shows the screen
|
|
@@ -351,6 +456,8 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
|
|
|
351
456
|
fi
|
|
352
457
|
shots=$(find "$out" -name '*.png' | wc -l | tr -d ' ')
|
|
353
458
|
echo "$1: flows $passed/$total passed, $shots screenshots in ${out#"$root"/}"
|
|
459
|
+
a11y=$(grep -c . "$out/.a11y" 2> /dev/null || true)
|
|
460
|
+
[ "${a11y:-0}" = 0 ] || echo " $1: $a11y accessibility warning$([ "$a11y" = 1 ] || echo s) on the flows' screens (controls without a label, tap areas under 48 dp): see the report"
|
|
354
461
|
if [ "$shots" = 0 ]; then
|
|
355
462
|
echo " $1: no screenshots were saved, so there's no evidence; treating this as a failure"
|
|
356
463
|
status=1
|
|
@@ -365,6 +472,7 @@ run_flows() { # screen device app_id orientation (PORTRAIT, or LANDSCAPE_LEFT to
|
|
|
365
472
|
case $was in upright) other=landscape ;; *) other=portrait ;; esac
|
|
366
473
|
echo " $1: the app sets its orientation in its code (${set_in% }), which can keep it $was. If it's meant to stay $was, take $other out of its native settings (UISupportedInterfaceOrientations in Info.plist, screenOrientation in AndroidManifest.xml) and this screen isn't checked any more; otherwise change that code"
|
|
367
474
|
fi
|
|
475
|
+
echo " $1: a flow that leaves the app (a call, the camera, a picker) comes back $was when the other app's screen turned the device: turn it back after that step with - setOrientation: \${ORIENTATION}"
|
|
368
476
|
fi
|
|
369
477
|
}
|
|
370
478
|
|
|
@@ -416,6 +524,11 @@ quick() {
|
|
|
416
524
|
cat "$evidence/lint.log" "$evidence/typecheck.log" "$evidence/test.log" 2> /dev/null | sed -n -E '/^(lint|typecheck|test): /,/^[^ ]/p' | head -n 20
|
|
417
525
|
status=1
|
|
418
526
|
fi
|
|
527
|
+
# React Native mistakes in the lines this branch changed (the app's rules list them): its problems fail quick, its
|
|
528
|
+
# warnings don't
|
|
529
|
+
node scripts/amk/rn-check.js > "$evidence/rn-check.log" 2>&1 || status=1
|
|
530
|
+
head -n 40 "$evidence/rn-check.log"
|
|
531
|
+
[ "$(wc -l < "$evidence/rn-check.log")" -le 40 ] || echo " … all of it in ${evidence#"$root"/}/rn-check.log"
|
|
419
532
|
}
|
|
420
533
|
|
|
421
534
|
ios() {
|
|
@@ -639,6 +752,10 @@ device_width() {
|
|
|
639
752
|
/Physical size/ { split($2, s, "x"); w = s[1] + 0 < s[2] + 0 ? s[1] : s[2] } /Physical density/ { d = $2 }
|
|
640
753
|
END { if (d) print int(w * 160 / d) }'
|
|
641
754
|
}
|
|
755
|
+
# the screen density (dpi) of the Android device $1: the one set for it, else its own
|
|
756
|
+
device_density() {
|
|
757
|
+
"$adb" -s "$1" shell 'wm size; wm density' 2> /dev/null | tr -d '\r' | awk -F': ' '/Override density/ { o = $2 } /Physical density/ { p = $2 } END { print o ? o : p }'
|
|
758
|
+
}
|
|
642
759
|
avd_home=${ANDROID_AVD_HOME:-${ANDROID_USER_HOME:-$HOME/.android}/avd}
|
|
643
760
|
# an AVD's folder: its .ini names it (an AVD can be renamed, and keep its folder), else <name>.avd
|
|
644
761
|
avd_dir() { d=$(sed -n 's/^path=//p' "$avd_home/$1.ini" 2> /dev/null | head -n 1); echo "${d:-$avd_home/$1.avd}"; }
|
|
@@ -915,6 +1032,7 @@ plan() {
|
|
|
915
1032
|
console.log(Math.round(os.totalmem() / 2 ** 30), Math.round(s.bavail * s.bsize / 2 ** 30))')
|
|
916
1033
|
mem=$1
|
|
917
1034
|
case ${AMK_MEMORY_GB:-x} in *[!0-9]*) ;; *) mem=$AMK_MEMORY_GB ;; esac
|
|
1035
|
+
case ${AMK_DISK_GB:-x} in *[!0-9]*) ;; *) set -- "$1" "$AMK_DISK_GB" ;; esac
|
|
918
1036
|
have="$mem GB of memory, $2 GB free disk, Maestro $(maestro_version)"
|
|
919
1037
|
# the devices to check, phones first and the platforms mixed, so a round of two has one of each
|
|
920
1038
|
# (each platform's screens are read first: grep -q stops reading at its first match, and a writer still going then
|
|
@@ -1014,5 +1132,11 @@ case $mode in
|
|
|
1014
1132
|
*) echo "verify: unknown mode $mode (quick, ios, android, all, build or plan)"; exit 2 ;;
|
|
1015
1133
|
esac
|
|
1016
1134
|
|
|
1135
|
+
# the run's report, from every screen checked so far: other devices, parts and rounds add theirs
|
|
1136
|
+
case $mode in
|
|
1137
|
+
ios | android | all) if [ -n "$(find "$evidence" -name .flows 2> /dev/null | head -n 1)" ] && node scripts/amk/report.js "$evidence" > /dev/null 2>&1; then
|
|
1138
|
+
echo "Report: ${evidence#"$root"/}/report.md (each flow's result, why one failed, and its screenshots)"
|
|
1139
|
+
fi ;;
|
|
1140
|
+
esac
|
|
1017
1141
|
echo "Evidence: ${evidence#"$root"/}/ (open the screenshots: a tool saying 'passed' isn't proof)"
|
|
1018
1142
|
exit $status
|
|
@@ -1,5 +1,21 @@
|
|
|
1
1
|
# <ID>: design
|
|
2
2
|
|
|
3
|
+
## UI/UX level
|
|
4
|
+
|
|
5
|
+
<!-- For a feature with screens: the level the user confirmed before the design, and the date (n/a without screens).
|
|
6
|
+
Simple (the default): clean, minimal and functional. The app's own components and theme, or the platform's
|
|
7
|
+
standard ones; a clear hierarchy with room around it; standard navigation, lists and forms; motion only where
|
|
8
|
+
the platform gives it (screen transitions, pressed states).
|
|
9
|
+
Mixed: Simple, with modern touches where they help: cards with rounded corners and soft shadows, an accent colour
|
|
10
|
+
and icons, subtle transitions and feedback when something changes, skeletons while loading, friendly empty and
|
|
11
|
+
error states.
|
|
12
|
+
Premium: polished and visually engaging, following current iOS and Android design (Apple's Human Interface
|
|
13
|
+
Guidelines, Material 3): one type scale, spacing and colour tokens, dark mode, purposeful motion (shared
|
|
14
|
+
transitions, gestures), haptics on key actions, illustrations for empty states. It takes longer, and may need a
|
|
15
|
+
library (animation, haptics): ask before adding one.
|
|
16
|
+
Every level meets the same requirements and the screen rules (accessibility, large text, Reduce Motion, both
|
|
17
|
+
platforms): the level changes how the screens look and move, not what they do. -->
|
|
18
|
+
|
|
3
19
|
## Existing code to reuse
|
|
4
20
|
|
|
5
21
|
<!-- Search first: components, hooks, API clients and helpers this change will use instead of writing new ones. -->
|
|
@@ -1,11 +1,19 @@
|
|
|
1
1
|
# Copy to .maestro/<id>.yaml. verify.sh runs it on iOS and Android and keeps the screenshots as evidence.
|
|
2
2
|
# Tap by testID (give every interactive element one); tapping by text can hit a label instead of the control.
|
|
3
|
+
# Each scenario of specs/<id>/requirements.md gets a "# Scenario <n>: <name>" comment above its steps, an assertion for
|
|
4
|
+
# its THEN and a screenshot: rn-check (in verify.sh quick) checks that, and Maestro's syntax, before any build.
|
|
5
|
+
# Steps several flows share (logging in, skipping onboarding, a permission prompt) and resetting test data go in
|
|
6
|
+
# .maestro/subflows/ (specs/_templates/subflow.yaml), run with "- runFlow: subflows/<name>.yaml".
|
|
3
7
|
# Test logins: ${MAESTRO_EMAIL}, ${MAESTRO_PASSWORD} and the like, set in .maestro/.env.local, which isn't committed.
|
|
4
8
|
# On a real iPhone (maestro-runner): text with an apostrophe can't be searched for (use a testID), and permission
|
|
5
9
|
# prompts aren't answered for the flow (tapOn: { text: "Allow", optional: true }). setAirplaneMode works only on an
|
|
6
10
|
# iPhone in English (it looks for "Airplane Mode" in Settings) and leaves Settings in front: launchApp: { stopApp: false }
|
|
7
11
|
# brings the app back. verify.sh opens Settings on its main page before such a flow, and turns airplane mode off after.
|
|
12
|
+
# A flow that leaves the app (a call, the camera, a system picker) can come back upright on a turned screen: the other
|
|
13
|
+
# app's portrait-only screen turned the device. Turn it back after that step with "- setOrientation: ${ORIENTATION}",
|
|
14
|
+
# which verify.sh sets to the screen's (run by hand: maestro test -e ORIENTATION=PORTRAIT <flow>).
|
|
8
15
|
appId: ${APP_ID} # set by verify.sh
|
|
16
|
+
# tags: [smoke] # optional: verify.sh --tags smoke checks only the flows with one of the tags
|
|
9
17
|
---
|
|
10
18
|
- launchApp:
|
|
11
19
|
clearState: true
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Copy to .maestro/subflows/<name>.yaml for steps several flows share: logging in, skipping onboarding, answering a
|
|
2
|
+
# permission prompt. A flow runs it with "- runFlow: subflows/<name>.yaml". verify.sh runs only the flows directly in
|
|
3
|
+
# .maestro/, not the subflows below it. This one logs in with the test account from .maestro/.env.local (MAESTRO_EMAIL,
|
|
4
|
+
# MAESTRO_PASSWORD), which isn't committed.
|
|
5
|
+
appId: ${APP_ID}
|
|
6
|
+
---
|
|
7
|
+
- tapOn:
|
|
8
|
+
id: "login-email"
|
|
9
|
+
- inputText: ${MAESTRO_EMAIL}
|
|
10
|
+
- tapOn:
|
|
11
|
+
id: "login-password"
|
|
12
|
+
- inputText: ${MAESTRO_PASSWORD}
|
|
13
|
+
- tapOn:
|
|
14
|
+
id: "login-submit"
|
|
15
|
+
- extendedWaitUntil:
|
|
16
|
+
visible:
|
|
17
|
+
id: "home-screen"
|
|
18
|
+
timeout: 15000
|
|
19
|
+
|
|
20
|
+
# Test data: so a flow starts from the same data every run, reset it through the app's API first. Put a script like
|
|
21
|
+
# this in .maestro/subflows/reset-data.js, and run it at the start of the flow:
|
|
22
|
+
# - runScript:
|
|
23
|
+
# file: subflows/reset-data.js
|
|
24
|
+
# env:
|
|
25
|
+
# API_URL: ${MAESTRO_API_URL}
|
|
26
|
+
# TEST_TOKEN: ${MAESTRO_TEST_TOKEN}
|
|
27
|
+
# Maestro runs it with its own JavaScript, which has http (docs.maestro.dev: Make HTTP requests) and reads the env
|
|
28
|
+
# values as plain variables. MAESTRO_API_URL and MAESTRO_TEST_TOKEN go in .maestro/.env.local. Point it at the app's
|
|
29
|
+
# own test-only endpoint and test account, never at production data.
|
|
30
|
+
#
|
|
31
|
+
# /* global http, API_URL, TEST_TOKEN */
|
|
32
|
+
# const response = http.post(`${API_URL}/test/reset`, {
|
|
33
|
+
# headers: { Authorization: `Bearer ${TEST_TOKEN}`, 'Content-Type': 'application/json' },
|
|
34
|
+
# body: JSON.stringify({ account: 'e2e' }),
|
|
35
|
+
# });
|
|
36
|
+
# if (!response.ok) throw new Error(`resetting the test data failed: ${response.status} ${response.body}`);
|