mobile-automator 0.38.4 → 0.40.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/README.md +2 -0
  2. package/package.json +4 -2
  3. package/src/assertion/evaluator.js +116 -14
  4. package/src/assertion/fields.js +106 -0
  5. package/src/assertion/observe.js +17 -0
  6. package/src/cli.js +180 -174
  7. package/src/device/action-catalog.js +4 -2
  8. package/src/device/bridge.js +17 -1
  9. package/src/device/mobile-mcp-tools.js +1 -0
  10. package/src/device/resolve-connection.js +1 -1
  11. package/src/device/semantic-press/index.js +19 -0
  12. package/src/device/semantic-press/resolver.js +1 -1
  13. package/src/{device/semantic-press/labels.js → dialog/permission-labels.js} +6 -3
  14. package/src/guide/content/execute.agnostic.md +74 -21
  15. package/src/guide/content/execute.aware.md +69 -15
  16. package/src/guide/content/execute.invariants.md +1 -0
  17. package/src/guide/content/generate.agnostic.md +3 -3
  18. package/src/guide/content/generate.aware.md +5 -5
  19. package/src/guide/emitter.js +2 -0
  20. package/src/init/host-plan.js +1 -0
  21. package/src/observe/trace.js +1 -1
  22. package/src/observe/vocab.js +6 -0
  23. package/src/output/device-fail.js +41 -0
  24. package/src/output/envelope.js +3 -3
  25. package/src/output/run-human.js +37 -0
  26. package/src/result/capability-catalog.js +48 -0
  27. package/src/result/executor.js +58 -0
  28. package/src/result/finalize-against-scenario.js +103 -0
  29. package/src/result/flags.js +49 -6
  30. package/src/result/junit.js +39 -16
  31. package/src/result/outcome.js +24 -2
  32. package/src/result/pending-hint.js +67 -0
  33. package/src/result/scenario-check.js +58 -0
  34. package/src/result/status-guard.js +46 -0
  35. package/src/result/store.js +159 -16
  36. package/src/run/actions/capture.js +21 -0
  37. package/src/run/actions/gestures.js +89 -0
  38. package/src/run/actions/index.js +48 -0
  39. package/src/run/actions/launch.js +30 -0
  40. package/src/run/actions/preconditions.js +44 -0
  41. package/src/run/actions/scroll.js +22 -0
  42. package/src/run/actions/semantic.js +16 -0
  43. package/src/run/actions/wait.js +66 -0
  44. package/src/run/assert-reference.js +118 -0
  45. package/src/run/assertions.js +102 -0
  46. package/src/run/clock.js +10 -0
  47. package/src/run/condition.js +80 -0
  48. package/src/run/fatal.js +15 -0
  49. package/src/run/handle.js +151 -0
  50. package/src/run/needs-agent.js +39 -0
  51. package/src/run/poll.js +38 -0
  52. package/src/run/prepare.js +107 -0
  53. package/src/run/reference-assertion.js +172 -0
  54. package/src/run/reference-screenshot.js +92 -0
  55. package/src/run/resolve.js +95 -0
  56. package/src/run/run-id.js +14 -0
  57. package/src/run/runner.js +104 -0
  58. package/src/run/scale.js +52 -0
  59. package/src/run/screenshots.js +163 -0
  60. package/src/run/settings.js +35 -0
  61. package/src/run/state.js +22 -0
  62. package/src/run/step.js +138 -0
  63. package/src/run/summary.js +73 -0
  64. package/src/run/trace.js +30 -0
  65. package/src/run/tree.js +96 -0
  66. package/src/run/variables.js +56 -0
  67. package/src/scenario/load.js +78 -0
  68. package/src/schemas/config_schema.json +29 -0
  69. package/src/schemas/result_schema.json +45 -3
  70. package/src/schemas/scenario_schema.json +27 -0
  71. package/src/util/as-array.js +8 -0
  72. package/src/util/parse-positive-int.js +15 -0
  73. package/src/util/parse-unit-interval.js +17 -0
