mobile-automator 0.36.1 → 0.38.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +6 -6
- package/bin/mauto-session-daemon.js +1 -1
- package/package.json +2 -2
- package/src/cli.js +105 -27
- package/src/config/manager.js +6 -9
- package/src/device/action-catalog.js +2 -1
- package/src/device/connection.js +1 -1
- package/src/device/engine-hints.js +1 -1
- package/src/device/failure-probe.js +2 -0
- package/src/device/selection.js +2 -2
- package/src/device/session-daemon.js +1 -1
- package/src/device/session-handle.js +1 -1
- package/src/device/session-paths.js +3 -2
- package/src/device/session-salt.js +1 -1
- package/src/device/session-spawn.js +1 -1
- package/src/guide/content/execute.agnostic.md +9 -9
- package/src/guide/content/execute.aware.md +8 -8
- package/src/guide/content/generate.agnostic.md +6 -6
- package/src/guide/content/generate.aware.md +6 -6
- package/src/guide/content/setup.agnostic.md +1 -1
- package/src/guide/content/setup.aware.md +1 -1
- package/src/guide/emitter.js +1 -1
- package/src/init/skill-meta.js +1 -1
- package/src/mcp/prompts.js +1 -1
- package/src/memory/paths.js +3 -5
- package/src/observe/failure-capture.js +10 -8
- package/src/observe/paths.js +4 -12
- package/src/observe/sinks/file.js +4 -3
- package/src/observe/spool.js +3 -2
- package/src/output/envelope.js +10 -0
- package/src/result/flags.js +61 -1
- package/src/result/store.js +10 -11
- package/src/scenario/replayability.js +2 -2
- package/src/schemas/config_schema.json +1 -1
- package/src/schemas/result_schema.json +1 -1
- package/src/schemas/scenario_schema.json +3 -3
- package/src/setup/scaffold.js +3 -2
- package/src/util/log-rotate.js +2 -2
- package/src/workspace/discover.js +56 -9
- package/src/workspace/layout.js +26 -0
package/README.md
CHANGED
|
@@ -46,10 +46,10 @@ npm install && npm link
|
|
|
46
46
|
```bash
|
|
47
47
|
cd ~/projects/my-app
|
|
48
48
|
mauto init --agent claude # or: cursor | gemini | copilot | agents | all
|
|
49
|
-
mauto setup # scaffolds mobile-automator/ + config
|
|
49
|
+
mauto setup # scaffolds .mobile-automator/ + config
|
|
50
50
|
```
|
|
51
51
|
|
|
52
|
-
`init` installs native Agent Skills into each host's skills directory and writes agent command files + MCP server entry (`.claude/commands/` + `.mcp.json` for Claude Code; `.cursor/` for Cursor). `setup` creates the
|
|
52
|
+
`init` installs native Agent Skills into each host's skills directory and writes agent command files + MCP server entry (`.claude/commands/` + `.mcp.json` for Claude Code; `.cursor/` for Cursor). `setup` creates the `.mobile-automator/` workspace. Add `--mode agnostic` to `setup` for cross-platform apps (Flutter/RN/KMP/CMP).
|
|
53
53
|
|
|
54
54
|
**3. Check your device is visible:**
|
|
55
55
|
|
|
@@ -71,7 +71,7 @@ Open your agent in the project. In **Claude Code**, `init` installs slash comman
|
|
|
71
71
|
|
|
72
72
|
In **Cursor**, `init` installs a project rule instead — just ask the agent in plain language (e.g. *"generate a login test"* / *"execute the login scenario"*) and it follows the same workflow. **Any other agent:** see [Using another agent](#-using-another-agent) below.
|
|
73
73
|
|
|
74
|
-
That's it. Scenarios land in
|
|
74
|
+
That's it. Scenarios land in `.mobile-automator/scenarios/`, results in `.mobile-automator/results/`.
|
|
75
75
|
|
|
76
76
|
**Upgrading:** after `npm i -g mobile-automator@latest`, re-run `mauto init --agent <host>` in each project to refresh the skills, rules and commands it installed. Until you do, `mauto guide` starts with a notice that the host integration is out of date, and `mauto doctor` reports which hosts need refreshing.
|
|
77
77
|
|
|
@@ -108,7 +108,7 @@ Either way the workspace, scenarios, and schemas are identical — the agent is
|
|
|
108
108
|
|
|
109
109
|
## 🔀 Platform modes
|
|
110
110
|
|
|
111
|
-
Chosen at `mauto setup` (stored in
|
|
111
|
+
Chosen at `mauto setup` (stored in `.mobile-automator/config.json`):
|
|
112
112
|
|
|
113
113
|
| Mode | Best for | Enable |
|
|
114
114
|
|------|----------|--------|
|
|
@@ -140,7 +140,7 @@ Most low-level verbs are called **by the agent**, not by you. The ones you'll ru
|
|
|
140
140
|
|---------|--------------|
|
|
141
141
|
| `mauto init --agent <claude\|cursor\|gemini\|copilot\|agents\|all>` | Install native Agent Skills into each host's skills directory; also writes slash-commands/rules + MCP entry for claude/cursor |
|
|
142
142
|
| `mauto doctor` | Report whether the integration `init` installed is missing or out of date, and the `init` command that refreshes it |
|
|
143
|
-
| `mauto setup [--mode aware\|agnostic]` | Scaffold the
|
|
143
|
+
| `mauto setup [--mode aware\|agnostic]` | Scaffold the `.mobile-automator/` workspace + config |
|
|
144
144
|
| `mauto devices` · `devices use <id>` · `devices clear` | List / pin / unpin the target device |
|
|
145
145
|
| `mauto guide <generate\|execute\|setup>` | Print the workflow guidance for a topic |
|
|
146
146
|
| `mauto mcp` | Run the MCP prompts server (for any MCP-capable agent) |
|
|
@@ -161,7 +161,7 @@ Run `mauto <command> --help` for full flags.
|
|
|
161
161
|
After `mauto setup`:
|
|
162
162
|
|
|
163
163
|
```
|
|
164
|
-
mobile-automator/
|
|
164
|
+
.mobile-automator/
|
|
165
165
|
├── config.json # mode, environments, project config
|
|
166
166
|
├── scenarios/ # test scenarios (JSON, schema 2.1)
|
|
167
167
|
├── screenshots/ # reference screenshots
|
|
@@ -79,7 +79,7 @@ async function main() {
|
|
|
79
79
|
// degrades rather than throwing.
|
|
80
80
|
//
|
|
81
81
|
// The stderr sink is deliberately left in place: the daemon's stderr IS
|
|
82
|
-
// mobile-automator/.session/daemon.log (PR #176), not a terminal, which
|
|
82
|
+
// .mobile-automator/.session/daemon.log (PR #176), not a terminal, which
|
|
83
83
|
// inverts cli.js finish()'s calculus — a warn line here costs a human no
|
|
84
84
|
// terminal noise and lands next to the adb/simctl output that explains it.
|
|
85
85
|
//
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mobile-automator",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.38.1",
|
|
4
4
|
"description": "Host-agnostic mauto CLI for AI-driven mobile QA automation — analyzes a mobile project and drives devices through mobile-mcp.",
|
|
5
5
|
"homepage": "https://github.com/sh3lan93/mobile-automator#readme",
|
|
6
6
|
"repository": {
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"test:all": "jest"
|
|
35
35
|
},
|
|
36
36
|
"dependencies": {
|
|
37
|
-
"@mobilenext/mobile-mcp": "1.0.
|
|
37
|
+
"@mobilenext/mobile-mcp": "1.0.15",
|
|
38
38
|
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
39
39
|
"ajv": "^8.20.0",
|
|
40
40
|
"commander": "^12.1.0"
|
package/src/cli.js
CHANGED
|
@@ -13,7 +13,7 @@ const { ScenarioValidator } = require('./scenario/validator');
|
|
|
13
13
|
const { findReplayWarnings, summarize } = require('./scenario/replayability');
|
|
14
14
|
const { evaluate, MECHANICAL_TYPES } = require('./assertion/evaluator');
|
|
15
15
|
const { ResultStore } = require('./result/store');
|
|
16
|
-
const { OBSERVATION_TYPES, parseObservation, parseCapture, parseBool } = require('./result/flags');
|
|
16
|
+
const { OBSERVATION_TYPES, parseObservation, parseCapture, parseBool, parseRunStatus, parseStepStatus } = require('./result/flags');
|
|
17
17
|
const { MemoryStore } = require('./memory/store');
|
|
18
18
|
const { FILES: MEMORY_FILES, AGENT_KINDS } = require('./memory/paths');
|
|
19
19
|
const { validateEntryText, MAX_ENTRY_LEN } = require('./memory/entries');
|
|
@@ -41,7 +41,11 @@ const observeTelemetry = require('./observe/telemetry');
|
|
|
41
41
|
const observeSpool = require('./observe/spool');
|
|
42
42
|
const observeTransport = require('./observe/transport');
|
|
43
43
|
const { makeFlusher } = require('./observe/flush');
|
|
44
|
-
const {
|
|
44
|
+
const {
|
|
45
|
+
findWorkspaceRoot,
|
|
46
|
+
workspaceFailure,
|
|
47
|
+
legacyWorkspaceFailure,
|
|
48
|
+
} = require('./workspace/discover');
|
|
45
49
|
|
|
46
50
|
// Commander throws (via exitOverride) for two very different reasons, and the
|
|
47
51
|
// split below is the ONLY thing that tells them apart.
|
|
@@ -562,8 +566,11 @@ async function handlePress({ deviceBridge }, button) {
|
|
|
562
566
|
}
|
|
563
567
|
|
|
564
568
|
// Build an assertion object from CLI flags, fetch the current element list,
|
|
565
|
-
// and run the pure evaluator. A
|
|
566
|
-
//
|
|
569
|
+
// and run the pure evaluator. A decided failure is a test outcome, not a tool
|
|
570
|
+
// fault: it exits 6 (`test_failed`, #273) so CI sees red without parsing JSON,
|
|
571
|
+
// with the verdict still in `data`. A pass and an undecided Tier-2 verdict
|
|
572
|
+
// (`needs_agent`) stay ok / exit 0. Only an unknown assertion type is a
|
|
573
|
+
// structural (invalid_input) error.
|
|
567
574
|
async function handleAssert({ deviceBridge }, type, flags = {}) {
|
|
568
575
|
if (!KNOWN_ASSERTION_TYPES.has(type)) {
|
|
569
576
|
return {
|
|
@@ -596,19 +603,24 @@ async function handleAssert({ deviceBridge }, type, flags = {}) {
|
|
|
596
603
|
`Record it: mauto result add-assertion --run-id <run_id> --step-id <step_id> ` +
|
|
597
604
|
`--type ${r.type} --pass ${verdict} --message "<why>"`;
|
|
598
605
|
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
needs_agent: r.needs_agent,
|
|
606
|
-
message: r.message,
|
|
607
|
-
},
|
|
608
|
-
hint
|
|
609
|
-
),
|
|
610
|
-
exitKind: 'ok',
|
|
606
|
+
const verdictData = {
|
|
607
|
+
type: r.type,
|
|
608
|
+
mechanical: r.mechanical,
|
|
609
|
+
pass: r.pass,
|
|
610
|
+
needs_agent: r.needs_agent,
|
|
611
|
+
message: r.message,
|
|
611
612
|
};
|
|
613
|
+
|
|
614
|
+
// Same data, same hint on both paths: an agent that reads `data` and copies
|
|
615
|
+
// the hint keeps working; only the exit code and `ok` change on a failure.
|
|
616
|
+
if (!r.needs_agent && r.pass === false) {
|
|
617
|
+
return {
|
|
618
|
+
envelope: fail('test_failed', `assertion failed: ${r.message}`, hint, verdictData),
|
|
619
|
+
exitKind: 'test_failed',
|
|
620
|
+
};
|
|
621
|
+
}
|
|
622
|
+
|
|
623
|
+
return { envelope: ok(verdictData, hint), exitKind: 'ok' };
|
|
612
624
|
}
|
|
613
625
|
|
|
614
626
|
// Collect a repeatable flag's values into an array (commander's collector).
|
|
@@ -623,6 +635,19 @@ function handleResultAddStep({ resultStoreFactory, projectRoot }, opts) {
|
|
|
623
635
|
};
|
|
624
636
|
}
|
|
625
637
|
|
|
638
|
+
// The status flag is a schema enum, not free text: an unknown value used to
|
|
639
|
+
// be silently recorded as 'error' — a mislabelled step with a green exit —
|
|
640
|
+
// because 'error' was the catch-all of the normalizer rather than an explicit
|
|
641
|
+
// acceptance (#286 review). Same all-or-nothing rule as the composite flags
|
|
642
|
+
// below: reject BEFORE the store is touched, so nothing is half-recorded.
|
|
643
|
+
const parsedStatus = parseStepStatus(status);
|
|
644
|
+
if (parsedStatus.error) {
|
|
645
|
+
return {
|
|
646
|
+
envelope: fail('invalid_input', parsedStatus.error, 'Valid values: pass | fail | skipped | error.'),
|
|
647
|
+
exitKind: 'invalid_input',
|
|
648
|
+
};
|
|
649
|
+
}
|
|
650
|
+
|
|
626
651
|
// Parse every composite flag BEFORE touching the store: a half-recorded step
|
|
627
652
|
// (screenshot persisted, observation rejected) leaves the agent unable to
|
|
628
653
|
// tell which half landed, so validation is all-or-nothing.
|
|
@@ -653,7 +678,9 @@ function handleResultAddStep({ resultStoreFactory, projectRoot }, opts) {
|
|
|
653
678
|
const store = resultStoreFactory({ runId, scenarioId, projectRoot });
|
|
654
679
|
const step = store.addStep({
|
|
655
680
|
step_id: stepId,
|
|
656
|
-
status,
|
|
681
|
+
// The VALIDATED status: validated AND normalized at the boundary, so the
|
|
682
|
+
// store only ever records schema values.
|
|
683
|
+
status: parsedStatus.value,
|
|
657
684
|
attempts: attempts === undefined ? 1 : Number(attempts),
|
|
658
685
|
screenshot: screenshot === undefined ? null : screenshot,
|
|
659
686
|
error_message: errorMessage === undefined ? null : errorMessage,
|
|
@@ -797,6 +824,26 @@ function handleResultFinalize({ resultStoreFactory, memoryStoreFactory, projectR
|
|
|
797
824
|
};
|
|
798
825
|
}
|
|
799
826
|
|
|
827
|
+
// The status flag is a schema enum, not free text: an unlisted value (a case
|
|
828
|
+
// variant of a documented word, a typo) used to be persisted verbatim — a
|
|
829
|
+
// schema-invalid result file with ok:true and exit 0 — directly under the
|
|
830
|
+
// exit-6 contract keyed on that status (#286 review). Reject before anything
|
|
831
|
+
// is written. A provided-but-empty value is NOT an omitted one: only absence
|
|
832
|
+
// derives the status from the recorded assertions.
|
|
833
|
+
if (status !== undefined) {
|
|
834
|
+
const parsed = parseRunStatus(status);
|
|
835
|
+
if (parsed.error) {
|
|
836
|
+
return {
|
|
837
|
+
envelope: fail(
|
|
838
|
+
'invalid_input',
|
|
839
|
+
parsed.error,
|
|
840
|
+
'Valid values: passed | failed | error, or omit --status to derive it from the recorded assertions.'
|
|
841
|
+
),
|
|
842
|
+
exitKind: 'invalid_input',
|
|
843
|
+
};
|
|
844
|
+
}
|
|
845
|
+
}
|
|
846
|
+
|
|
800
847
|
// Only provided keys: `defaultMetadata` fills the rest with 'unknown', and
|
|
801
848
|
// the result schema requires all five fields to be strings, so threading
|
|
802
849
|
// `undefined` through would break conformance.
|
|
@@ -850,6 +897,24 @@ function handleResultFinalize({ resultStoreFactory, memoryStoreFactory, projectR
|
|
|
850
897
|
if (memHint) hints.push(memHint);
|
|
851
898
|
}
|
|
852
899
|
|
|
900
|
+
// The exit code is keyed on the FINALIZED status, not the --status flag:
|
|
901
|
+
// with the flag omitted, the store derives 'failed' from a failed assertion,
|
|
902
|
+
// and the exit code must agree with the file either way (#273). 'error' takes
|
|
903
|
+
// the same path — a run that errored is not a pass for CI either; data.status
|
|
904
|
+
// tells the two apart. Everything above (write, retention, harvest) has
|
|
905
|
+
// already run: exit 6 is a verdict about the app, not a reason to lose the
|
|
906
|
+
// record of it.
|
|
907
|
+
if (result.status === 'failed' || result.status === 'error') {
|
|
908
|
+
const hint = hints.length
|
|
909
|
+
? hints.join(' ')
|
|
910
|
+
: 'See data.steps_executed and data.assertion_results for what failed; ' +
|
|
911
|
+
`the result is saved to ${path.relative(projectRoot, store.file)}.`;
|
|
912
|
+
return {
|
|
913
|
+
envelope: fail('test_failed', `run ${runId} ${result.status}`, hint, result),
|
|
914
|
+
exitKind: 'test_failed',
|
|
915
|
+
};
|
|
916
|
+
}
|
|
917
|
+
|
|
853
918
|
return { envelope: ok(result, hints.length ? hints.join(' ') : null), exitKind: 'ok' };
|
|
854
919
|
}
|
|
855
920
|
|
|
@@ -873,7 +938,13 @@ function storeHint(store) {
|
|
|
873
938
|
// still scaffolds in cwd — it is the one verb whose job is to create a
|
|
874
939
|
// workspace where the user stands — but a nested workspace silently shadows
|
|
875
940
|
// the ancestor for every later verb run below it, so say so.
|
|
876
|
-
|
|
941
|
+
//
|
|
942
|
+
// `legacyRoot` is the pre-rename workspace discovery found at or above cwd, if
|
|
943
|
+
// any (and no new workspace beside or above it). Discovery owns that walk, so
|
|
944
|
+
// setup honours the same answer every other verb does: checking only cwd let
|
|
945
|
+
// `mauto setup` from a subdirectory scaffold a nested workspace under a legacy
|
|
946
|
+
// project, the split state this refusal exists to prevent.
|
|
947
|
+
function handleSetup({ projectRoot, ancestorRoot = null, legacyRoot = null }, opts = {}) {
|
|
877
948
|
const raw = opts.mode === undefined ? 'aware' : String(opts.mode);
|
|
878
949
|
const mode = MODE_ALIASES[raw];
|
|
879
950
|
if (!mode) {
|
|
@@ -882,6 +953,10 @@ function handleSetup({ projectRoot, ancestorRoot = null }, opts = {}) {
|
|
|
882
953
|
exitKind: 'invalid_input',
|
|
883
954
|
};
|
|
884
955
|
}
|
|
956
|
+
// Scaffolding beside an un-migrated legacy workspace would fork the user's
|
|
957
|
+
// state into two directories. Discovery reports no legacy root once a new
|
|
958
|
+
// workspace exists, so a user mid-recovery gets through.
|
|
959
|
+
if (legacyRoot) return legacyWorkspaceFailure(legacyRoot);
|
|
885
960
|
const r = scaffold(projectRoot, { mode });
|
|
886
961
|
const hint = ancestorRoot
|
|
887
962
|
? `An existing workspace was found in an ancestor directory (${ancestorRoot}). This new workspace in ${projectRoot} shadows it for every mauto verb run from here or below; remove it if you meant to use the ancestor's.`
|
|
@@ -1725,8 +1800,8 @@ function buildProgram(deps = {}) {
|
|
|
1725
1800
|
workspace = deps.projectRoot !== undefined
|
|
1726
1801
|
? { root: deps.projectRoot, searched: [deps.projectRoot] }
|
|
1727
1802
|
: findWorkspaceRoot(cwd),
|
|
1728
|
-
// Project root used to resolve mobile-automator/results/ — and, through the
|
|
1729
|
-
// emitters below, mobile-automator/.logs/. One root, one tree. The
|
|
1803
|
+
// Project root used to resolve .mobile-automator/results/ — and, through the
|
|
1804
|
+
// emitters below, .mobile-automator/.logs/. One root, one tree. The
|
|
1730
1805
|
// discovered workspace when there is one; cwd otherwise, which is what the
|
|
1731
1806
|
// tolerant verbs (guide, mcp, read-only device/session) have always used.
|
|
1732
1807
|
projectRoot = workspace.root || cwd,
|
|
@@ -1827,7 +1902,7 @@ function buildProgram(deps = {}) {
|
|
|
1827
1902
|
// (exit 5) naming where we looked, so the agent can recover.
|
|
1828
1903
|
const requireWorkspace = (action) => (...args) => {
|
|
1829
1904
|
if (!workspace.root) {
|
|
1830
|
-
emit(
|
|
1905
|
+
emit(workspaceFailure(workspace), humanFlag());
|
|
1831
1906
|
return undefined;
|
|
1832
1907
|
}
|
|
1833
1908
|
return action(...args);
|
|
@@ -1867,7 +1942,7 @@ function buildProgram(deps = {}) {
|
|
|
1867
1942
|
let close;
|
|
1868
1943
|
try {
|
|
1869
1944
|
// autostart: the daemon is a per-workspace artifact — its .session/ tree
|
|
1870
|
-
// and logs live under mobile-automator/. With no discovered workspace
|
|
1945
|
+
// and logs live under .mobile-automator/. With no discovered workspace
|
|
1871
1946
|
// there is nowhere legitimate to put one, so never autostart: the verb
|
|
1872
1947
|
// connects one-shot and creates nothing. `ok:true` plus a phantom
|
|
1873
1948
|
// workspace is the exact #188 pathology.
|
|
@@ -2198,13 +2273,16 @@ function buildProgram(deps = {}) {
|
|
|
2198
2273
|
|
|
2199
2274
|
program
|
|
2200
2275
|
.command('setup')
|
|
2201
|
-
.description('Scaffold the workspace (mobile-automator/) and write a config')
|
|
2276
|
+
.description('Scaffold the workspace (.mobile-automator/) and write a config')
|
|
2202
2277
|
.option('--mode <mode>', 'aware (platform-aware, default) | agnostic (platform-agnostic)')
|
|
2203
2278
|
.action(withEnvelope((opts) => {
|
|
2204
2279
|
// cwd, not the discovered root: setup creates a workspace where the user
|
|
2205
2280
|
// stands. A discovered root that is not cwd is an ancestor worth naming.
|
|
2206
2281
|
const ancestorRoot = workspace.root && workspace.root !== cwd ? workspace.root : null;
|
|
2207
|
-
const r = handleSetup(
|
|
2282
|
+
const r = handleSetup(
|
|
2283
|
+
{ projectRoot: cwd, ancestorRoot, legacyRoot: workspace.legacy || null },
|
|
2284
|
+
{ mode: opts.mode }
|
|
2285
|
+
);
|
|
2208
2286
|
emit(r, humanFlag());
|
|
2209
2287
|
}));
|
|
2210
2288
|
|
|
@@ -2388,12 +2466,12 @@ function buildProgram(deps = {}) {
|
|
|
2388
2466
|
.description('Inspect and control anonymous usage telemetry (off by default)');
|
|
2389
2467
|
|
|
2390
2468
|
// requireWorkspace, same as config get/set: telemetry status/enable/disable
|
|
2391
|
-
// all read or write mobile-automator/config.json, and flush reads/claims
|
|
2392
|
-
// mobile-automator/.logs/telemetry.spool, so all four have #188's exact
|
|
2469
|
+
// all read or write .mobile-automator/config.json, and flush reads/claims
|
|
2470
|
+
// .mobile-automator/.logs/telemetry.spool, so all four have #188's exact
|
|
2393
2471
|
// failure mode without the gate — status would report the SAME
|
|
2394
2472
|
// not_configured/no_token answer for "no workspace here" as for "a real,
|
|
2395
2473
|
// just-unconfigured workspace", and enable/disable would create a stray
|
|
2396
|
-
// mobile-automator/ wherever the caller happened to be standing.
|
|
2474
|
+
// .mobile-automator/ wherever the caller happened to be standing.
|
|
2397
2475
|
telemetryCmd
|
|
2398
2476
|
.command('status')
|
|
2399
2477
|
.description('Report whether telemetry is on, what would be sent, and what is queued')
|
package/src/config/manager.js
CHANGED
|
@@ -2,19 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
// Workspace config manager for the `mauto` CLI.
|
|
4
4
|
//
|
|
5
|
-
// Reads/writes mobile-automator/config.json under a project root.
|
|
5
|
+
// Reads/writes .mobile-automator/config.json under a project root.
|
|
6
6
|
// A config without an explicit `mode` is treated as `platform-aware`.
|
|
7
7
|
|
|
8
8
|
const fs = require('fs');
|
|
9
9
|
const path = require('path');
|
|
10
10
|
const { normalizeConfig } = require('./coerce');
|
|
11
|
-
|
|
12
|
-
function configDir(projectRoot) {
|
|
13
|
-
return path.join(projectRoot, 'mobile-automator');
|
|
14
|
-
}
|
|
11
|
+
const { workspaceDir } = require('../workspace/layout');
|
|
15
12
|
|
|
16
13
|
function configPath(projectRoot) {
|
|
17
|
-
return path.join(
|
|
14
|
+
return path.join(workspaceDir(projectRoot), 'config.json');
|
|
18
15
|
}
|
|
19
16
|
|
|
20
17
|
// Parsed config object, or null when the file is absent. Values written before
|
|
@@ -40,11 +37,11 @@ function get(projectRoot, key) {
|
|
|
40
37
|
}
|
|
41
38
|
|
|
42
39
|
// Load-or-{}, set the dotted path, write back preserving every other field as
|
|
43
|
-
// pretty 2-space JSON. Creates mobile-automator/ if needed.
|
|
40
|
+
// pretty 2-space JSON. Creates .mobile-automator/ if needed.
|
|
44
41
|
function set(projectRoot, key, value) {
|
|
45
42
|
const cfg = load(projectRoot) || {};
|
|
46
43
|
setPath(cfg, key, value);
|
|
47
|
-
fs.mkdirSync(
|
|
44
|
+
fs.mkdirSync(workspaceDir(projectRoot), { recursive: true });
|
|
48
45
|
fs.writeFileSync(configPath(projectRoot), JSON.stringify(cfg, null, 2) + '\n');
|
|
49
46
|
return cfg;
|
|
50
47
|
}
|
|
@@ -72,4 +69,4 @@ function setPath(obj, key, value) {
|
|
|
72
69
|
cur[parts[parts.length - 1]] = value;
|
|
73
70
|
}
|
|
74
71
|
|
|
75
|
-
module.exports = { load, resolveMode, get, set, configPath
|
|
72
|
+
module.exports = { load, resolveMode, get, set, configPath };
|
|
@@ -18,7 +18,8 @@
|
|
|
18
18
|
// 'composed' — no dedicated verb; the agent composes it from existing verbs
|
|
19
19
|
// (e.g. poll `mauto elements`, repeat `mauto swipe`). The
|
|
20
20
|
// execute guide documents the composition.
|
|
21
|
-
// 'unsupported' —
|
|
21
|
+
// 'unsupported' — no `mauto` verb reaches it: the engine has no primitive, or
|
|
22
|
+
// (clear_app_data, since 1.0.15) mauto has not wired it. Not
|
|
22
23
|
// mechanically executable; the guide must NOT promise a verb,
|
|
23
24
|
// and the agent reports it honestly / handles it manually.
|
|
24
25
|
//
|
package/src/device/connection.js
CHANGED
|
@@ -31,7 +31,7 @@ const sessionSpawn = require('./session-spawn');
|
|
|
31
31
|
// `autostart` (default true: the daemon is the normal connection path) is the
|
|
32
32
|
// daemon-vs-oneshot policy. cli.js's connectBridge passes false when no
|
|
33
33
|
// workspace was discovered (#188), so a workspace-less cwd gets a one-shot
|
|
34
|
-
// bridge and no mobile-automator/.session/ tree. `resolve` is an internal test
|
|
34
|
+
// bridge and no .mobile-automator/.session/ tree. `resolve` is an internal test
|
|
35
35
|
// seam only; verbs call acquireConnection with just
|
|
36
36
|
// { device, projectRoot, autostart }.
|
|
37
37
|
async function acquireConnection({
|
|
@@ -74,7 +74,7 @@ function deviceNotFoundHint(id) {
|
|
|
74
74
|
// directory". The engine runs from the project root (the daemon is spawned
|
|
75
75
|
// there), which is not necessarily the directory the user ran the verb from.
|
|
76
76
|
const OUTSIDE_ALLOWED_DIRS_HINT =
|
|
77
|
-
'Screenshots must be saved under the project root (the directory containing mobile-automator/) ' +
|
|
77
|
+
'Screenshots must be saved under the project root (the directory containing .mobile-automator/) ' +
|
|
78
78
|
'or the system temp directory. Choose a path inside one of them and retry.';
|
|
79
79
|
|
|
80
80
|
function engineHint(message, { mobilecliVersion = resolveMobilecliVersion } = {}) {
|
|
@@ -86,6 +86,8 @@ const PROBE_EXEMPT_VERBS = new Set(['devices', 'crash']);
|
|
|
86
86
|
// Failure kinds that can plausibly mean "the app died". invalid_input is a bad
|
|
87
87
|
// flag, target_not_found/environment/internal never reached (or never
|
|
88
88
|
// involved) the device — none of them are worth a device round trip.
|
|
89
|
+
// test_failed/incomplete are outcomes: the device answered and the app failed;
|
|
90
|
+
// the evidence is the step screenshot, not a crash list.
|
|
89
91
|
const PROBE_KINDS = new Set(['device', 'timeout']);
|
|
90
92
|
|
|
91
93
|
function shouldProbe({ envelope, verb } = {}) {
|
package/src/device/selection.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
//
|
|
5
5
|
// A chosen device id is remembered across separate one-shot verb invocations so
|
|
6
6
|
// the agent does not have to re-pass --device every call. The selection lives in
|
|
7
|
-
// #91's session layout (mobile-automator/.session/) as a small sidecar file,
|
|
7
|
+
// #91's session layout (.mobile-automator/.session/) as a small sidecar file,
|
|
8
8
|
// SEPARATE from config.json (which is user-authored project config) and from the
|
|
9
9
|
// live session handle (session.json, owned by the daemon lifecycle).
|
|
10
10
|
//
|
|
@@ -36,7 +36,7 @@ function read(projectRoot) {
|
|
|
36
36
|
}
|
|
37
37
|
}
|
|
38
38
|
|
|
39
|
-
// Persist a device id. Creates mobile-automator/.session/ if needed. Written
|
|
39
|
+
// Persist a device id. Creates .mobile-automator/.session/ if needed. Written
|
|
40
40
|
// via atomicWrite (tmp + fsync + rename) so a concurrent reader or a crash
|
|
41
41
|
// sees the old-complete or new-complete selection, never a torn one.
|
|
42
42
|
function write(projectRoot, id) {
|
|
@@ -332,7 +332,7 @@ async function startDaemon({
|
|
|
332
332
|
: (info) =>
|
|
333
333
|
// Was a bespoke process.stderr.write with its own try/catch. It is
|
|
334
334
|
// the same destination — the stderr sink writes to fd 2, which since
|
|
335
|
-
// #176 IS mobile-automator/.session/daemon.log — but now structured,
|
|
335
|
+
// #176 IS .mobile-automator/.session/daemon.log — but now structured,
|
|
336
336
|
// and safeObserve (plus record()'s own never-throw guarantee)
|
|
337
337
|
// subsumes the hand-rolled guard. That guard mattered: this runs
|
|
338
338
|
// inside reply(), on the socket's async data handler, so a throw here
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
-
// Read side of mobile-automator/.session/session.json — the ONLY one. The
|
|
3
|
+
// Read side of .mobile-automator/.session/session.json — the ONLY one. The
|
|
4
4
|
// session id it carries is minted, and its shape defined, in session-id.js.
|
|
5
5
|
// resolve-connection.js's readHandleDevice() is a projection onto the `device`
|
|
6
6
|
// field and delegates here; it used to parse the file itself, which meant two
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
// Pure path helpers for the per-workspace device session daemon.
|
|
4
4
|
//
|
|
5
|
-
// Everything lives under <projectRoot
|
|
5
|
+
// Everything lives under <projectRoot>/.mobile-automator/.session/:
|
|
6
6
|
// mauto.sock — Unix domain socket the daemon listens on
|
|
7
7
|
// daemon.pid — pidfile written once the daemon is listening
|
|
8
8
|
// session.json — handle describing the live session (device pin, socket, pid)
|
|
@@ -19,6 +19,7 @@ const fs = require('fs');
|
|
|
19
19
|
const path = require('path');
|
|
20
20
|
const os = require('os');
|
|
21
21
|
const crypto = require('crypto');
|
|
22
|
+
const { workspaceDir } = require('../workspace/layout');
|
|
22
23
|
|
|
23
24
|
const SESSION_DIRNAME = '.session';
|
|
24
25
|
const SOCKET_NAME = 'mauto.sock';
|
|
@@ -37,7 +38,7 @@ const SALT_NAME = 'marker.salt';
|
|
|
37
38
|
const SOCKET_PATH_LIMIT = 100;
|
|
38
39
|
|
|
39
40
|
function sessionDir(projectRoot) {
|
|
40
|
-
return path.join(projectRoot,
|
|
41
|
+
return path.join(workspaceDir(projectRoot), SESSION_DIRNAME);
|
|
41
42
|
}
|
|
42
43
|
|
|
43
44
|
// The canonical in-workspace socket path. Used when short enough.
|
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
// `ps` shows every process's argv to every user on the host, so the daemon's
|
|
6
6
|
// command line carries HMAC(salt, root) (session-paths.daemonMarkerKey) rather
|
|
7
7
|
// than a digest anyone could recompute from a guessed project path. The salt is
|
|
8
|
-
// 32 random bytes as hex in <root
|
|
8
|
+
// 32 random bytes as hex in <root>/.mobile-automator/.session/marker.salt, mode
|
|
9
9
|
// 0600 so only the workspace's owner can read it. It is created once and never
|
|
10
10
|
// rotated: rotating it would orphan a running daemon's marker, and no teardown
|
|
11
11
|
// deletes it (cleanStale, daemon stop and the bin's exit cleanup all unlink
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
// Spawns the device session daemon as a DETACHED background process and waits
|
|
4
4
|
// until it is reachable. The daemon's output is captured to the workspace log
|
|
5
|
-
// (mobile-automator/.session/daemon.log) instead of /dev/null, so a crashing
|
|
5
|
+
// (.mobile-automator/.session/daemon.log) instead of /dev/null, so a crashing
|
|
6
6
|
// engine leaves a readable trace behind. The spawn and openLog fns are
|
|
7
7
|
// injectable so the spawn args, the log wiring and the readiness-poll contract
|
|
8
8
|
// are all unit-testable without launching a real daemon or touching disk.
|
|
@@ -58,8 +58,8 @@ Record each observation with `mauto result add-step --observation <type>:<messag
|
|
|
58
58
|
4. **App under test.**
|
|
59
59
|
- If the user pointed you at a prebuilt app artifact, install it with `mauto install <path>`.
|
|
60
60
|
- Otherwise verify the app is already installed; if it is not, halt and ask the user to install it. This guide never builds.
|
|
61
|
-
- **Fresh install.** If the scenario's `preconditions.app_state` is `fresh_install` and the user pointed you at a prebuilt app artifact, uninstall the app first with `mauto uninstall <appId>` (the app identifier from
|
|
62
|
-
- If the install fails because a different build is already on the device, uninstall it with `mauto uninstall <appId>` (the app identifier from
|
|
61
|
+
- **Fresh install.** If the scenario's `preconditions.app_state` is `fresh_install` and the user pointed you at a prebuilt app artifact, uninstall the app first with `mauto uninstall <appId>` (the app identifier from `.mobile-automator/config.json` — `android_package` / `ios_bundle_id`) and only then install that artifact, so the run starts with no app data. Without an artifact, do not uninstall — you could not reinstall the app. Leave it in place and report that the app state was not reset, so a failure that depends on existing app data is not mistaken for a regression.
|
|
62
|
+
- If the install fails because a different build is already on the device, uninstall it with `mauto uninstall <appId>` (the app identifier from `.mobile-automator/config.json` — `android_package` / `ios_bundle_id`), install again, and report that app data was wiped — a scenario whose preconditions assume existing app state may now fail for that reason.
|
|
63
63
|
- State which path you took before continuing.
|
|
64
64
|
5. **Validate schema version:** read the `$schema_version` field; it must be `"2.1"`. If absent or unrecognized, report an error and halt.
|
|
65
65
|
6. Validate the scenario with `mauto validate <path>` against `mauto schema scenario`. If the result lists `data.warnings`, branch on each entry's `code` (its `path` names the step or precondition): `unsupported_action` means it uses an action that is unsupported on this run: report it as unsupported in the result (see "Not mechanically executable" under step execution) and do not substitute a gesture for it. `launch_cold_implicit` is advisory: replay that step exactly as written (a step that does not set `"cold": false` is a cold start, per the step table below) and do not substitute your own reading of what the author meant; record the warning's `message` as a `state_context` observation on that step (`mauto result add-step ... --observation state_context:<message>`).
|
|
@@ -69,7 +69,7 @@ Record each observation with `mauto result add-step --observation <type>:<messag
|
|
|
69
69
|
| Device action | `mauto` verb | Notes |
|
|
70
70
|
|---|---|---|
|
|
71
71
|
| `install_app` | `mauto install <path>` | `path` = the device action's `value` if set and the file exists, else the build artifact used in pre-flight. If neither is available, report this precondition as not executed |
|
|
72
|
-
| `uninstall_app` | `mauto uninstall <appId>` | `appId` = the device action's `target_package` if set, else the app identifier from
|
|
72
|
+
| `uninstall_app` | `mauto uninstall <appId>` | `appId` = the device action's `target_package` if set, else the app identifier from `.mobile-automator/config.json` (`android_package` / `ios_bundle_id`) for the connected device's platform. If a later `install_app` in the same block has no resolvable path, skip this uninstall too and report both as not executed — never leave the device without the app under test |
|
|
73
73
|
| `set_orientation` | `mauto orientation <portrait\|landscape>` | |
|
|
74
74
|
|
|
75
75
|
The remaining precondition actions are not mechanically executable (see step execution): report them honestly or perform them out of band.
|
|
@@ -104,7 +104,7 @@ For each step in the scenario:
|
|
|
104
104
|
- `launch_app` restarts the app so the step starts on its initial screen; `--resume` instead brings a running app to the front in its current state. A plain launch resets the screen, not app data: `app_state: "fresh_install"` is still the data reset. It returns `{launched, cold}`; an app that is not running is simply started. If the app cannot be stopped, the launch fails with a device error and a hint to use `--resume` — record the step as failed rather than retrying blindly.
|
|
105
105
|
- Semantic actions → run `mauto press <action>` and let the CLI resolve them for the connected device.
|
|
106
106
|
- Not mechanically executable → `clear_app_data` (and the precondition device actions `enable_wifi` / `disable_wifi`) have no verb and no underlying primitive. Do NOT substitute a gesture: report them honestly as unsupported on this run, or perform them manually out of band if the run depends on them.
|
|
107
|
-
4. **Capture screenshot:** Run `mauto screenshot mobile-automator/screenshots/<scenario_id>/<run_id>/step_<step_id>.png`.
|
|
107
|
+
4. **Capture screenshot:** Run `mauto screenshot .mobile-automator/screenshots/<scenario_id>/<run_id>/step_<step_id>.png`.
|
|
108
108
|
5. **Evaluate assertions** attached to the step (see section 4).
|
|
109
109
|
6. **Record** the step result with `mauto result add-step --step-id <id> --status <s> --screenshot <path> [--attempts <n>] [--error-message <text>] [--observation <type>:<message>] [--capture <name>=<value>]`, then record each assertion verdict with `mauto result add-assertion --step-id <id> --type <t> --pass <true|false> --message <text> [--expected <v> --actual <v>]`. `--message` carries the justification you already formed — for Tier-2 verdicts it IS the evidence, so never omit it; add `--expected`/`--actual` whenever the assertion compares a specific value.
|
|
110
110
|
|
|
@@ -176,7 +176,7 @@ switch the engine mid-run yourself.
|
|
|
176
176
|
|
|
177
177
|
For each assertion, pick the type recorded in the scenario and evaluate it. The 27 types split into two tiers by **who decides pass/fail**:
|
|
178
178
|
|
|
179
|
-
- **Tier 1 — mechanical (the CLI decides).** Deterministic checks over the on-screen element list (plus captured variables / a previous snapshot). Run `mauto elements`, then evaluate with `mauto assert <type> ...`; the CLI returns a JSON verdict (`{ mechanical: true, pass: true|false, message }`). You record that verdict — you do not re-judge it.
|
|
179
|
+
- **Tier 1 — mechanical (the CLI decides).** Deterministic checks over the on-screen element list (plus captured variables / a previous snapshot). Run `mauto elements`, then evaluate with `mauto assert <type> ...`; the CLI returns a JSON verdict (`{ mechanical: true, pass: true|false, message }`). A passing verdict arrives as a normal `ok: true` envelope. A failing one arrives as `ok: false` with `error.kind: "test_failed"` and exit code `6`, and the verdict (`pass: false`) is still in `data`. That is the test result, not a tool error: do not retry the verb or treat the run as broken. You record that verdict — you do not re-judge it.
|
|
180
180
|
- **Tier 2 — visual / semantic (the agent decides).** These require judging pixels. `mauto assert <type> ...` reports them as `needs_agent` (with `pass: null`). For these you take a screenshot with `mauto screenshot <path>`, visually analyze it, and report pass/fail yourself with a clear justification.
|
|
181
181
|
|
|
182
182
|
> One assertion type, `element_state`, names a Tier-1 intent but its per-attribute state inspection is not represented in the element model the CLI reads, so `mauto assert` returns it as `needs_agent` — judge it from the element list / screenshot like a Tier-2 check.
|
|
@@ -210,7 +210,7 @@ For each: take a screenshot, visually analyze it, and report pass/fail with a cl
|
|
|
210
210
|
|
|
211
211
|
### 5. Generate the Result Report
|
|
212
212
|
|
|
213
|
-
Obtain the result schema by running `mauto schema result`, then finalize the run with `mauto result finalize` (writing to
|
|
213
|
+
Obtain the result schema by running `mauto schema result`, then finalize the run with `mauto result finalize` (writing to `.mobile-automator/results/<run_id>.json`), passing the run metadata you already know (`--device-model`, `--api-level`, `--app-version`, `--environment`) — the timestamp is filled in for you, and omitted fields are recorded as `unknown`. You may supply your own narrative with `--summary <text>`; omitting it keeps the generated default summary line. A run that finalizes as `failed` or `error` returns `ok: false` with `error.kind: "test_failed"` and exit code `6`. The result file is still written and the full result is in `data`, so present it as usual; the non-zero exit is what lets CI see a red run. The finalized result assembles what the earlier `add-step`/`add-assertion` calls already recorded:
|
|
214
214
|
|
|
215
215
|
- `run_id`, `scenario_id`, `status`, `duration_seconds`.
|
|
216
216
|
- `steps_executed[]`: per-step status, retry_count, screenshot, error_message.
|
|
@@ -231,7 +231,7 @@ When neither attempt succeeds, fail the step and add a detailed observation desc
|
|
|
231
231
|
## Multi-Scenario Execution
|
|
232
232
|
|
|
233
233
|
- Execute scenarios sequentially. Each scenario's leading `launch_app` restarts the app (`mauto launch <appId>`), so a scenario never inherits the previous one's screen and needs no separate reset; use `app_state: "fresh_install"` only when app data must be wiped too.
|
|
234
|
-
- "run all smoke tests" → filter by the `smoke` tag. "run all" → every scenario in
|
|
234
|
+
- "run all smoke tests" → filter by the `smoke` tag. "run all" → every scenario in `.mobile-automator/scenarios/`. List `.mobile-automator/scenarios/` directly: the workspace folder is hidden, and recursive search tools (glob or grep style) skip hidden directories, so they will report it empty.
|
|
235
235
|
- Present a combined summary with a per-scenario breakdown.
|
|
236
236
|
|
|
237
237
|
## Operational Boundaries
|
|
@@ -257,8 +257,8 @@ When neither attempt succeeds, fail the step and add a detailed observation desc
|
|
|
257
257
|
|
|
258
258
|
## Resources
|
|
259
259
|
|
|
260
|
-
-
|
|
260
|
+
- **.mobile-automator/config.json**: Project configuration. Read it for any placeholder that was not filled in this guide.
|
|
261
261
|
- **`mauto schema scenario`**: JSON schema for test scenarios. Use it to validate scenarios with `mauto validate <path>`.
|
|
262
262
|
- **`mauto schema result`**: JSON schema for execution results.
|
|
263
|
-
-
|
|
263
|
+
- **.mobile-automator/scenarios/**: Source scenario files.
|
|
264
264
|
{{additional_resources}}
|