agentic-mobile-kit 0.7.17 → 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 +60 -8
- package/package.json +1 -1
- package/stacks/react-native/expo/AGENTS.md +3 -2
- 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 +1 -1
- 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/AGENTS.md +3 -2
- package/stacks/react-native/template/scripts/amk/a11y.js +78 -0
- package/stacks/react-native/template/scripts/amk/report.js +78 -0
- package/stacks/react-native/template/scripts/amk/rn-check.js +146 -17
- package/stacks/react-native/template/scripts/amk/verify.sh +134 -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
package/bin/cli.js
CHANGED
|
@@ -50,7 +50,7 @@ function main([cmd, ...rest]) {
|
|
|
50
50
|
printSummary(init(process.cwd(), { tools: list('tools'), ci: list('ci'), pm: flag('pm') }));
|
|
51
51
|
});
|
|
52
52
|
} else if (cmd === 'sync') {
|
|
53
|
-
run('sync', () => printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') })));
|
|
53
|
+
run('sync', () => { if (printSync(sync(process.cwd(), { from: flag('from'), ci: list('ci'), pm: flag('pm') }))) process.exitCode = 1; });
|
|
54
54
|
} else if (cmd === 'uninstall') {
|
|
55
55
|
run('uninstall', () => printUninstall(uninstall(process.cwd(), { from: flag('from'), pm: flag('pm') })));
|
|
56
56
|
} else if (cmd === 'doctor') {
|
package/lib/init.js
CHANGED
|
@@ -470,6 +470,34 @@ function merge3(current, base, kitNew, from) {
|
|
|
470
470
|
return { text: r.stdout, conflicts: r.status };
|
|
471
471
|
}
|
|
472
472
|
|
|
473
|
+
// AGENTS.md's kit section as the team left it, merged with the kit's new one: a team's edit inside it (the screens it
|
|
474
|
+
// builds for, say) stays. A line the kit fills in with what it finds (the versions, the package manager, the app's
|
|
475
|
+
// checks) is the kit's, whatever it says now: there the old version's line, filled in today, stands in for the team's.
|
|
476
|
+
// The screens are a team's decision, so a line with them counts as an edit. The marker lines are the kit's
|
|
477
|
+
function mergeSection(mine, rawOld, kitOld, kitNew, from) {
|
|
478
|
+
const lines = s => s.replace(/\n$/, '').split('\n');
|
|
479
|
+
const [raw, base, theirs] = [rawOld, kitOld, kitNew].map(lines);
|
|
480
|
+
const found = raw.length !== base.length ? [] : raw.map((l, i) => /\{\{\w+\}\}/.test(l) && !l.includes('{{SCREENS}}')
|
|
481
|
+
&& [new RegExp(`^${l.split(/\{\{\w+\}\}/).map(s => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*')}$`), base[i]]).filter(Boolean);
|
|
482
|
+
const ours = lines(mine).map(l => (base.includes(l) ? l : (found.find(([re]) => re.test(l)) || [null, l])[1]));
|
|
483
|
+
const inner = a => `${a.slice(1, -1).join('\n')}\n`;
|
|
484
|
+
const { text, conflicts } = merge3(inner(ours), inner(base), inner(theirs), from);
|
|
485
|
+
return { text: !conflicts && text === inner(theirs) ? kitNew : `${theirs[0]}\n${text}${theirs[theirs.length - 1]}\n`, conflicts };
|
|
486
|
+
}
|
|
487
|
+
|
|
488
|
+
// whether a merged script still parses (two edits can merge cleanly into one that doesn't): sh -n for shell scripts
|
|
489
|
+
// and git hooks, node --check for JavaScript. Without sh on the PATH (Windows without Git's), shell isn't checked
|
|
490
|
+
function parses(rel, text) {
|
|
491
|
+
const shell = rel.endsWith('.sh') || rel.startsWith('.githooks/');
|
|
492
|
+
if (!shell && !/\.[cm]?js$/.test(rel)) return true;
|
|
493
|
+
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'amk-parse-'));
|
|
494
|
+
const file = path.join(dir, path.basename(rel));
|
|
495
|
+
fs.writeFileSync(file, text);
|
|
496
|
+
const r = spawnSync(shell ? 'sh' : process.execPath, [shell ? '-n' : '--check', file], { encoding: 'utf8' });
|
|
497
|
+
fs.rmSync(dir, { recursive: true, force: true });
|
|
498
|
+
return Boolean(r.error) || r.status === 0;
|
|
499
|
+
}
|
|
500
|
+
|
|
473
501
|
// Git hook managers a project may already use. The kit's hooks then run from theirs and core.hooksPath stays theirs:
|
|
474
502
|
// two tools setting it undo each other on every install (husky's prepare script runs after the kit's postinstall).
|
|
475
503
|
const KIT_HOOKS = ['pre-commit', 'pre-push'];
|
|
@@ -489,7 +517,10 @@ const forwarder = h => `#!/bin/sh\n${FORWARD} .git/hooks/${h}, which core.hooksP
|
|
|
489
517
|
const localHooksPath = cwd => {
|
|
490
518
|
let v = '';
|
|
491
519
|
try { v = git(cwd, 'config', '--local', 'core.hooksPath'); } catch {}
|
|
492
|
-
|
|
520
|
+
v = v && path.posix.normalize(v.replace(/\\/g, '/')).replace(/\/+$/, '');
|
|
521
|
+
// the project's own .githooks as a full path (git config core.hooksPath "$PWD/.githooks") is the kit's folder too
|
|
522
|
+
const real = p => { try { return fs.realpathSync(p); } catch { return path.resolve(p); } };
|
|
523
|
+
return v && path.isAbsolute(v) && real(v) === real(path.join(cwd, '.githooks')) ? '.githooks' : v;
|
|
493
524
|
};
|
|
494
525
|
|
|
495
526
|
function hookManager(cwd, pkg) {
|
|
@@ -662,10 +693,11 @@ function finish(cwd, { pkg, deps, tools, files, stack, skipGenerate }) {
|
|
|
662
693
|
const gi = path.join(cwd, '.gitignore');
|
|
663
694
|
const giText = readIf(gi) || '';
|
|
664
695
|
// Expo: ios/ and android/ are generated by prebuild, so they stay out of git too
|
|
665
|
-
|
|
696
|
+
// .maestro/.amk-*: the copies of flows with view-tree steps that verify.sh runs on Android, there only while they run
|
|
697
|
+
const ignored = ['.env', '.env.*', '!.env*.example', '!.env*.sample', '!.env*.template', '.amk/', '.maestro/.amk-*', ...(stack === 'expo' ? ['/ios', '/android'] : [])];
|
|
666
698
|
const missing = ignored.filter(l => !giText.split('\n').includes(l));
|
|
667
699
|
if (missing.length) {
|
|
668
|
-
fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs)${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
|
|
700
|
+
fs.writeFileSync(gi, `${giText.replace(/\n*$/, giText ? '\n' : '')}\n# agentic-mobile-kit: secrets stay out of git; .amk/ holds local evidence (screenshots, logs), .maestro/.amk-* the flows verify.sh is running${stack === 'expo' ? '; ios/ and android/ are generated' : ''}\n${missing.join('\n')}\n`);
|
|
669
701
|
done.merged.push('.gitignore');
|
|
670
702
|
}
|
|
671
703
|
|
|
@@ -834,7 +866,7 @@ function sync(cwd, opts = {}) {
|
|
|
834
866
|
const oldValues = { ...values, ...ciTexts(hadCi) };
|
|
835
867
|
const tools = installedTools(cwd);
|
|
836
868
|
const targets = tools.flatMap(t => TOOLS[t]);
|
|
837
|
-
const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], removed: [], kept: [] };
|
|
869
|
+
const report = { moved: [], updated: [], added: [], merged: [], conflicts: [], byHand: [], removed: [], kept: [] };
|
|
838
870
|
const newFiles = stackFiles(opts.template || TEMPLATE, stack, deps);
|
|
839
871
|
// an install from before 0.7.0: the kit's files move to the new folders first, so the team's edits come along.
|
|
840
872
|
// Other files in the old folders may be the app's own, so they stay where they are.
|
|
@@ -862,8 +894,14 @@ function sync(cwd, opts = {}) {
|
|
|
862
894
|
const kitOld = oldFiles.has(rel) && wasInstalled(rel) ? kitText(oldFiles.get(rel), rel, oldValues, targets) : null;
|
|
863
895
|
const current = projectText(cwd, rel, targets);
|
|
864
896
|
if (rel === 'AGENTS.md' || rel === 'CLAUDE.md') {
|
|
865
|
-
|
|
866
|
-
|
|
897
|
+
// the team's edits inside the kit's section stay, merged like any file's
|
|
898
|
+
const mine = rel === 'AGENTS.md' && exact && kitOld !== null && current !== null && (current.match(MARKERS) || [])[0];
|
|
899
|
+
const { text: section, conflicts } = mine ? mergeSection(mine, fs.readFileSync(oldFiles.get(rel), 'utf8'), kitOld, kitNew, from) : { text: kitNew, conflicts: 0 };
|
|
900
|
+
const next = current === null ? kitNew : rel === 'AGENTS.md' ? mergeAgents(current, section) : mergeClaude(current);
|
|
901
|
+
if (next === current) continue;
|
|
902
|
+
fs.writeFileSync(path.join(cwd, rel), next);
|
|
903
|
+
if (section === kitNew) report.updated.push(rel);
|
|
904
|
+
else (conflicts ? report.conflicts : report.merged).push(`${rel} (your edits inside the kit's section)`);
|
|
867
905
|
continue;
|
|
868
906
|
}
|
|
869
907
|
if (current === null) {
|
|
@@ -879,6 +917,14 @@ function sync(cwd, opts = {}) {
|
|
|
879
917
|
if (kitOld === kitNew || PROJECT_DOCS.includes(rel)) continue;
|
|
880
918
|
// without an exact base, an old unchanged file would look like your edit and be kept: show every difference instead
|
|
881
919
|
const { text, conflicts } = merge3(current, exact ? kitOld : '', kitNew, from);
|
|
920
|
+
// markers, or a merge that no longer parses, would stop a script, a hook, a workflow or a config from working (and
|
|
921
|
+
// every check with it): those get the kit's version, and the team's goes beside it to bring its changes back
|
|
922
|
+
if (!rel.endsWith('.md') && (conflicts || !parses(rel, text))) {
|
|
923
|
+
fs.copyFileSync(path.join(cwd, rel), path.join(cwd, `${rel}.mine`));
|
|
924
|
+
writeKitFile(cwd, rel, kitNew);
|
|
925
|
+
report.byHand.push(rel);
|
|
926
|
+
continue;
|
|
927
|
+
}
|
|
882
928
|
writeKitFile(cwd, rel, text);
|
|
883
929
|
(conflicts ? report.conflicts : report.merged).push(rel);
|
|
884
930
|
}
|
|
@@ -1014,13 +1060,19 @@ function printSync({ report, warnings = [], from, to, changed, generated, genera
|
|
|
1014
1060
|
log(from === to ? `agentic-mobile-kit is already ${to}.` : `agentic-mobile-kit updated from ${from} to ${to}.`);
|
|
1015
1061
|
const lines = [
|
|
1016
1062
|
['moved to the new folders', report.moved || []], ['updated', report.updated], ['added', report.added], ['removed', report.removed],
|
|
1017
|
-
['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts],
|
|
1063
|
+
['merged with your changes', report.merged], ['CONFLICTS, resolve the <<<<<<< markers', report.conflicts],
|
|
1064
|
+
['CONFLICTS where markers would stop the file from working, so the kit\'s version is in place: bring your changes back from <file>.mine, then delete it', report.byHand || []],
|
|
1065
|
+
['left alone', report.kept],
|
|
1018
1066
|
];
|
|
1019
1067
|
for (const [label, files] of lines) if (files.length) log(` ${label}: ${files.join(', ')}`);
|
|
1020
1068
|
if (!changed) log(' Nothing changed.');
|
|
1021
1069
|
for (const w of warnings) log(` ! ${w}`);
|
|
1022
1070
|
if (!generated) log(` ! could not generate tool configs; run: npx -y ${RULESYNC} generate\n${generateError.replace(/^/gm, ' ')}`);
|
|
1023
|
-
|
|
1071
|
+
// a conflict left is an update not finished: said last, and the command fails
|
|
1072
|
+
const open = report.conflicts.length + (report.byHand || []).length;
|
|
1073
|
+
if (open) log(`\nsync isn't finished: ${open === 1 ? 'a conflict' : `${open} conflicts`} to resolve (above). Then run the checks, and commit.`);
|
|
1074
|
+
else if (changed) log('\nReview it with "git diff", run the checks, then commit on a branch and open a PR.');
|
|
1075
|
+
return open;
|
|
1024
1076
|
}
|
|
1025
1077
|
|
|
1026
1078
|
function printUninstall({ report }, log = console.log) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agentic-mobile-kit",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.18",
|
|
4
4
|
"description": "One setup for AI-assisted development of React Native apps, bare or Expo: shared rules and workflows for Claude Code, Codex and Antigravity, git hooks, device checks with screenshots, and release tooling for the App Store and Google Play.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "prakashpro1",
|
|
@@ -20,9 +20,9 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
20
20
|
| Add a library (ask first) | `npx expo install <package>`: the version that matches the SDK |
|
|
21
21
|
| Lint, typecheck, test (each skips what the app doesn't have yet) | `sh scripts/amk/pm-run.sh lint`, `sh scripts/amk/pm-run.sh typecheck`, `sh scripts/amk/pm-run.sh test` |
|
|
22
22
|
| Check dependency versions and the app config | `npx expo install --check`, `npx expo-doctor` |
|
|
23
|
-
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
|
|
23
|
+
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); only the flows tagged smoke: `--tags smoke`; on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
|
|
24
24
|
| Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` says how many this machine's memory fits, and prints the commands: one per device (in rounds when they don't all fit; a device's flows in parts when there's room), each for an `m-device-checker` subagent |
|
|
25
|
-
| React Native mistakes in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
|
|
25
|
+
| React Native mistakes and Maestro flow problems in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
|
|
26
26
|
| Specs: progress, format check, fold a finished feature into the living spec | `node scripts/amk/specs.js status`, `node scripts/amk/specs.js check`, `node scripts/amk/specs.js merge <id>` |
|
|
27
27
|
| Check a release before tagging it (versions, permission texts, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
|
|
28
28
|
| Signed release builds (a person runs them: they use the signing keys) | `sh scripts/amk/release-build.sh android`, `sh scripts/amk/release-build.sh ios` |
|
|
@@ -40,6 +40,7 @@ Never say a check passed unless you ran it in this session.
|
|
|
40
40
|
## Rules
|
|
41
41
|
|
|
42
42
|
- Stay inside the task. Ask before touching unrelated files.
|
|
43
|
+
- Before designing a feature's screens, ask the user which UI/UX level they want: Simple (the default), Mixed or Premium (`specs/_templates/design.md` describes each). Build them to it.
|
|
43
44
|
- Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `app.json`, `app.config.*`, `eas.json` or `.github/workflows/`.
|
|
44
45
|
- Never edit `ios/` or `android/`: the next prebuild overwrites them. Native settings go in `app.json` or `app.config.*`, through config plugins; native code goes in an Expo module (`expo-module` skill). Ask before adding a config plugin.
|
|
45
46
|
- Never run `eas build`, `eas submit` or `eas update`: they build, ship or publish with the team's accounts, so a person runs them.
|
|
@@ -35,17 +35,18 @@ If the input describes a bug rather than new behavior, suggest `m-bugfix` and st
|
|
|
35
35
|
|
|
36
36
|
## 3. Design and tasks (then stop for approval)
|
|
37
37
|
|
|
38
|
-
1. **
|
|
39
|
-
2.
|
|
40
|
-
3. Fill `
|
|
41
|
-
4.
|
|
38
|
+
1. **Ask for the UI/UX level first, when the feature has screens.** As one question, ask which level its screens should have: Simple (clean, minimal and functional), Mixed (simple, with modern touches) or Premium (polished, following current design trends; it takes longer). `specs/_templates/design.md` describes each. Offer as the default the level a prototype settled (under `## Decisions` in `requirements.md`), otherwise the one the app's other screens have (an earlier spec's `design.md`), otherwise Simple. Don't design until the user has answered. Write the answer and the date under "UI/UX level" in `design.md` (n/a for a feature without screens).
|
|
39
|
+
2. **Search the codebase before designing.** List the components, hooks, API clients and helpers you'll reuse in `design.md` under "Existing code to reuse". Read `docs/amk/structure.md` and `docs/amk/conventions.md`.
|
|
40
|
+
3. Fill `design.md`: approach, files to change, risks (native changes, pod install, migrations).
|
|
41
|
+
4. Fill `tasks.md`: small tasks (about an hour, under ~300 changed lines each). Each task names the requirement it serves and how it's checked, and its tests are written in the same task, not left for the end. The last task writes `.maestro/<id>.yaml` (from `specs/_templates/flow.yaml`): a Maestro flow with a `# Scenario <n>: <name>` comment above each scenario's steps, an assertion for its THEN and a screenshot, tapping elements by `testID` and scrolling to the ones further down a screen first (`scrollUntilVisible`): turned screens are short.
|
|
42
|
+
5. Show design and tasks and **stop until the user approves them**. Ask them to check that every task serves an approved requirement and nothing goes beyond the agreed scope.
|
|
42
43
|
|
|
43
44
|
From here the plan lives in files, so the building can also run in a fresh session or another tool with `m-continue <id>`.
|
|
44
45
|
|
|
45
46
|
## 4. Build, one task at a time
|
|
46
47
|
|
|
47
48
|
For each task:
|
|
48
|
-
1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages), for every phone, tablet and orientation `AGENTS.md` lists: they're the bugs device checks and reviews find most.
|
|
49
|
+
1. Implement only that task. Write tests first for logic (state, data, utils); UI can be tested after. Build screens to the UI/UX level in `design.md`, and to the screen rules in the React Native rules file `AGENTS.md` names (keyboard, system bars, scrolling, large text, announced messages), for every phone, tablet and orientation `AGENTS.md` lists: they're the bugs device checks and reviews find most.
|
|
49
50
|
2. Run `lint`, `typecheck` and `test` (see AGENTS.md). Paste the real output. If something fails, fix it; after 2 failed attempts, stop and report.
|
|
50
51
|
3. Commit with a clear message ending in `Spec: specs/<id>`.
|
|
51
52
|
4. Tick the task in `tasks.md` and update the handoff block and log in `progress.md`.
|
|
@@ -16,9 +16,10 @@ A prototype answers questions before the real build: what the client wants, how
|
|
|
16
16
|
|
|
17
17
|
1. Read the requirement, `docs/amk/product.md`, `structure.md` and `conventions.md`, the living spec for the area in `specs/current/`, and the screens around where this would live: their components, theme and navigation.
|
|
18
18
|
2. Ask who the demo is for (the client or the team) and what it must show, one question at a time.
|
|
19
|
-
3.
|
|
20
|
-
4.
|
|
21
|
-
5.
|
|
19
|
+
3. Ask which UI/UX level the screens should have: Simple (clean, minimal and functional; the default), Mixed (simple, with modern touches) or Premium (polished, following current design trends). `specs/_templates/design.md` describes each; offer the level the app's other screens have, if an earlier spec's `design.md` records one. The concepts and the prototype are made at that level. Don't start them until the user has answered.
|
|
20
|
+
4. Pick an ID: the task's ID if it has one, otherwise `YYYYMMDD-<slug>`. Create the branch `prototype/<id>` from the main branch; this workflow commits everything there.
|
|
21
|
+
5. Write `specs/<id>/requirements.md` from `specs/_templates/requirements.md`: the goal, what's known so far, and the open questions the prototype should answer. Add a `## Decisions` section for what gets settled along the way, starting with the UI/UX level and the date.
|
|
22
|
+
6. Decide which case this is:
|
|
22
23
|
- **What to show is clear** (the screens and the flow are known): go to step 3.
|
|
23
24
|
- **How it should work or look is still open:** go to step 2.
|
|
24
25
|
|
|
@@ -17,7 +17,7 @@ If your tool has subagents, hand the review to the `m-reviewer` subagent, so it
|
|
|
17
17
|
- **Against the spec**, when there is one:
|
|
18
18
|
- *Complete:* every task is ticked, every requirement is implemented, and every scenario has evidence (a test or a screenshot).
|
|
19
19
|
- *Correct:* the code does what each requirement says, edge cases included, and nothing outside the agreed scope.
|
|
20
|
-
- *Coherent:* the decisions in `design.md` show up in the code, and `specs/current/` was updated (`node scripts/amk/specs.js merge <id>`) if behavior changed.
|
|
20
|
+
- *Coherent:* the decisions in `design.md` show up in the code, its UI/UX level in the screens, and `specs/current/` was updated (`node scripts/amk/specs.js merge <id>`) if behavior changed.
|
|
21
21
|
- **No spec:** does the diff do what was asked, and nothing unrelated?
|
|
22
22
|
- **Tests:** were tests added for new logic? Were any tests deleted, skipped or weakened?
|
|
23
23
|
- **TypeScript:** any new `any`, `@ts-ignore` or non-null `!` to get past a check, or a loosened `tsconfig.json`?
|
|
@@ -65,6 +65,9 @@ jobs:
|
|
|
65
65
|
disable-animations: true
|
|
66
66
|
emulator-options: -no-window -gpu swiftshader_indirect -noaudio -no-boot-anim -camera-back none
|
|
67
67
|
script: sh scripts/amk/verify.sh android --label ci
|
|
68
|
+
- name: Summary (each flow's result, from verify.sh's report)
|
|
69
|
+
if: always()
|
|
70
|
+
run: if [ -d .amk/evidence/ci ]; then node scripts/amk/report.js .amk/evidence/ci --summary >> "$GITHUB_STEP_SUMMARY"; fi
|
|
68
71
|
- name: Upload screenshots and logs
|
|
69
72
|
if: always()
|
|
70
73
|
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
|
|
@@ -9,8 +9,8 @@ claudecode:
|
|
|
9
9
|
You check the app on one device with fresh eyes, and hand the evidence back. You never edit files.
|
|
10
10
|
|
|
11
11
|
1. Run the one command you were given exactly as it is, for example `sh scripts/amk/verify.sh ios --no-build --screens tablet --spec <id>`: no pipes, redirects or other commands added. Its output is short, and the plain command is the one people allow, so you don't wait on a permission prompt while the other checkers run. It installs the build that's there, runs the feature's Maestro flows on that device's screens (upright and turned), and saves screenshots in `.amk/evidence/<id>/<screen>/`. A command with `--part k/n` runs only its share of the flows, on a device of its own (a temporary copy for the parts after the first, deleted afterwards), and saves them in `.amk/evidence/<id>/<screen>/part-k/`. Don't build, and don't run anything else on a device: other checkers are using the other devices. A check takes several minutes, up to about 15 when a flow has to run again: give the command a timeout that long, or run it in the background and wait for it to end, never stopping it early.
|
|
12
|
-
2. If a flow failed, read its log and Maestro's own log
|
|
13
|
-
3. Open every screenshot in your screens' folders and check each against its scenario in `specs/<id>/requirements.md`, and against the screen rules in the React Native rules file that `AGENTS.md` names: the right content, nothing cut off or covered, a layout made for that screen. A turned screen's screenshots are landscape; a portrait one means the app didn't turn.
|
|
12
|
+
2. If a flow failed, the output says at which step and what Maestro said, and shows the screen then (`report.md` in the evidence folder has it too); read its log and Maestro's own log for more, and say why, and whether the app or the flow is wrong: on a turned screen, a flow often checks or taps something further down without scrolling to it first. Don't fix anything.
|
|
13
|
+
3. On Android screens, the output may list accessibility warnings from the screens' view trees (controls without a label, tap areas under 48 dp; `report.md` says which screenshot): report them as they are, they don't fail the check. Open every screenshot in your screens' folders and check each against its scenario in `specs/<id>/requirements.md`, and against the screen rules in the React Native rules file that `AGENTS.md` names: the right content, nothing cut off or covered, a layout made for that screen. A turned screen's screenshots are landscape; a portrait one means the app didn't turn.
|
|
14
14
|
4. Report, and say only what you saw in this run:
|
|
15
15
|
- the command, and its last lines of output;
|
|
16
16
|
- per screen: flows passed out of total, and the evidence folder;
|
|
@@ -20,9 +20,9 @@ This project may also use other AI workflow frameworks (for example Superpowers,
|
|
|
20
20
|
| iOS pods (after native dependency changes) | `sh scripts/amk/pod-install.sh` |
|
|
21
21
|
| iOS build (simulator, no signing) | `sh scripts/amk/ios-build.sh` |
|
|
22
22
|
| Android build | `cd android && ./gradlew assembleDebug` |
|
|
23
|
-
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; with product flavors it checks the first unless `--flavor <name>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
|
|
23
|
+
| Check on devices (release builds, Maestro flows, screenshots) | `sh scripts/amk/verify.sh all --spec <id>`; with product flavors it checks the first unless `--flavor <name>`; another iOS scheme: `--scheme <name>`; only some screens: `--screens phone` (or `tablet`, `landscape`, …); only the flows tagged smoke: `--tags smoke`; on a real iPhone or iPad the user names: `AMK_IOS_DEVICE=<its UDID>` (the flows clear the app's data on it) |
|
|
24
24
|
| Check devices at the same time | `sh scripts/amk/verify.sh plan --spec <id>` says how many this machine's memory fits, and prints the commands: one per device (in rounds when they don't all fit; a device's flows in parts when there's room), each for an `m-device-checker` subagent |
|
|
25
|
-
| React Native mistakes in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
|
|
25
|
+
| React Native mistakes and Maestro flow problems in this branch's changed lines (`verify.sh quick` runs it) | `node scripts/amk/rn-check.js` |
|
|
26
26
|
| Specs: progress, format check, fold a finished feature into the living spec | `node scripts/amk/specs.js status`, `node scripts/amk/specs.js check`, `node scripts/amk/specs.js merge <id>` |
|
|
27
27
|
| Check a release before tagging it (versions, permission texts, store review rules, debug leftovers) | `node scripts/amk/release-check.js` |
|
|
28
28
|
| Signed release builds (a person runs them: they use the signing keys) | `sh scripts/amk/release-build.sh android [flavor]`, `sh scripts/amk/release-build.sh ios [scheme]` |
|
|
@@ -40,6 +40,7 @@ Never say a check passed unless you ran it in this session.
|
|
|
40
40
|
## Rules
|
|
41
41
|
|
|
42
42
|
- Stay inside the task. Ask before touching unrelated files.
|
|
43
|
+
- Before designing a feature's screens, ask the user which UI/UX level they want: Simple (the default), Mixed or Premium (`specs/_templates/design.md` describes each). Build them to it.
|
|
43
44
|
- Ask before adding or upgrading dependencies, and before editing `package.json`, lockfiles, `Podfile`, `build.gradle`, `Info.plist`, `AndroidManifest.xml` or `.github/workflows/`.
|
|
44
45
|
- Don't hand-edit `ios/*.xcodeproj/project.pbxproj`. If a native file must be added to the Xcode project, stop and ask.
|
|
45
46
|
- Never read, print or commit `.env` files, keystores, signing files or the files `.amk-secrets` lists. Secrets don't belong in this repo.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Accessibility on the device: from the view trees verify.sh has Maestro save after each screenshot on Android (which
|
|
3
|
+
// marks what's tappable; iOS' tree doesn't), the tappable elements without a label, which a screen reader can't name,
|
|
4
|
+
// and the ones smaller than 48×48 dp, Android's minimum (and more than iOS' 44 points: React Native lays out both
|
|
5
|
+
// alike). An element a scrolling list cuts off at its edge isn't measured. Prints a line each, once per element and
|
|
6
|
+
// kind of problem in a flow: flow, screenshot, problem, element.
|
|
7
|
+
// Usage: node scripts/amk/a11y.js <Maestro debug folder> <screen density in dpi> <flow>
|
|
8
|
+
'use strict';
|
|
9
|
+
const fs = require('fs');
|
|
10
|
+
const path = require('path');
|
|
11
|
+
|
|
12
|
+
const [dir, dpi, flow] = process.argv.slice(2);
|
|
13
|
+
const scale = Number(dpi) / 160;
|
|
14
|
+
if (!dir || !scale || !fs.existsSync(dir)) process.exit(0);
|
|
15
|
+
|
|
16
|
+
// the trees and the screenshot each follows, in the order the flow saved them. Maestro's commands.json has each step:
|
|
17
|
+
// the view-tree step's id (amk-view-tree-<screenshot>) and the tree it saved; the file's own name is cut short
|
|
18
|
+
const trees = [];
|
|
19
|
+
const files = [];
|
|
20
|
+
(function find(d, depth) {
|
|
21
|
+
for (const e of fs.readdirSync(d, { withFileTypes: true })) {
|
|
22
|
+
const p = path.join(d, e.name);
|
|
23
|
+
if (e.isDirectory() && depth < 4) find(p, depth + 1);
|
|
24
|
+
else files.push(p);
|
|
25
|
+
}
|
|
26
|
+
})(dir, 0);
|
|
27
|
+
for (const f of files.filter(p => path.basename(p) === 'commands.json')) {
|
|
28
|
+
let steps;
|
|
29
|
+
try { steps = JSON.parse(fs.readFileSync(f, 'utf8')); } catch { continue; }
|
|
30
|
+
for (const s of Array.isArray(steps) ? steps : []) {
|
|
31
|
+
const id = ((((s.command || {}).assertConditionCommand || {}).condition || {}).visible || {}).idRegex || '';
|
|
32
|
+
const tree = ((s.metadata || {}).artifacts || []).find(a => a.type === 'SCREEN_HIERARCHY');
|
|
33
|
+
if (id.startsWith('amk-view-tree-') && tree) trees.push([path.join(path.dirname(f), tree.path), id.slice(14)]);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
// without commands.json: the names of the trees' files
|
|
37
|
+
if (!trees.length) {
|
|
38
|
+
for (const p of files.filter(p => /amk-view-tree-.+\.json$/.test(p)).sort((a, b) => path.basename(a).localeCompare(path.basename(b)))) {
|
|
39
|
+
trees.push([p, /amk-view-tree-(.+)\.json$/.exec(path.basename(p))[1]]);
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
// the system's own windows, with everything inside them (the status bar, a keyboard and its suggestions); Android's
|
|
44
|
+
// own ids (android:id/…) only for that element, as the app's views sit inside android:id/content
|
|
45
|
+
const SYSTEM = /^(com\.android\.systemui|com\.google\.android\.inputmethod|com\.android\.inputmethod|com\.samsung\.android\.honeyboard|com\.touchtype\.swiftkey)/;
|
|
46
|
+
const box = a => { const b = /\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]/.exec(a.bounds || ''); return b && b.slice(1).map(Number); };
|
|
47
|
+
const seen = new Set();
|
|
48
|
+
for (const [file, shot] of trees) {
|
|
49
|
+
let tree;
|
|
50
|
+
try { tree = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { continue; }
|
|
51
|
+
// each node with the bounds of the nearest scrolling container around it
|
|
52
|
+
(function walk(n, clip) {
|
|
53
|
+
if (!n) return;
|
|
54
|
+
const a = n.attributes || {};
|
|
55
|
+
if (SYSTEM.test(a['resource-id'] || '')) return;
|
|
56
|
+
const b = box(a);
|
|
57
|
+
if (a.clickable === 'true' && b && !/^android:id\//.test(a['resource-id'] || '')) {
|
|
58
|
+
const [x1, y1, x2, y2] = b;
|
|
59
|
+
const w = (x2 - x1) / scale;
|
|
60
|
+
const h = (y2 - y1) / scale;
|
|
61
|
+
const label = (a.accessibilityText || a.text || a.hintText || '').trim();
|
|
62
|
+
const id = a['resource-id'] || '';
|
|
63
|
+
const name = id ? `testID ${id}` : label ? `"${label}"` : `${a.class || 'an element'} at ${a.bounds}`;
|
|
64
|
+
// once per element and kind of problem in a flow, where it first shows (its size can differ a little later)
|
|
65
|
+
const say = problem => {
|
|
66
|
+
const key = `${id || label}|${problem.startsWith('no label') ? 'label' : 'size'}`; // a testID names it, whatever it shows
|
|
67
|
+
if (!seen.has(key)) { seen.add(key); console.log([flow, shot, problem, name].join('\t')); }
|
|
68
|
+
};
|
|
69
|
+
if (w > 0 && h > 0) {
|
|
70
|
+
if (!label) say('no label: a screen reader can\'t say what it does');
|
|
71
|
+
const cut = clip && (y1 <= clip[1] || y2 >= clip[3] || x1 <= clip[0] || x2 >= clip[2]);
|
|
72
|
+
if (!cut && (w < 47.5 || h < 47.5)) say(`${Math.round(w)}×${Math.round(h)} dp: under 48×48`);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
const inner = a.scrollable === 'true' && b ? b : clip;
|
|
76
|
+
for (const c of n.children || []) walk(c, inner);
|
|
77
|
+
})(tree.root || tree, null);
|
|
78
|
+
}
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// A device check's report, from its evidence folder (.amk/evidence/<label>/): report.md for people (each screen, its
|
|
3
|
+
// flows, passed or failed and why, and their screenshots) and junit.xml for CI. --summary prints a short Markdown
|
|
4
|
+
// table instead, for a CI job's summary. verify.sh runs it after each device check, and builds it from what's on disk,
|
|
5
|
+
// so devices and parts checked at the same time all end up in it: each screen's flows are in <screen>/.flows (or
|
|
6
|
+
// <screen>/part-<k>/.flows), a line each: name, passed or failed, why, its screenshots, the screen when it failed.
|
|
7
|
+
// Usage: node scripts/amk/report.js <evidence folder> [--summary]
|
|
8
|
+
'use strict';
|
|
9
|
+
const fs = require('fs');
|
|
10
|
+
const path = require('path');
|
|
11
|
+
|
|
12
|
+
const [dir, mode] = process.argv.slice(2);
|
|
13
|
+
if (!dir || !fs.existsSync(dir)) {
|
|
14
|
+
console.error('usage: node scripts/amk/report.js <evidence folder> [--summary]');
|
|
15
|
+
process.exit(2);
|
|
16
|
+
}
|
|
17
|
+
const label = path.basename(path.resolve(dir));
|
|
18
|
+
const read = f => { try { return fs.readFileSync(f, 'utf8'); } catch { return null; } };
|
|
19
|
+
|
|
20
|
+
// the screens: <screen>/.flows, and <screen>/part-<k>/.flows for a device's flows split in parts
|
|
21
|
+
const screens = [];
|
|
22
|
+
for (const s of fs.readdirSync(dir, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name).sort()) {
|
|
23
|
+
for (const sub of ['', ...(fs.readdirSync(path.join(dir, s)).filter(p => /^part-\d+$/.test(p)).sort())]) {
|
|
24
|
+
const text = read(path.join(dir, s, sub, '.flows'));
|
|
25
|
+
if (text === null) continue;
|
|
26
|
+
// what the view trees showed on Android: flow, screenshot, problem, element (a11y.js)
|
|
27
|
+
const a11y = (read(path.join(dir, s, sub, '.a11y')) || '').split('\n').filter(Boolean).map(l => l.split('\t'));
|
|
28
|
+
const flows = text.split('\n').filter(Boolean).map(l => {
|
|
29
|
+
const [name, result, why, shots, shot] = l.split('\t');
|
|
30
|
+
return { name, passed: result === 'passed', why: why || '', shots: (shots || '').split(',').filter(Boolean), shot: shot || '',
|
|
31
|
+
a11y: a11y.filter(x => x[0] === name).map(([, at, problem, element]) => ({ at, problem, element })) };
|
|
32
|
+
});
|
|
33
|
+
screens.push({ name: sub ? `${s} (${sub.replace('-', ' ')})` : s, dir: sub ? `${s}/${sub}` : s, flows });
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
const all = screens.flatMap(s => s.flows);
|
|
37
|
+
const failed = all.filter(f => !f.passed);
|
|
38
|
+
const counts = s => `${s.flows.filter(f => f.passed).length}/${s.flows.length}`;
|
|
39
|
+
const table = ['| Screen | Flows passed | Screenshots |', '|---|---|---|',
|
|
40
|
+
...screens.map(s => `| ${s.name} | ${counts(s)}${s.flows.every(f => f.passed) ? '' : ' ✗'} | ${s.flows.reduce((n, f) => n + f.shots.length, 0)} |`)];
|
|
41
|
+
const warned = all.reduce((n, f) => n + f.a11y.length, 0);
|
|
42
|
+
const headline = `${all.length - failed.length} of ${all.length} flows passed on ${screens.length} screen${screens.length === 1 ? '' : 's'}${warned ? `, ${warned} accessibility warning${warned === 1 ? '' : 's'}` : ''}`;
|
|
43
|
+
|
|
44
|
+
if (mode === '--summary') {
|
|
45
|
+
console.log([`### Device checks: ${label}`, '', headline, '', ...table, '',
|
|
46
|
+
...failed.map(f => `- ✗ ${screens.find(s => s.flows.includes(f)).name}: ${f.name}${f.why ? `, failed ${f.why}` : ''}`)].join('\n'));
|
|
47
|
+
process.exit(0);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
// a path inside the evidence folder, for a link from report.md, which sits in it
|
|
51
|
+
const link = p => p.split('/').map(encodeURIComponent).join('/');
|
|
52
|
+
const md = [`# Device checks: ${label}`, '', `${new Date().toISOString().slice(0, 16).replace('T', ' ')} UTC · ${headline}`, '', ...table];
|
|
53
|
+
for (const s of screens) {
|
|
54
|
+
md.push('', `## ${s.name}`);
|
|
55
|
+
for (const f of s.flows) {
|
|
56
|
+
md.push('', `### ${f.passed ? '✓' : '✗'} ${f.name}`);
|
|
57
|
+
if (!f.passed) {
|
|
58
|
+
md.push('', `Failed${f.why ? ` ${f.why}` : ''}. Log: [${s.dir}/${f.name}.log](${link(`${s.dir}/${f.name}.log`)})${f.shot ? ` · [the screen when it failed](${link(f.shot)})` : ''}`);
|
|
59
|
+
}
|
|
60
|
+
if (f.shots.length) md.push('', f.shots.map(p => `<img src="${link(p)}" width="180" alt="${path.basename(p, '.png')}" title="${path.basename(p, '.png')}">`).join(' '));
|
|
61
|
+
if (f.a11y.length) md.push('', 'Accessibility, from the screen\'s view tree:', '', ...f.a11y.map(x => `- ${x.at}: ${x.element}: ${x.problem}`));
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
fs.writeFileSync(path.join(dir, 'report.md'), `${md.join('\n')}\n`);
|
|
65
|
+
|
|
66
|
+
const xml = s => String(s).replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"');
|
|
67
|
+
fs.writeFileSync(path.join(dir, 'junit.xml'), [
|
|
68
|
+
'<?xml version="1.0" encoding="UTF-8"?>',
|
|
69
|
+
`<testsuites name="${xml(label)}" tests="${all.length}" failures="${failed.length}">`,
|
|
70
|
+
...screens.flatMap(s => [
|
|
71
|
+
` <testsuite name="${xml(s.name)}" tests="${s.flows.length}" failures="${s.flows.filter(f => !f.passed).length}">`,
|
|
72
|
+
...s.flows.map(f => (f.passed ? ` <testcase classname="${xml(s.name)}" name="${xml(f.name)}"/>`
|
|
73
|
+
: ` <testcase classname="${xml(s.name)}" name="${xml(f.name)}"><failure message="${xml(f.why || 'failed')}"/></testcase>`)),
|
|
74
|
+
' </testsuite>',
|
|
75
|
+
]),
|
|
76
|
+
'</testsuites>', '',
|
|
77
|
+
].join('\n'));
|
|
78
|
+
console.log(`${headline}: ${path.join(dir, 'report.md')}`);
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// Checks the lines this branch adds or changes for React Native mistakes that the app's rules (docs/amk/react-native.md
|
|
3
|
-
// or expo.md) list
|
|
3
|
+
// or expo.md) list, and its Maestro flows (.maestro/): Maestro's own syntax check, files they run that aren't there,
|
|
4
|
+
// taps by text, and each scenario of a spec the branch touched with its steps, an assertion and a screenshot.
|
|
5
|
+
// Problems (✗) fail it, and so verify.sh quick; warnings (!) don't. Only changed lines: code already
|
|
4
6
|
// on the base branch is never reported. A line that's right as it is carries `// amk-ok <date>: <reason>`, on it or on
|
|
5
7
|
// the line above, with the user's reason and the day they gave it; it's listed as kept, for review. When a branch changes
|
|
6
8
|
// a file again, a kept line in it that's over two weeks old is reported again, for the user to decide again (the date
|
|
@@ -32,18 +34,21 @@ const since = baseRef || 'the last commit';
|
|
|
32
34
|
const source = f => /\.(js|jsx|ts|tsx|mjs|cjs)$/.test(f) && !f.endsWith('.d.ts')
|
|
33
35
|
&& !/(^|\/)(node_modules|scripts\/amk|__tests__|__mocks__|e2e)\//.test(f)
|
|
34
36
|
&& !/\.(test|spec)\.\w+$|(^|\/)(jest[.-]setup|setup-?tests)[^/]*$/i.test(f);
|
|
37
|
+
// Maestro flows: the ones verify.sh runs (.maestro/*.yaml) and the subflows they run (in folders below)
|
|
38
|
+
// (not the copies with view-tree steps verify.sh runs for a moment on Android: .amk-<screen>-<flow>.yaml)
|
|
39
|
+
const flowFile = f => /^\.maestro\/.+\.ya?ml$/.test(f) && !/(^|\/)\.amk-/.test(f);
|
|
35
40
|
const changed = new Map(); // file -> Set of line numbers, or 'all'
|
|
36
41
|
if (sha) {
|
|
37
42
|
let file = null;
|
|
38
43
|
for (const line of (git('diff', '-U0', '--no-color', '--no-ext-diff', '--relative', '-M', '--diff-filter=ACMR', sha) || '').split('\n')) {
|
|
39
44
|
if (line.startsWith('+++ ')) { file = line === '+++ /dev/null' ? null : line.slice(6); continue; }
|
|
40
45
|
const h = /^@@ -\S+ \+(\d+)(?:,(\d+))? @@/.exec(line);
|
|
41
|
-
if (!h || !file || !source(file)) continue;
|
|
46
|
+
if (!h || !file || !(source(file) || flowFile(file))) continue;
|
|
42
47
|
if (!changed.has(file)) changed.set(file, new Set());
|
|
43
48
|
for (let n = Number(h[1]), end = n + Number(h[2] ?? 1); n < end; n++) changed.get(file).add(n);
|
|
44
49
|
}
|
|
45
50
|
}
|
|
46
|
-
for (const f of (git('ls-files', '--others', '--exclude-standard') || '').split('\n')) if (f && source(f)) changed.set(f, 'all');
|
|
51
|
+
for (const f of (git('ls-files', '--others', '--exclude-standard') || '').split('\n')) if (f && (source(f) || flowFile(f))) changed.set(f, 'all');
|
|
47
52
|
|
|
48
53
|
// ---------- what the app uses ----------
|
|
49
54
|
let pkg = {};
|
|
@@ -107,6 +112,13 @@ function okSince(file, n, date) {
|
|
|
107
112
|
const t = /^committer-time (\d+)$/m.exec(git('blame', '--porcelain', '-L', `${n},${n}`, '--', file) || '');
|
|
108
113
|
return t ? localDay(Number(t[1]) * 1000) : today;
|
|
109
114
|
}
|
|
115
|
+
const BASE64 = new Set([...'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/='].map(c => c.charCodeAt(0)));
|
|
116
|
+
const SECRETS = [
|
|
117
|
+
[/\bgh[pousr]_[A-Za-z0-9]{36,}/g, 'a GitHub token'], [/\bgithub_pat_[A-Za-z0-9_]{40,}/g, 'a GitHub token'],
|
|
118
|
+
[/\b[sr]k_live_[A-Za-z0-9]{20,}/g, 'a Stripe secret key'], [/\bAKIA[0-9A-Z]{16}\b/g, 'an AWS access key'],
|
|
119
|
+
[/-----BEGIN [A-Z ]*PRIVATE KEY-----/g, 'a private key'], [/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, 'a Slack token'],
|
|
120
|
+
[/\bsk-(proj-|ant-)?[A-Za-z0-9_-]{32,}/g, 'an AI service API key'],
|
|
121
|
+
];
|
|
110
122
|
const importsFrom = (code, from) => [...code.matchAll(new RegExp(`import\\s+[^;'"]*?\\{([^}]*)\\}\\s*from\\s*['"]${from}['"]`, 'g'))];
|
|
111
123
|
const timers = /\bset(Timeout|Interval)\s*\(/;
|
|
112
124
|
// a permission prompt (not App Tracking Transparency's, which apps show early on purpose)
|
|
@@ -155,15 +167,17 @@ function check(file, text) {
|
|
|
155
167
|
}
|
|
156
168
|
});
|
|
157
169
|
// secrets are reported without their value; comments too, as they ship in the repository
|
|
158
|
-
const
|
|
159
|
-
[/\bgh[pousr]_[A-Za-z0-9]{36,}/g, 'a GitHub token'], [/\bgithub_pat_[A-Za-z0-9_]{40,}/g, 'a GitHub token'],
|
|
160
|
-
[/\b[sr]k_live_[A-Za-z0-9]{20,}/g, 'a Stripe secret key'], [/\bAKIA[0-9A-Z]{16}\b/g, 'an AWS access key'],
|
|
161
|
-
[/-----BEGIN [A-Z ]*PRIVATE KEY-----/g, 'a private key'], [/\bxox[baprs]-[A-Za-z0-9-]{10,}/g, 'a Slack token'],
|
|
162
|
-
[/\bsk-(proj-|ant-)?[A-Za-z0-9_-]{32,}/g, 'an AI service API key'],
|
|
163
|
-
];
|
|
164
|
-
for (const [re, what] of secrets) each(re, m => add('✗', m.index, null, `${what} in code: anyone with the repository or the app can read it. Revoke it and keep it on a server`), text);
|
|
170
|
+
for (const [re, what] of SECRETS) each(re, m => add('✗', m.index, null, `${what} in code: anyone with the repository or the app can read it. Revoke it and keep it on a server`), text);
|
|
165
171
|
each(/\bAIza[0-9A-Za-z_-]{35}\b/g, m => add('!', m.index, null, 'a Google API key in code: ship it only if it is restricted to this app (Google Cloud console)'), text);
|
|
166
|
-
|
|
172
|
+
// measured without a regular expression, whose repetition overflows the stack on an image of a few MB
|
|
173
|
+
for (let i = text.indexOf('data:image/'); i !== -1; i = text.indexOf('data:image/', i + 1)) {
|
|
174
|
+
const head = /^data:image\/[a-z+]+;base64,/.exec(text.slice(i, i + 40));
|
|
175
|
+
if (!head) continue;
|
|
176
|
+
let j = i + head[0].length;
|
|
177
|
+
while (j < text.length && BASE64.has(text.charCodeAt(j))) j++;
|
|
178
|
+
if (j - i >= 8000) add('✗', i, j, `a ${Math.round((j - i) * 0.75 / 1024)} KB base64 image in code: put it in an asset file`);
|
|
179
|
+
i = j;
|
|
180
|
+
}
|
|
167
181
|
if (expoSdk >= 56 && deps['expo-router']) {
|
|
168
182
|
each(/(['"])@react-navigation\/[^'"\n]+\1/g, m => add('✗', m.index, null, `${m[0]} doesn't work alongside Expo Router from SDK 56: import from expo-router (see the expo-router skill)`));
|
|
169
183
|
}
|
|
@@ -246,6 +260,81 @@ function lineAt(code, i) {
|
|
|
246
260
|
return n;
|
|
247
261
|
}
|
|
248
262
|
|
|
263
|
+
// ---------- Maestro flows ----------
|
|
264
|
+
// a flow without its comments (each comment character a space, so positions stay): # outside quotes starts one
|
|
265
|
+
function stripYamlComments(text) {
|
|
266
|
+
return text.split('\n').map(l => {
|
|
267
|
+
let quote = null;
|
|
268
|
+
for (let i = 0; i < l.length; i++) {
|
|
269
|
+
const c = l[i];
|
|
270
|
+
if (quote) { if (c === quote) quote = null; } else if (c === '"' || c === "'") quote = c;
|
|
271
|
+
else if (c === '#' && (i === 0 || /\s/.test(l[i - 1]))) return l.slice(0, i) + ' '.repeat(l.length - i);
|
|
272
|
+
}
|
|
273
|
+
return l;
|
|
274
|
+
}).join('\n');
|
|
275
|
+
}
|
|
276
|
+
const TAPS = /^(tapOn|doubleTapOn|longPressOn)$/;
|
|
277
|
+
const SELECTS = /^(tapOn|doubleTapOn|longPressOn|assertVisible|assertNotVisible|scrollUntilVisible|extendedWaitUntil|copyTextFrom)$/;
|
|
278
|
+
const ASSERTS = /^(assertVisible|assertNotVisible|assertTrue|assertWithAI|assertNoDefectsWithAI)$/;
|
|
279
|
+
// buttons of system dialogs (permission prompts, alerts), which have no testID
|
|
280
|
+
const SYSTEM_BUTTON = /^(allow|allow while using (the )?app|allow once|only this time|while using the app|ok|cancel|continue|don.t allow|not now|deny|close)$/i;
|
|
281
|
+
const unquote = v => { v = v.trim(); return /^'.*'$/.test(v) ? v.slice(1, -1).replace(/''/g, "'") : /^".*"$/.test(v) ? v.slice(1, -1) : v; };
|
|
282
|
+
let noMaestro = false;
|
|
283
|
+
function checkFlow(file, text) {
|
|
284
|
+
const out = [];
|
|
285
|
+
const add = (level, at, message, always) => out.push({ level, at, end: at, message, always });
|
|
286
|
+
const dir = path.dirname(file);
|
|
287
|
+
let offset = 0;
|
|
288
|
+
let cmd = null;
|
|
289
|
+
let optional = false;
|
|
290
|
+
let target = '';
|
|
291
|
+
let asserts = 0;
|
|
292
|
+
const done = () => { if (cmd === 'extendedWaitUntil' && !optional) asserts++; };
|
|
293
|
+
for (const l of stripYamlComments(text).split('\n')) {
|
|
294
|
+
const at = offset;
|
|
295
|
+
offset += l.length + 1;
|
|
296
|
+
const item = /^\s*-\s*([A-Za-z]+)\s*:?\s*(.*)$/.exec(l);
|
|
297
|
+
if (item) { done(); cmd = item[1]; optional = false; if (ASSERTS.test(cmd)) asserts++; }
|
|
298
|
+
if (/^\s*optional\s*:\s*true\b/.test(l)) optional = true;
|
|
299
|
+
const app = /^appId\s*:\s*(.+)$/.exec(l);
|
|
300
|
+
if (app && !/\$\{APP_ID\}/.test(app[1])) add('!', at, `appId ${app[1].trim()}: verify.sh sets APP_ID for the build it checks, which a flavor or scheme changes: use appId: \${APP_ID}`);
|
|
301
|
+
// what this line selects: the command's own value (tapOn: Save), keys of an inline map, or a key below the command
|
|
302
|
+
const sel = [];
|
|
303
|
+
if (item && SELECTS.test(cmd) && item[2].trim() && !/^[{[|>]/.test(item[2].trim())) sel.push(['text', unquote(item[2])]);
|
|
304
|
+
for (const m of (item && /^\{/.test(item[2].trim()) ? item[2] : !item ? l : '').matchAll(/\b(text|id|visible|notVisible)\s*:\s*("[^"]*"|'(?:[^']|'')*'|[^,}\n]+)/g)) {
|
|
305
|
+
if (SELECTS.test(cmd || '') && unquote(m[2])) sel.push([m[1] === 'id' ? 'id' : 'text', unquote(m[2])]);
|
|
306
|
+
}
|
|
307
|
+
for (const [kind, value] of sel) {
|
|
308
|
+
if (TAPS.test(cmd)) target = value;
|
|
309
|
+
if (kind === 'text' && TAPS.test(cmd) && !SYSTEM_BUTTON.test(value) && !value.includes('${')) {
|
|
310
|
+
add('!', at, `${cmd} "${value}" taps by text: on iOS a label and its control both match, and on a real iPhone a hidden one can; tap by testID (id:)`);
|
|
311
|
+
}
|
|
312
|
+
if (kind === 'text' && /['’]/.test(value)) add('!', at, `"${value}" has an apostrophe, which a real iPhone can't search for (maestro-runner): match a testID, or text without it`);
|
|
313
|
+
}
|
|
314
|
+
if (item && cmd === 'inputText' && item[2].trim() && !item[2].includes('${') && /pass(word|code)?\b|\bpin\b|otp|secret/i.test(target)) {
|
|
315
|
+
add('!', at, `a password typed into the flow: use \${MAESTRO_PASSWORD} (or another MAESTRO_ variable) from .maestro/.env.local, which isn't committed`);
|
|
316
|
+
}
|
|
317
|
+
// a subflow or script it runs: there, or the flow fails when it gets to it
|
|
318
|
+
const runs = (item && /^(runFlow|runScript)$/.test(cmd) && !/^[{[|>]/.test(item[2].trim()) && item[2].trim()) || (!item && /^(runFlow|runScript)$/.test(cmd || '') && (/^\s*file\s*:\s*(.+)$/.exec(l) || [])[1]);
|
|
319
|
+
if (runs && !runs.includes('${') && /\.(ya?ml|js)$/.test(unquote(runs)) && !fs.existsSync(path.join(root, dir, unquote(runs)))) {
|
|
320
|
+
add('✗', at, `${cmd} ${unquote(runs)}: no such file next to this flow (${dir}/)`, true);
|
|
321
|
+
}
|
|
322
|
+
}
|
|
323
|
+
done();
|
|
324
|
+
for (const [re, what] of SECRETS) for (const m of text.matchAll(re)) add('✗', m.index, `${what} in a flow: anyone with the repository can read it. Revoke it, and use a MAESTRO_ variable from .maestro/.env.local`);
|
|
325
|
+
// a flow verify.sh runs (not a subflow) that never checks anything passes whatever the app shows
|
|
326
|
+
if (/^\.maestro\/[^/]+$/.test(file) && !asserts) add('!', 0, 'this flow checks nothing: add an assertVisible for what each scenario\'s THEN expects', true);
|
|
327
|
+
// Maestro's own syntax check (seconds, no device): AMK_MAESTRO names another maestro
|
|
328
|
+
const r = noMaestro ? null : spawnSync(process.env.AMK_MAESTRO || 'maestro', ['check-syntax', file], { cwd: root, encoding: 'utf8' });
|
|
329
|
+
if (r && r.error) noMaestro = true;
|
|
330
|
+
else if (r && r.status !== 0) {
|
|
331
|
+
const said = `${r.stdout || ''}\n${r.stderr || ''}`.split('\n').map(s => s.trim()).find(s => s && s !== 'OK') || 'invalid flow';
|
|
332
|
+
const n = Number((/:(\d+):\d+/.exec(said) || [])[1]) || 1;
|
|
333
|
+
add('✗', text.split('\n').slice(0, n - 1).reduce((a, s) => a + s.length + 1, 0), `maestro check-syntax: ${said.replace(/\s+at \/syntax-checker:\d+:\d+/, '')}`, true);
|
|
334
|
+
}
|
|
335
|
+
return out;
|
|
336
|
+
}
|
|
337
|
+
|
|
249
338
|
for (const [file, lines] of changed) {
|
|
250
339
|
let text;
|
|
251
340
|
try { text = fs.readFileSync(path.join(root, file), 'utf8'); } catch { continue; }
|
|
@@ -253,13 +342,13 @@ for (const [file, lines] of changed) {
|
|
|
253
342
|
const starts = [0];
|
|
254
343
|
for (let i = text.indexOf('\n'); i !== -1; i = text.indexOf('\n', i + 1)) starts.push(i + 1);
|
|
255
344
|
const line = i => { let lo = 0, hi = starts.length - 1; while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= i) lo = mid; else hi = mid - 1; } return lo + 1; };
|
|
256
|
-
for (const f of check(file, text)) {
|
|
345
|
+
for (const f of flowFile(file) ? checkFlow(file, text) : check(file, text)) {
|
|
257
346
|
const from = line(f.at);
|
|
258
347
|
const to = line(f.end);
|
|
259
348
|
const touched = lines === 'all' || [...Array(to - from + 1).keys()].some(k => lines.has(from + k));
|
|
260
349
|
const at = f.line || from;
|
|
261
350
|
// on the line, or in a comment on the line above
|
|
262
|
-
const above = /^\s*(\/\/|\/\*|\{\s
|
|
351
|
+
const above = /^\s*(\/\/|\/\*|\{\s*\/\*|#)/.test(rows[at - 2] || '') ? at - 1 : 0;
|
|
263
352
|
const okAt = [at, above].find(n => n && /amk-ok\b/.test(rows[n - 1]));
|
|
264
353
|
const ok = okAt && /amk-ok(?:\s+(\d{4}-\d{2}-\d{2}))?\s*:\s*(\S.*?)\s*(\*\/\s*\}?)?\s*$/.exec(rows[okAt - 1]);
|
|
265
354
|
let message = f.message;
|
|
@@ -268,14 +357,14 @@ for (const [file, lines] of changed) {
|
|
|
268
357
|
// kept: listed when its own lines changed; over two weeks old, asked again whenever its file changes
|
|
269
358
|
if (Date.parse(today) - Date.parse(since) <= 14 * DAY) { if (touched) kept.push(`${file}:${at}: ${ok[2]} (${since})`); continue; }
|
|
270
359
|
message = `kept with amk-ok since ${since}, over two weeks, and its file changed again: ${f.message}. The user's reason then: ${ok[2]}`;
|
|
271
|
-
} else if (!touched) continue;
|
|
360
|
+
} else if (!touched && !f.always) continue;
|
|
272
361
|
if (!findings.some(x => x.where === `${file}:${at}` && x.message === message)) findings.push({ ...f, message, where: `${file}:${at}` });
|
|
273
362
|
}
|
|
274
363
|
}
|
|
275
364
|
|
|
276
365
|
// ---------- once for the app: an error boundary somewhere ----------
|
|
277
366
|
let boundary = true;
|
|
278
|
-
if (changed.
|
|
367
|
+
if ([...changed.keys()].some(source)) {
|
|
279
368
|
boundary = false;
|
|
280
369
|
const files = [...(git('ls-files') || '').split('\n'), ...changed.keys()].filter(f => f && source(f));
|
|
281
370
|
for (const f of new Set(files)) {
|
|
@@ -285,6 +374,45 @@ if (changed.size) {
|
|
|
285
374
|
}
|
|
286
375
|
}
|
|
287
376
|
|
|
377
|
+
// ---------- each scenario of a spec the branch touched has its steps in the spec's flows ----------
|
|
378
|
+
// specs/<id>/requirements.md lists them ("#### Scenario: <name>"); the flows are .maestro/<id>*.yaml, with a
|
|
379
|
+
// "# Scenario <n>: <name>" comment above each one's steps, as specs/_templates/flow.yaml shows
|
|
380
|
+
const touchedPaths = [...(sha ? (git('diff', '--name-only', '--relative', sha) || '').split('\n') : []),
|
|
381
|
+
...(git('ls-files', '--others', '--exclude-standard') || '').split('\n')].filter(Boolean);
|
|
382
|
+
const norm = s => s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
|
|
383
|
+
const specIds = fs.existsSync(path.join(root, 'specs')) ? fs.readdirSync(path.join(root, 'specs'), { withFileTypes: true })
|
|
384
|
+
.filter(e => e.isDirectory() && !/^(_|current$)/.test(e.name)).map(e => e.name) : [];
|
|
385
|
+
const flowsDir = fs.existsSync(path.join(root, '.maestro')) ? fs.readdirSync(path.join(root, '.maestro')).filter(f => /\.ya?ml$/.test(f)) : [];
|
|
386
|
+
for (const id of specIds) {
|
|
387
|
+
const req = `specs/${id}/requirements.md`;
|
|
388
|
+
let reqText;
|
|
389
|
+
try { reqText = fs.readFileSync(path.join(root, req), 'utf8'); } catch { continue; }
|
|
390
|
+
const flows = flowsDir.filter(f => f.toLowerCase().startsWith(id.toLowerCase())).map(f => `.maestro/${f}`);
|
|
391
|
+
if (!flows.length || !touchedPaths.some(p => p.startsWith(`specs/${id}/`) || flows.includes(p))) continue;
|
|
392
|
+
const blocks = flows.flatMap(f => {
|
|
393
|
+
const text = fs.readFileSync(path.join(root, f), 'utf8');
|
|
394
|
+
const code = stripYamlComments(text).split('\n');
|
|
395
|
+
const out = [];
|
|
396
|
+
text.split('\n').forEach((l, i) => {
|
|
397
|
+
const m = /^\s*#\s*Scenario\b\s*(\d+)?\s*[:.)-]?\s*(.*)$/i.exec(l);
|
|
398
|
+
if (m) out.push({ n: Number(m[1]) || 0, name: norm(m[2]), at: i });
|
|
399
|
+
else if (out.length) out[out.length - 1].code = `${out[out.length - 1].code || ''}${code[i]}\n`;
|
|
400
|
+
});
|
|
401
|
+
return out.map(b => ({ ...b, flow: f }));
|
|
402
|
+
});
|
|
403
|
+
[...reqText.matchAll(/^#### Scenario:\s*(.*)$/gm)].forEach((m, i) => {
|
|
404
|
+
const name = norm(m[1]);
|
|
405
|
+
const where = `${req}:${reqText.slice(0, m.index).split('\n').length}`;
|
|
406
|
+
const b = blocks.find(x => x.n === i + 1) || blocks.find(x => name && x.name && (x.name.includes(name) || name.includes(x.name)));
|
|
407
|
+
const say = message => findings.push({ level: '!', message, where });
|
|
408
|
+
if (!b) say(`scenario ${i + 1} "${m[1].trim()}" has no block in ${flows.join(', ')}: add "# Scenario ${i + 1}: ${m[1].trim()}" above its steps, with an assertion for its THEN and a screenshot`);
|
|
409
|
+
else {
|
|
410
|
+
if (!/-\s*(assertVisible|assertNotVisible|assertTrue|assertWithAI|extendedWaitUntil)\b/.test(b.code || '')) say(`scenario ${i + 1} "${m[1].trim()}" has no assertion in ${b.flow}: check what its THEN expects`);
|
|
411
|
+
if (!/-\s*takeScreenshot\b/.test(b.code || '')) say(`scenario ${i + 1} "${m[1].trim()}" has no screenshot in ${b.flow}, so it has no evidence`);
|
|
412
|
+
}
|
|
413
|
+
});
|
|
414
|
+
}
|
|
415
|
+
|
|
288
416
|
// ---------- report ----------
|
|
289
417
|
// by file, then line
|
|
290
418
|
const order = w => { const [, file, n] = /^(.*):(\d+)$/.exec(w); return [file, Number(n)]; };
|
|
@@ -292,14 +420,15 @@ findings.sort((a, b) => { const [fa, na] = order(a.where); const [fb, nb] = orde
|
|
|
292
420
|
const problems = findings.filter(f => f.level === '✗');
|
|
293
421
|
const warnings = findings.filter(f => f.level === '!');
|
|
294
422
|
const plural = (n, w) => `${n} ${w}${n === 1 ? '' : 's'}`;
|
|
295
|
-
if (!changed.size) console.log(`rn-check: no changed
|
|
423
|
+
if (!changed.size && !findings.length) console.log(`rn-check: no changed code or flows since ${since}`);
|
|
296
424
|
else if (!findings.length) console.log(`rn-check: nothing to report in the lines changed since ${since}`);
|
|
297
425
|
else console.log(`rn-check: ${plural(problems.length, 'problem')}, ${plural(warnings.length, 'warning')} in the lines changed since ${since}`);
|
|
298
426
|
for (const f of [...problems, ...warnings]) console.log(` ${f.level} ${f.where} ${f.message}`);
|
|
427
|
+
if (noMaestro && [...changed.keys()].some(flowFile)) console.log(' flows not syntax-checked: Maestro isn\'t installed here');
|
|
299
428
|
if (!boundary) console.log(` ! the app has no error boundary: a render error shows a blank screen or closes the app. Wrap the app in one`);
|
|
300
429
|
if (kept.length) console.log(` kept with amk-ok: ${[...new Set(kept)].join('; ')}`);
|
|
301
430
|
if (problems.length) {
|
|
302
|
-
console.log(` Each ✗ fails verify.sh quick. Ask the user, for each one: fix it, or keep the line with \`// amk-ok ${today}: <their reason>\` on it.`);
|
|
431
|
+
console.log(` Each ✗ fails verify.sh quick. Ask the user, for each one: fix it, or keep the line with \`// amk-ok ${today}: <their reason>\` on it (# in a flow).`);
|
|
303
432
|
console.log(' Never add an amk-ok without the user\'s reason. One kept over two weeks ago comes back when its file changes: ask again, and to keep it, write today\'s date.');
|
|
304
433
|
}
|
|
305
434
|
if (warnings.length || !boundary) console.log(' Fix each ! in the code this task changed, or tell the user why it stays.');
|
|
@@ -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
|
|
|
@@ -644,6 +752,10 @@ device_width() {
|
|
|
644
752
|
/Physical size/ { split($2, s, "x"); w = s[1] + 0 < s[2] + 0 ? s[1] : s[2] } /Physical density/ { d = $2 }
|
|
645
753
|
END { if (d) print int(w * 160 / d) }'
|
|
646
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
|
+
}
|
|
647
759
|
avd_home=${ANDROID_AVD_HOME:-${ANDROID_USER_HOME:-$HOME/.android}/avd}
|
|
648
760
|
# an AVD's folder: its .ini names it (an AVD can be renamed, and keep its folder), else <name>.avd
|
|
649
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}"; }
|
|
@@ -920,6 +1032,7 @@ plan() {
|
|
|
920
1032
|
console.log(Math.round(os.totalmem() / 2 ** 30), Math.round(s.bavail * s.bsize / 2 ** 30))')
|
|
921
1033
|
mem=$1
|
|
922
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
|
|
923
1036
|
have="$mem GB of memory, $2 GB free disk, Maestro $(maestro_version)"
|
|
924
1037
|
# the devices to check, phones first and the platforms mixed, so a round of two has one of each
|
|
925
1038
|
# (each platform's screens are read first: grep -q stops reading at its first match, and a writer still going then
|
|
@@ -1019,5 +1132,11 @@ case $mode in
|
|
|
1019
1132
|
*) echo "verify: unknown mode $mode (quick, ios, android, all, build or plan)"; exit 2 ;;
|
|
1020
1133
|
esac
|
|
1021
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
|
|
1022
1141
|
echo "Evidence: ${evidence#"$root"/}/ (open the screenshots: a tool saying 'passed' isn't proof)"
|
|
1023
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}`);
|