@@ -0,0 +1,107 @@
1
+ 'use strict';
2
+
3
+ const fs = require('fs');
4
+ const path = require('path');
5
+
6
+ const { fail } = require('../output/envelope');
7
+ const { loadScenario } = require('../scenario/load');
8
+ const { isResultRunId } = require('../result/store');
9
+ const { resolveRunId } = require('../observe/settings');
10
+ const { makeRunId } = require('./run-id');
11
+ const { parsePositiveInt } = require('../util/parse-positive-int');
12
+
13
+ // Why the --junit path cannot take the report, or null. Checked before the
14
+ // run, so a CI job learns of a typo'd report directory before the device
15
+ // work rather than after it (atomicWrite would otherwise create the directory).
16
+ function statOf(p) {
17
+ try {
18
+ return fs.statSync(p);
19
+ } catch {
20
+ return null;
21
+ }
22
+ }
23
+
24
+ function junitRefusal(junitPath) {
25
+ const target = statOf(junitPath);
26
+ if (target && target.isDirectory()) return `--junit names a directory: ${junitPath}`;
27
+ const dir = path.dirname(junitPath);
28
+ const parent = statOf(dir);
29
+ if (!parent) return `--junit directory does not exist: ${dir}`;
30
+ if (!parent.isDirectory()) return `--junit directory is not a directory: ${dir}`;
31
+ return null;
32
+ }
33
+
34
+ // The values `mauto run --judge` accepts. Private: src/result/flags.js
35
+ // exports a different JUDGES, the ones `result add-assertion` takes.
36
+ const RUN_JUDGES = Object.freeze(['none']);
37
+
38
+ // A refusal: the envelope and the exit kind it maps to.
39
+ const refuse = (kind, message, hint) => ({ failure: { envelope: fail(kind, message, hint), exitKind: kind } });
40
+
41
+ // Everything `mauto run` decides before it touches a device, in this order:
42
+ // --judge, --timeout-ms, --junit, the scenario
43
+ // (strict: a blocking replayability finding refuses), then the run id (the
44
+ // --run-id flag, else MAUTO_RUN_ID, else minted from `now()`), which must
45
+ // name a result file. Returns `{ scenario, runId, file, sha256, timeoutMs,
46
+ // junitPath }` — `sha256` is loadScenario's hash of the file, for the run's
47
+ // executor; `timeoutMs` and `junitPath` (resolved against `cwd`) are null
48
+ // when not given — or `{ failure: { envelope, exitKind } }`.
49
+ function prepareRun({
50
+ validator, file, runId: flag, timeoutMs: timeoutFlag, judge = 'none', junit,
51
+ cwd = process.cwd(), env = process.env, now = () => new Date(),
52
+ }) {
53
+ // --judge names who decides the assertions only an agent can judge. Only
54
+ // `none` exists: the runner has no judge (R2, see src/run/assertions.js),
55
+ // so such an assertion is left needs_agent and the run ends incomplete.
56
+ // Validated, not returned: there is nothing yet for it to select.
57
+ if (!RUN_JUDGES.includes(judge)) {
58
+ return refuse(
59
+ 'invalid_input',
60
+ `unknown --judge "${judge}"`,
61
+ `Accepted: ${RUN_JUDGES.join(', ')}. With none, an assertion only an agent can judge is left needs_agent for an agent to decide.`
62
+ );
63
+ }
64
+
65
+ // The --timeout-ms flag, when given, must be a positive integer (a plain
66
+ // decimal string, or a number).
67
+ let timeoutMs = null;
68
+ if (timeoutFlag !== undefined && timeoutFlag !== null) {
69
+ timeoutMs = parsePositiveInt(timeoutFlag);
70
+ if (timeoutMs === null) {
71
+ return refuse(
72
+ 'invalid_input',
73
+ `invalid --timeout-ms "${timeoutFlag}"`,
74
+ 'Pass --timeout-ms a positive integer number of milliseconds; it caps how long any one step waits.'
75
+ );
76
+ }
77
+ }
78
+
79
+ let junitPath = null;
80
+ if (junit !== undefined && junit !== null) {
81
+ junitPath = path.resolve(cwd, String(junit));
82
+ const refusal = junitRefusal(junitPath);
83
+ if (refusal) {
84
+ return refuse(
85
+ 'invalid_input',
86
+ refusal,
87
+ 'Pass --junit a file path whose directory already exists; mauto run writes the report there after the run.'
88
+ );
89
+ }
90
+ }
91
+
92
+ const loaded = loadScenario(validator, file, { strict: true });
93
+ if (loaded.failure) return { failure: loaded.failure };
94
+
95
+ const runId = flag || resolveRunId(env) || makeRunId(now());
96
+ if (!isResultRunId(runId)) {
97
+ return refuse(
98
+ 'invalid_input',
99
+ `invalid run id "${runId}"`,
100
+ 'Pass --run-id run_YYYYMMDD_HHMMSS (or omit it to mint one); a run id names a result file and cannot contain a path separator.'
101
+ );
102
+ }
103
+
104
+ return { scenario: loaded.scenario, runId, file, sha256: loaded.sha256, timeoutMs, junitPath };
105
+ }
106
+
107
+ module.exports = { prepareRun };
@@ -0,0 +1,172 @@
1
+ 'use strict';
2
+
3
+ // The one decision behind a `screenshot_match` verdict (#281), shared by
4
+ // `mauto run` (src/run/assertions.js) and `mauto assert`
5
+ // (src/run/assert-reference.js). Both build its `input` through the one field
6
+ // mapping (src/assertion/fields.js: toEvaluatorInput / fromCliFlags) and its
7
+ // paths through ./screenshots.js (runArtifacts / assertArtifacts), then
8
+ // capture, mask and compare here the same way, so the same screen cannot
9
+ // verdict differently by path.
10
+ //
11
+ // capture a stable frame -> (update: record it as the baseline)
12
+ // -> (no baseline: needs_agent) -> resolve masks -> compare -> verdict
13
+ //
14
+ // A missing baseline is not a failure: it is left to an agent (or to a re-run
15
+ // with --update-references), as any undecided assertion is.
16
+
17
+ const fs = require('fs');
18
+ const path = require('path');
19
+
20
+ const { compareScreenshots, DEFAULT_TOLERANCE } = require('./reference-screenshot');
21
+ const { captureStable, writeReference } = require('./screenshots');
22
+ const { scaleFactor, pointsToPixels, boundsToRect, pngSize } = require('./scale');
23
+ const { timeoutFor } = require('./poll');
24
+ const { parseUnitInterval } = require('../util/parse-unit-interval');
25
+
26
+ const RECT_KEYS = ['x', 'y', 'width', 'height'];
27
+
28
+ // A scenario's `tolerance` (or the --tolerance flag, already a number): the
29
+ // default when absent, else a number in [0, 1].
30
+ function toleranceOf(value) {
31
+ if (value === undefined || value === null) return DEFAULT_TOLERANCE;
32
+ const n = parseUnitInterval(value);
33
+ if (n === null) throw new Error(`tolerance must be a number from 0 to 1 (got ${JSON.stringify(value)})`);
34
+ return n;
35
+ }
36
+
37
+ // One mask, checked: `{ element_description }` or `{ x, y, width, height }`
38
+ // (numbers >= 0, in element/screen coordinates).
39
+ function maskOf(mask, i) {
40
+ if (mask && typeof mask === 'object' && typeof mask.element_description === 'string' && mask.element_description.trim() !== '') {
41
+ return { element_description: mask.element_description };
42
+ }
43
+ if (mask && typeof mask === 'object' && RECT_KEYS.every((k) => typeof mask[k] === 'number' && Number.isFinite(mask[k]) && mask[k] >= 0)) {
44
+ return { x: mask.x, y: mask.y, width: mask.width, height: mask.height };
45
+ }
46
+ throw new Error(`mask ${i + 1} must be { element_description } or { x, y, width, height } numbers >= 0 (got ${JSON.stringify(mask)})`);
47
+ }
48
+
49
+ function masksOf(masks) {
50
+ if (masks === undefined || masks === null) return [];
51
+ if (!Array.isArray(masks)) throw new Error('masks must be an array');
52
+ return masks.map(maskOf);
53
+ }
54
+
55
+ // `mauto assert --mask <spec>`: four comma-separated numbers are a rect
56
+ // `x,y,width,height`; anything else is an element description.
57
+ function parseMaskSpec(spec) {
58
+ const raw = String(spec);
59
+ const parts = raw.split(',').map((p) => p.trim());
60
+ if (parts.length === 4 && parts.every((p) => p !== '' && Number.isFinite(Number(p)))) {
61
+ const [x, y, width, height] = parts.map(Number);
62
+ return maskOf({ x, y, width, height }, 0);
63
+ }
64
+ return maskOf({ element_description: raw }, 0);
65
+ }
66
+
67
+ const fmt = (n) => n.toFixed(3);
68
+
69
+ // The pixel rects the masks cover on `actualPath`, or `{ missing }` naming the
70
+ // first element description nothing on screen matches. The screen size is
71
+ // asked for only when there is a mask to scale.
72
+ async function pixelMasks(masks, { bridge, actualPath, findFirst }) {
73
+ if (masks.length === 0) return { rects: [] };
74
+ const factor = scaleFactor(pngSize(actualPath).width, await bridge.getScreenSize());
75
+ let elements = null;
76
+ const rects = [];
77
+ for (const mask of masks) {
78
+ let rect = mask;
79
+ if (mask.element_description !== undefined) {
80
+ if (!elements) elements = await bridge.listElements();
81
+ const found = findFirst(elements, mask.element_description);
82
+ if (!found) return { missing: mask.element_description };
83
+ rect = boundsToRect(found.bounds);
84
+ }
85
+ rects.push(pointsToPixels(rect, factor));
86
+ }
87
+ return { rects };
88
+ }
89
+
90
+ // Decide one screenshot_match.
91
+ // input the evaluator input ({ type, reference_screenshot?, tolerance? })
92
+ // masks the assertion's masks (scenario objects, or parsed --mask specs)
93
+ // paths { reference, actual, diff }, absolute (./screenshots.js)
94
+ // The capture's poll budget is the run settings' (timeoutFor / pollMs).
95
+ // Returns { verdict, diff }: `verdict` is the record body
96
+ // { status: 'passed' | 'failed' | 'needs_agent', message, mechanical, judge,
97
+ // reference_screenshot, actual_screenshot, similarity_score }
98
+ // with paths relative to `projectRoot` (similarity_score null when nothing was
99
+ // compared), and `diff` the project-relative diff image, or null when none was
100
+ // written. Throws only on a device or file error (and on a bad tolerance or
101
+ // mask, before the device is touched).
102
+ async function decideReferenceScreenshot({
103
+ bridge, clock, settings, projectRoot, input, masks, paths, updateReferences = false, findFirst,
104
+ }) {
105
+ const tol = toleranceOf(input.tolerance);
106
+ const checkedMasks = masksOf(masks);
107
+ const timeoutMs = timeoutFor({}, settings);
108
+ const rel = (p) => (p ? path.relative(projectRoot, p) : null);
109
+ const capture = await captureStable({ bridge, dest: paths.actual, clock, timeoutMs, pollMs: settings.pollMs });
110
+ const unsettled = capture.stable ? '' : ` (the screen did not settle within ${timeoutMs}ms; the last of ${capture.frames} frames was used)`;
111
+ const referenceRel = rel(paths.reference);
112
+ const record = (status, message, { mechanical = true, judge = { by: 'reference_screenshot' }, similarity = null } = {}) => ({
113
+ status,
114
+ message,
115
+ mechanical,
116
+ judge,
117
+ reference_screenshot: referenceRel,
118
+ actual_screenshot: rel(paths.actual),
119
+ similarity_score: similarity,
120
+ });
121
+ const decided = (status, message, similarity = null) => ({ verdict: record(status, message, { similarity }), diff: null });
122
+
123
+ if (updateReferences) {
124
+ // A baseline is what every later run is held to: a frame of a screen
125
+ // still moving would make them all fail (or pass) for the wrong reason,
126
+ // so an unsettled screen records nothing.
127
+ if (!capture.stable) {
128
+ return decided(
129
+ 'failed',
130
+ `screen did not settle within ${timeoutMs}ms; no reference recorded (${capture.frames} frames captured)`
131
+ );
132
+ }
133
+ writeReference(paths.actual, paths.reference);
134
+ return decided('passed', `reference updated (--update-references): ${referenceRel}`, 1);
135
+ }
136
+ if (!fs.existsSync(paths.reference)) {
137
+ return {
138
+ verdict: record(
139
+ 'needs_agent',
140
+ `no reference screenshot at ${referenceRel}; re-run with --update-references to record it from this screen`,
141
+ { mechanical: false, judge: { by: 'none' } }
142
+ ),
143
+ diff: null,
144
+ };
145
+ }
146
+
147
+ const { rects, missing } = await pixelMasks(checkedMasks, { bridge, actualPath: paths.actual, findFirst });
148
+ if (missing !== undefined) {
149
+ return decided('failed', `mask element "${missing}" was not found on screen, so the comparison cannot ignore it`);
150
+ }
151
+
152
+ const r = compareScreenshots({
153
+ referencePath: paths.reference, actualPath: paths.actual, tolerance: tol, masks: rects, diffPath: paths.diff,
154
+ });
155
+ if (r.dimensionsMismatch) {
156
+ const { reference: a, actual: b } = r.dimensionsMismatch;
157
+ return decided(
158
+ 'failed',
159
+ `screenshot size does not match reference ${referenceRel}: reference is ${a.width}x${a.height}, ` +
160
+ `actual is ${b.width}x${b.height}; never resampled (record a reference for this device with --update-references)`
161
+ );
162
+ }
163
+ const diff = rel(r.diffPath);
164
+ const message = r.pass
165
+ ? `screenshot matches reference ${referenceRel}: similarity ${fmt(r.similarity)} >= tolerance ${fmt(tol)}${unsettled}`
166
+ : `screenshot differs from reference ${referenceRel}: similarity ${fmt(r.similarity)} < tolerance ${fmt(tol)} ` +
167
+ `(${r.diffPixels} of ${r.comparedPixels} pixels differ)` +
168
+ `${diff ? `; diff image: ${diff}` : ''}${unsettled}`;
169
+ return { verdict: record(r.pass ? 'passed' : 'failed', message, { similarity: r.similarity }), diff };
170
+ }
171
+
172
+ module.exports = { decideReferenceScreenshot, toleranceOf, masksOf, parseMaskSpec };
@@ -0,0 +1,92 @@
1
+ 'use strict';
2
+
3
+ // The deterministic comparator behind `screenshot_match` (#281): one PNG
4
+ // against its reference, pixel for pixel, with pixelmatch. Pure apart from the
5
+ // file reads and the one diff-image write.
6
+ //
7
+ // - Different sizes are never resampled: the result says so and is a failure
8
+ // (a reference captured on another device profile is the wrong reference).
9
+ // - Masks are pixel rects ({x, y, width, height}, already scaled — see
10
+ // ./scale.js) that the comparison ignores: the reference's pixels are copied
11
+ // over the actual's under each one, and masked pixels are not counted.
12
+ // - similarity = 1 - diffPixels / comparedPixels (1 when everything is masked).
13
+
14
+ const fs = require('fs');
15
+ const { PNG } = require('pngjs');
16
+ const pixelmatch = require('pixelmatch');
17
+
18
+ const DEFAULT_TOLERANCE = 0.9;
19
+ // pixelmatch's per-pixel colour threshold (0..1): smaller is more sensitive.
20
+ const DEFAULT_THRESHOLD = 0.1;
21
+
22
+ const read = (file) => PNG.sync.read(fs.readFileSync(file));
23
+
24
+ // Whether a similarity meets the tolerance. A null similarity (nothing was
25
+ // compared) never does.
26
+ function pass(similarity, tolerance = DEFAULT_TOLERANCE) {
27
+ return typeof similarity === 'number' && similarity >= tolerance;
28
+ }
29
+
30
+ // Paint every masked pixel of `actual` with `reference`'s and return how many
31
+ // distinct pixels were masked. Masks are clamped to the image.
32
+ function applyMasks(reference, actual, masks) {
33
+ const { width, height } = reference;
34
+ const masked = new Uint8Array(width * height);
35
+ let count = 0;
36
+ for (const m of masks) {
37
+ const x0 = Math.max(0, Math.floor(m.x));
38
+ const y0 = Math.max(0, Math.floor(m.y));
39
+ const x1 = Math.min(width, Math.floor(m.x + m.width));
40
+ const y1 = Math.min(height, Math.floor(m.y + m.height));
41
+ for (let y = y0; y < y1; y++) {
42
+ for (let x = x0; x < x1; x++) {
43
+ const p = y * width + x;
44
+ if (masked[p]) continue;
45
+ masked[p] = 1;
46
+ count++;
47
+ reference.data.copy(actual.data, p << 2, p << 2, (p << 2) + 4);
48
+ }
49
+ }
50
+ }
51
+ return count;
52
+ }
53
+
54
+ function compareScreenshots({
55
+ referencePath, actualPath, tolerance = DEFAULT_TOLERANCE, masks = [], diffPath = null, threshold = DEFAULT_THRESHOLD,
56
+ }) {
57
+ const reference = read(referencePath);
58
+ const actual = read(actualPath);
59
+ if (reference.width !== actual.width || reference.height !== actual.height) {
60
+ return {
61
+ similarity: 0,
62
+ diffPixels: null,
63
+ comparedPixels: null,
64
+ dimensionsMismatch: {
65
+ reference: { width: reference.width, height: reference.height },
66
+ actual: { width: actual.width, height: actual.height },
67
+ },
68
+ diffPath: null,
69
+ pass: false,
70
+ };
71
+ }
72
+
73
+ const { width, height } = reference;
74
+ const maskedPixels = applyMasks(reference, actual, masks || []);
75
+ const diff = new PNG({ width, height });
76
+ const diffPixels = pixelmatch(reference.data, actual.data, diff.data, width, height, { threshold });
77
+ const comparedPixels = width * height - maskedPixels;
78
+ const similarity = comparedPixels === 0 ? 1 : 1 - diffPixels / comparedPixels;
79
+
80
+ // No mkdir: the diff lands in the actual's directory (./screenshots.js
81
+ // runArtifacts / assertArtifacts), which the capture already created.
82
+ let written = null;
83
+ if (diffPixels > 0 && diffPath) {
84
+ fs.writeFileSync(diffPath, PNG.sync.write(diff));
85
+ written = diffPath;
86
+ }
87
+ return {
88
+ similarity, diffPixels, comparedPixels, dimensionsMismatch: null, diffPath: written, pass: pass(similarity, tolerance),
89
+ };
90
+ }
91
+
92
+ module.exports = { compareScreenshots, pass, DEFAULT_TOLERANCE, DEFAULT_THRESHOLD };
@@ -0,0 +1,95 @@
1
+ 'use strict';
2
+
3
+ // Target resolution for `mauto run`. It began as the real-device E2E
4
+ // harness's resolver; the harness copy was retired in replay R7 (#283), and
5
+ // the harness now runs every scenario through `mauto run`, so this is the one
6
+ // resolver.
7
+ //
8
+ // A scenario target is an on-screen string ("More", "Sample Shop"), never an
9
+ // OS element id: that is a locked invariant of agnostic mode, and the old
10
+ // harness broke it. The string is resolved with the CLI's OWN matcher —
11
+ // `findFirst`/`matches` from src/assertion/evaluator.js, INJECTED by the
12
+ // caller — so a run and `mauto assert` cannot disagree about what a target
13
+ // means. There is deliberately no fallback matcher in this file.
14
+
15
+ // How many perceivable strings a miss lists. Enough to see what screen the
16
+ // device is on; not a full dump.
17
+ const MAX_SEEN = 20;
18
+
19
+ class TargetNotFoundError extends Error {
20
+ // `described` is what was looked for, already rendered by describeTarget.
21
+ constructor(described, seen) {
22
+ const listed = seen.length ? seen.map((s) => JSON.stringify(s)).join(', ') : '<nothing perceivable>';
23
+ super(`no element matches target ${described}; on screen: ${listed}`);
24
+ this.name = 'TargetNotFoundError';
25
+ this.target = described;
26
+ this.seen = seen;
27
+ }
28
+ }
29
+
30
+ // The distinct non-blank text / accessibility-label strings on screen, in
31
+ // list order, capped at MAX_SEEN.
32
+ function perceivable(elements) {
33
+ const seen = [];
34
+ for (const e of elements) {
35
+ for (const s of [e && e.text, e && e.accessibility_label]) {
36
+ if (typeof s !== 'string' || s.trim() === '' || seen.includes(s)) continue;
37
+ seen.push(s);
38
+ if (seen.length === MAX_SEEN) return seen;
39
+ }
40
+ }
41
+ return seen;
42
+ }
43
+
44
+ function centerOf(element) {
45
+ if (Array.isArray(element.center)) return element.center;
46
+ const [x1, y1, x2, y2] = element.bounds;
47
+ return [Math.round((x1 + x2) / 2), Math.round((y1 + y2) / 2)];
48
+ }
49
+
50
+ // How a miss names what it looked for: the target string, the pattern, or both.
51
+ function describeTarget(target, pattern) {
52
+ const parts = [];
53
+ if (typeof target === 'string' && target.trim() !== '') parts.push(JSON.stringify(target));
54
+ if (typeof pattern === 'string' && pattern !== '') parts.push(`pattern /${pattern}/`);
55
+ return parts.join(' ');
56
+ }
57
+
58
+ /**
59
+ * @param {object[]} elements the `data` of `mauto elements`
60
+ * @param {string} target on-screen string from the scenario (may be absent when a pattern is given)
61
+ * @param {{matches: Function, textOf?: Function}} matcher the CLI's evaluator
62
+ * @param {{pattern?: string}} [options] `pattern`: a regex the element's text must match, for a
63
+ * label that cannot be a static string; with a target, the target narrows first and the pattern filters
64
+ * @returns {{element: object, center: number[], matches: object[]}}
65
+ */
66
+ function resolveTarget(elements, target, { matches, textOf }, { pattern } = {}) {
67
+ const hasTarget = typeof target === 'string' && target.trim() !== '';
68
+ const hasPattern = typeof pattern === 'string' && pattern !== '';
69
+ // The CLI matcher treats an empty target as "matches everything", which is
70
+ // right for an assertion scope and wrong for a tap.
71
+ if (!hasTarget && !hasPattern) {
72
+ throw new Error('step has no target to resolve');
73
+ }
74
+ const list = Array.isArray(elements) ? elements : [];
75
+ // One pipeline: the target narrows, then the pattern filters; the first
76
+ // survivor is the element and every survivor a candidate.
77
+ let candidates = hasTarget ? list.filter((e) => matches(e, target)) : list;
78
+ if (hasPattern) {
79
+ const re = new RegExp(pattern);
80
+ candidates = candidates.filter((e) => re.test(textOf(e)));
81
+ }
82
+ const element = candidates[0];
83
+ if (!element) {
84
+ throw new TargetNotFoundError(describeTarget(target, pattern), perceivable(list));
85
+ }
86
+ return {
87
+ element,
88
+ center: centerOf(element),
89
+ // Every candidate, so a caller can warn when the first-match rule had a
90
+ // choice to make (a header and a nav item sharing a label, say).
91
+ matches: candidates,
92
+ };
93
+ }
94
+
95
+ module.exports = { resolveTarget, describeTarget, TargetNotFoundError, MAX_SEEN };
@@ -0,0 +1,14 @@
1
+ 'use strict';
2
+
3
+ const pad = (n) => String(n).padStart(2, '0');
4
+
5
+ // `run_YYYYMMDD_HHMMSS`, the format the execute guide and `result` verbs use.
6
+ // UTC so two CI machines agree on what a given instant is called.
7
+ function makeRunId(date) {
8
+ return (
9
+ `run_${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1)}${pad(date.getUTCDate())}` +
10
+ `_${pad(date.getUTCHours())}${pad(date.getUTCMinutes())}${pad(date.getUTCSeconds())}`
11
+ );
12
+ }
13
+
14
+ module.exports = { makeRunId };
@@ -0,0 +1,104 @@
1
+ 'use strict';
2
+
3
+ // The in-process scenario runner behind `mauto run`: an in-process port of
4
+ // the real-device harness's executor, which was retired in replay R7 (#283) —
5
+ // the harness now calls `mauto run` instead. It
6
+ // drives one held-open DeviceBridge and records through one ResultStore. It
7
+ // never spawns a process, never emits an envelope and never finalizes or
8
+ // decides the run's status: the CLI's finalizeRun does that, shared with
9
+ // `mauto result finalize`.
10
+ //
11
+ // Everything with a side effect is injected (bridge, store, clock, trace), which is what lets tests/unit/run drive it on a fake bridge and a
12
+ // fake clock.
13
+
14
+ const { runStep } = require('./tree');
15
+ const { createRunState } = require('./state');
16
+ const { handlerFor } = require('./actions');
17
+ const { preconditionHandlerFor } = require('./actions/preconditions');
18
+ const { runAssertion } = require('./assertions');
19
+ const { NO_TRACE } = require('./trace');
20
+ const { makePollUntil } = require('./poll');
21
+
22
+ // Best-effort: a store that cannot take this write must not replace the
23
+ // error that is about to propagate.
24
+ function recordAbort(store, step, err) {
25
+ if (!step) return;
26
+ try {
27
+ store.addStep({ step_id: step.id, status: 'error', error_message: `mauto run aborted: ${err && err.message}` });
28
+ } catch {
29
+ // The original error is the one worth reporting.
30
+ }
31
+ }
32
+
33
+ async function runScenario({
34
+ scenario, bridge, store, evaluator, catalog, projectRoot, runId, clock,
35
+ trace = NO_TRACE, settings, updateReferences = false,
36
+ }) {
37
+ const failures = [];
38
+ // `variables` is the run's captured values, which the assertions' evaluator
39
+ // reads (value_matches_variable); `settings` the run's timings and limits.
40
+ const variables = {};
41
+ // `pollUntil` is how every waiting handler looks at the screen.
42
+ const pollUntil = makePollUntil(settings, clock);
43
+ const assertions = Array.isArray(scenario.assertions) ? scenario.assertions : [];
44
+ // What the run remembers of the steps already done (statuses, snapshots).
45
+ const state = createRunState(assertions);
46
+ const ctx = {
47
+ scenario, bridge, store, evaluator, catalog, projectRoot, runId, clock, trace, failures, settings, variables, pollUntil, state,
48
+ // `mauto run --update-references` (#281): every screenshot_match records
49
+ // its capture as the baseline instead of comparing against one.
50
+ updateReferences,
51
+ };
52
+ // The assertions that follow a step, once it (and its sub_steps) is done.
53
+ const afterStep = async (stepId) => {
54
+ for (const assertion of assertions.filter((a) => a.after_step === stepId)) {
55
+ await runAssertion(assertion, ctx, state.snapshotOf(stepId));
56
+ }
57
+ };
58
+ // The first step that failed, if any.
59
+ let failedStep = null;
60
+
61
+ // The step being run when an unexpected error (a store write, a bug)
62
+ // escapes: it is recorded as `error` before the error propagates, so the
63
+ // result says the run aborted and where.
64
+ let current = null;
65
+ try {
66
+ trace.start();
67
+ // Preconditions first, each a synthetic step `precondition_<n>` (1-based
68
+ // position in device_actions), through the same runStep (src/run/tree.js).
69
+ const deviceActions = scenario.preconditions && scenario.preconditions.device_actions;
70
+ const setup = (Array.isArray(deviceActions) ? deviceActions : []).map((a, i) => {
71
+ const step = { ...a, id: `precondition_${i + 1}` };
72
+ return { step, perform: preconditionHandlerFor(step.action) };
73
+ });
74
+ const queue = [...setup, ...(scenario.steps || []).map((step) => ({ step, perform: handlerFor(step.action) }))];
75
+ for (const { step, perform } of queue) {
76
+ current = step;
77
+ const { outcome, record } = await runStep(step, perform, ctx, afterStep);
78
+ // A step only an agent can do is recorded, not failed; whatever follows
79
+ // would run on a state nobody established, so the run ends here and
80
+ // finalizes incomplete.
81
+ if (outcome.kind === 'needs_agent') break;
82
+ if (outcome.kind === 'failed') {
83
+ failures.push(`step ${step.id} (${step.action}): ${record.error_message}`);
84
+ failedStep = step.id;
85
+ // Later steps would run against a screen nobody predicted; their
86
+ // failures would only bury this one.
87
+ break;
88
+ }
89
+ // A skipped step (a false condition, an optional miss) still has its
90
+ // assertions run: they describe the screen the scenario expects either way.
91
+ await afterStep(step.id);
92
+ }
93
+ } catch (err) {
94
+ recordAbort(store, current, err);
95
+ throw err;
96
+ }
97
+
98
+ // No status: what a run's records add up to is defined once, by
99
+ // deriveRunStatus (src/result/outcome.js), applied when finalizeRun
100
+ // finalizes the store.
101
+ return { failures, failedStep };
102
+ }
103
+
104
+ module.exports = { runScenario };
@@ -0,0 +1,52 @@
1
+ 'use strict';
2
+
3
+ // Points vs pixels for reference screenshots (#281). Element bounds and
4
+ // `getScreenSize()` are in the device's coordinate space — pixels on Android,
5
+ // points on iOS — while a screenshot PNG is always pixels (an iOS @3x screen is
6
+ // 390 points but 1170 pixels wide). A mask given in element/screen
7
+ // coordinates has to be scaled before it can cover the right pixels; nothing
8
+ // is ever resampled.
9
+
10
+ const fs = require('fs');
11
+ const { PNG } = require('pngjs');
12
+
13
+ // The PNG pixels per device coordinate unit: ~1 on Android, 2 or 3 on iOS.
14
+ function scaleFactor(pngWidth, screenSize) {
15
+ const screenWidth = screenSize && Number(screenSize.width);
16
+ const factor = Number(pngWidth) / screenWidth;
17
+ if (!Number.isFinite(factor) || factor <= 0 || !(Number(pngWidth) > 0) || !(screenWidth > 0)) {
18
+ throw new Error(
19
+ `cannot derive a scale factor from a ${pngWidth}px-wide screenshot and a screen ` +
20
+ `${screenSize ? `${screenSize.width}` : 'of unknown'} wide`
21
+ );
22
+ }
23
+ return factor;
24
+ }
25
+
26
+ // A rect in device coordinates -> the pixel rect it covers, rounded.
27
+ function pointsToPixels({ x, y, width, height }, factor) {
28
+ return {
29
+ x: Math.round(x * factor),
30
+ y: Math.round(y * factor),
31
+ width: Math.round(width * factor),
32
+ height: Math.round(height * factor),
33
+ };
34
+ }
35
+
36
+ // An element's `bounds` (src/device/element-model.js: [x1, y1, x2, y2]) -> a
37
+ // rect in the same coordinates.
38
+ function boundsToRect(bounds) {
39
+ if (!Array.isArray(bounds) || bounds.length !== 4 || !bounds.every((v) => Number.isFinite(v))) {
40
+ throw new Error(`element bounds must be [x1, y1, x2, y2] numbers (got ${JSON.stringify(bounds)})`);
41
+ }
42
+ const [x1, y1, x2, y2] = bounds;
43
+ return { x: x1, y: y1, width: x2 - x1, height: y2 - y1 };
44
+ }
45
+
46
+ // A PNG file's pixel size.
47
+ function pngSize(file) {
48
+ const png = PNG.sync.read(fs.readFileSync(file));
49
+ return { width: png.width, height: png.height };
50
+ }
51
+
52
+ module.exports = { scaleFactor, pointsToPixels, boundsToRect, pngSize };