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,58 @@
1
+ 'use strict';
2
+
3
+ // Whether what a run recorded belongs to the scenario it claims (#275).
4
+ // Shared by `result finalize --scenario`.
5
+
6
+ const { flattenSteps } = require('../scenario/steps');
7
+
8
+ const unique = (values) => [...new Set(values)];
9
+
10
+ // Every id the recorded run names that the scenario does not, as readable
11
+ // problem strings; empty when the result is consistent with the scenario. A
12
+ // recorded scenario_id of null (a run recorded without --scenario-id) is not
13
+ // compared. Steps are matched against the whole step tree, sub_steps included.
14
+ function crossCheck(recorded, scenario) {
15
+ const problems = [];
16
+ if (recorded.scenario_id != null && recorded.scenario_id !== scenario.scenario_id) {
17
+ problems.push(`the run recorded scenario_id "${recorded.scenario_id}" but the scenario is "${scenario.scenario_id}"`);
18
+ }
19
+ const stepIds = new Set(flattenSteps(scenario).map(({ step }) => step.id));
20
+ // `mauto run` records each precondition device_action as `precondition_<n>`
21
+ // (1-based position in preconditions.device_actions).
22
+ const setup = scenario.preconditions && scenario.preconditions.device_actions;
23
+ if (Array.isArray(setup)) setup.forEach((_, i) => stepIds.add(`precondition_${i + 1}`));
24
+ for (const id of unique(recorded.steps.map((s) => s.step_id))) {
25
+ if (!stepIds.has(id)) problems.push(`step "${id}" is not in the scenario`);
26
+ }
27
+ const assertionIds = new Set((scenario.assertions || []).map((a) => a.id));
28
+ for (const id of unique(recorded.assertions.map((a) => a.assertion_id))) {
29
+ if (!assertionIds.has(id)) problems.push(`assertion "${id}" is not in the scenario`);
30
+ }
31
+ return problems;
32
+ }
33
+
34
+ // Why a recorded run cannot be finalized against a loaded scenario
35
+ // (`{scenario, sha256}`, from loadScenario), as `{message, hint, data}`, or
36
+ // null when it can. A scenario whose hash differs from the one the run
37
+ // recorded was edited since: refused first, since checking ids against a
38
+ // different file proves nothing. Then every recorded id must be the
39
+ // scenario's (crossCheck).
40
+ function scenarioMismatch(recorded, { scenario, sha256 }) {
41
+ const recordedSha = recorded.executor && recorded.executor.scenario_sha256;
42
+ if (recordedSha && recordedSha !== sha256) {
43
+ return {
44
+ message: 'the scenario changed since the run',
45
+ hint: `The run was recorded against ${recorded.executor.scenario_path} (sha256 ${recordedSha}); finalize with that file, or re-run the scenario.`,
46
+ data: { recorded_sha256: recordedSha, scenario_sha256: sha256 },
47
+ };
48
+ }
49
+ const problems = crossCheck(recorded, scenario);
50
+ if (problems.length === 0) return null;
51
+ return {
52
+ message: `the run does not match the scenario: ${problems.length} problem(s)`,
53
+ hint: 'See data.problems. Pass the scenario this run executed, or fix the recorded ids; nothing was written.',
54
+ data: { problems },
55
+ };
56
+ }
57
+
58
+ module.exports = { crossCheck, scenarioMismatch };
@@ -0,0 +1,46 @@
1
+ 'use strict';
2
+
3
+ const { deriveRunStatus } = require('./outcome');
4
+
5
+ // The rule for `result finalize --status <explicit>` (#275 review, B1): an
6
+ // agent may make a run worse than the status derived from what was recorded,
7
+ // never greener. Severity, least to most: passed < incomplete < failed < error.
8
+ //
9
+ // - An explicit status is allowed when it equals the derived one, or is
10
+ // strictly more severe — with one exception: `incomplete` is a derived-only
11
+ // state (it means "something recorded is pending"), so it is allowed only
12
+ // when the derived status is itself `incomplete`.
13
+ // - A `passed` over a run with nothing recorded (zero steps AND zero
14
+ // assertions) proves nothing, so it is refused — unless the caller loaded
15
+ // the `--scenario` and that scenario declares zero assertions
16
+ // (`scenarioAssertionCount === 0`).
17
+ //
18
+ // Returns null when the status may be written, else `{message, hint}`.
19
+ const SEVERITY = Object.freeze({ passed: 0, incomplete: 1, failed: 2, error: 3 });
20
+
21
+ function checkExplicitStatus({ status, steps = [], assertions = [], scenarioAssertionCount } = {}) {
22
+ if (status === undefined) return null;
23
+ const derived = deriveRunStatus(steps, assertions);
24
+ const empty = steps.length === 0 && assertions.length === 0;
25
+
26
+ if (status === 'passed' && empty && scenarioAssertionCount !== 0) {
27
+ return {
28
+ message: 'cannot finalize --status passed: nothing recorded for this run (no steps and no assertions)',
29
+ hint:
30
+ 'Record the run with `mauto result add-step` / `add-assertion` first, or omit --status. ' +
31
+ 'An empty run may be finalized passed only with --scenario naming a scenario that declares no assertions.',
32
+ };
33
+ }
34
+
35
+ const allowed = status === 'incomplete' ? derived === 'incomplete' : SEVERITY[status] >= SEVERITY[derived];
36
+ if (allowed) return null;
37
+
38
+ return {
39
+ message: `cannot finalize --status ${status}: the recorded steps and assertions derive "${derived}"`,
40
+ hint:
41
+ `An explicit --status may equal the derived status ("${derived}") or make the run worse (failed, error), ` +
42
+ 'never better. Omit --status to use the derived one, or record the missing verdicts first.',
43
+ };
44
+ }
45
+
46
+ module.exports = { checkExplicitStatus, SEVERITY };
@@ -6,7 +6,14 @@ const path = require('path');
6
6
  const { atomicWrite } = require('../util/atomic');
7
7
  const { withLock } = require('../util/lock');
8
8
  const { OBSERVATION_TYPES, stepStatus } = require('./flags');
9
- const { deriveRunStatus, isErroredStep, isFailedStep, isFailingAssertion } = require('./outcome');
9
+ const {
10
+ deriveRunStatus,
11
+ isErroredStep,
12
+ isFailedStep,
13
+ isFailingAssertion,
14
+ isPendingAssertion,
15
+ isPendingStep,
16
+ } = require('./outcome');
10
17
  const { workspaceDir } = require('../workspace/layout');
11
18
 
12
19
  // Incremental result accumulator that persists to
@@ -52,14 +59,55 @@ function stepFailureSuffix(steps) {
52
59
  return `${failed ? `, ${failed} failed` : ''}${errored ? `, ${errored} errored` : ''}`;
53
60
  }
54
61
 
55
- function assertionStatus(pass) {
62
+ // The summary tail counting entries still waiting for an agent (#275); empty
63
+ // when there are none, which keeps the text every earlier run had.
64
+ function pendingSuffix(steps, assertions) {
65
+ const pending = steps.filter(isPendingStep).length + assertions.filter(isPendingAssertion).length;
66
+ return pending ? `, ${pending} pending agent judgment` : '';
67
+ }
68
+
69
+ const ASSERTION_STATUSES = ['passed', 'failed', 'needs_agent'];
70
+
71
+ // The status to record. `status` is the explicit form (#275, B3). The legacy
72
+ // boolean `pass` of callers that predate it is still accepted, so they write
73
+ // byte-identical result files; anything else (including the retired
74
+ // `pass: 'pending'`) is a caller bug and throws rather than guessing.
75
+ function assertionStatus({ status, pass }) {
76
+ if (status !== undefined) {
77
+ if (!ASSERTION_STATUSES.includes(status)) {
78
+ throw new Error(`unknown assertion status "${status}" (expected ${ASSERTION_STATUSES.join(' | ')})`);
79
+ }
80
+ return status;
81
+ }
82
+ if (typeof pass !== 'boolean') {
83
+ throw new Error(`addAssertion needs a status (${ASSERTION_STATUSES.join(' | ')}) or a boolean legacy pass (pass must be a boolean)`);
84
+ }
56
85
  return pass ? 'passed' : 'failed';
57
86
  }
58
87
 
88
+ // The executor a finalize writes (#275, plan decision 4): the first one is
89
+ // kept, so an agent completing a runner's run never rewrites it as its own.
90
+ // The one thing a later finalize may add is the scenario, when the first was
91
+ // written without one; the CLI refuses a scenario that differs from a
92
+ // recorded hash before it gets here.
93
+ function mergeExecutor(existing, incoming) {
94
+ if (!existing) return incoming || null;
95
+ if (incoming && existing.scenario_sha256 == null && incoming.scenario_sha256 != null) {
96
+ return { ...existing, scenario_path: incoming.scenario_path, scenario_sha256: incoming.scenario_sha256 };
97
+ }
98
+ return existing;
99
+ }
100
+
59
101
  class ResultStore {
60
102
  constructor({ runId, scenarioId, projectRoot, metadata } = {}) {
61
- if (!runId) throw new Error('ResultStore requires a runId');
62
103
  if (!projectRoot) throw new Error('ResultStore requires a projectRoot');
104
+ // The one gate for every writer (#295): the id becomes `<runId>.json` and
105
+ // `<runId>.lock` below, and atomicWrite creates parent directories, so an
106
+ // id with a separator would write outside results/. Same rule as the
107
+ // reader, readFinalizedResult, so the two cannot disagree on valid ids.
108
+ // Thrown before anything is read or written; the CLI's toEnvelope maps it
109
+ // to invalid_input (exit 3).
110
+ if (!isResultRunId(runId)) throw new InvalidRunIdError(projectRoot, runId);
63
111
 
64
112
  this.runId = runId;
65
113
  this.scenarioId = scenarioId || null;
@@ -101,6 +149,7 @@ class ResultStore {
101
149
  this._observations = loaded.observations || [];
102
150
  this._capturedVariables = loaded.captured_variables || {};
103
151
  this._crashes = loaded.crashes || [];
152
+ this._executor = loaded.executor || null;
104
153
  if (!this.scenarioId && loaded.scenario_id) this.scenarioId = loaded.scenario_id;
105
154
  }
106
155
 
@@ -180,10 +229,26 @@ class ResultStore {
180
229
  crashes: this._crashes,
181
230
  _in_progress: true,
182
231
  };
232
+ // A re-opened finalized run (an agent deciding its pending assertions)
233
+ // must not lose who produced it.
234
+ if (this._executor) snapshot.executor = this._executor;
183
235
  this._atomicWrite(JSON.stringify(snapshot, null, 2));
184
236
  }
185
237
 
186
- addStep({ step_id, status, attempts = 1, screenshot = null, error_message = null, observations = null } = {}) {
238
+ // What the run has recorded so far, for checking it against a scenario
239
+ // (src/result/scenario-check.js crossCheck). A deep copy: the caller reads it,
240
+ // it never writes through it.
241
+ recorded() {
242
+ return structuredClone({
243
+ scenario_id: this.scenarioId,
244
+ steps: this._steps,
245
+ assertions: this._assertions,
246
+ executor: this._executor,
247
+ });
248
+ }
249
+
250
+ addStep({ step_id, status, attempts = 1, screenshot = null, error_message = null, observations = null, needs_agent = false,
251
+ condition_evaluated, step_duration_ms, sub_steps_executed } = {}) {
187
252
  return withLock(this._lock, () => {
188
253
  this._refreshFromDisk();
189
254
  const normalized = stepStatus(status);
@@ -196,6 +261,13 @@ class ResultStore {
196
261
  retried: retryCount > 0,
197
262
  retry_count: retryCount,
198
263
  observations,
264
+ // Only a step an agent must do carries the flag (see isPendingStep).
265
+ ...(needs_agent === true ? { needs_agent: true } : {}),
266
+ // Control-flow facts (#280): written only by `mauto run`, so a step
267
+ // recorded through the verbs carries none of them.
268
+ ...(condition_evaluated !== undefined ? { condition_evaluated } : {}),
269
+ ...(step_duration_ms !== undefined ? { step_duration_ms } : {}),
270
+ ...(Array.isArray(sub_steps_executed) ? { sub_steps_executed } : {}),
199
271
  };
200
272
  this._steps.push(step);
201
273
 
@@ -239,17 +311,50 @@ class ResultStore {
239
311
  });
240
312
  }
241
313
 
242
- addAssertion({ step_id, assertion_id, type, pass, message, expected = null, actual = null } = {}) {
314
+ // Record an assertion verdict. `status` is passed | failed | needs_agent
315
+ // (#275); the legacy boolean `pass` is still accepted in its place. Provenance is persisted beside it: `type`,
316
+ // `step_id`, `mechanical` (as given by the caller) and `judge`
317
+ // (omitted unless given — a caller that does not say who decided records
318
+ // no claim).
319
+ //
320
+ // With an explicit assertion_id, a verdict REPLACES a `needs_agent` entry of
321
+ // that id in place, keeping its position, and a pending verdict for an id
322
+ // already decided throws AlreadyDecidedError: a run never goes from decided
323
+ // back to undecided. A derived id (none given) always appends, as do two
324
+ // decided verdicts for one id.
325
+ addAssertion({
326
+ step_id, assertion_id, type, status, pass, message, expected = null, actual = null, mechanical, judge,
327
+ reference_screenshot = null, actual_screenshot = null, similarity_score = null,
328
+ } = {}) {
243
329
  return withLock(this._lock, () => {
244
330
  this._refreshFromDisk();
245
331
  const entry = {
246
332
  assertion_id: assertion_id || `${step_id || 'assert'}_${type || 'unknown'}_${this._assertions.length + 1}`,
247
- status: assertionStatus(pass),
333
+ status: assertionStatus({ status, pass }),
248
334
  expected: expected == null ? null : String(expected),
249
335
  actual: actual == null ? null : String(actual),
250
336
  message: message || '',
251
337
  };
252
- this._assertions.push(entry);
338
+ if (typeof type === 'string') entry.type = type;
339
+ if (step_id != null) entry.step_id = String(step_id);
340
+ // Supplied by the caller, which knows whether its verdict came from the
341
+ // CLI's evaluator; the store only records it.
342
+ if (mechanical !== undefined) entry.mechanical = mechanical;
343
+ if (judge != null) entry.judge = judge;
344
+ // A screenshot_match's comparison (#281): written only when supplied, so
345
+ // every other assertion's record is unchanged.
346
+ if (reference_screenshot != null) entry.reference_screenshot = String(reference_screenshot);
347
+ if (actual_screenshot != null) entry.actual_screenshot = String(actual_screenshot);
348
+ if (similarity_score != null) entry.similarity_score = Number(similarity_score);
349
+
350
+ const sameId = (a) => Boolean(assertion_id) && a !== null && typeof a === 'object' && a.assertion_id === assertion_id;
351
+ if (isPendingAssertion(entry)) {
352
+ const decided = this._assertions.find((a) => sameId(a) && !isPendingAssertion(a));
353
+ if (decided) throw new AlreadyDecidedError(assertion_id, decided.status);
354
+ }
355
+ const pendingIndex = this._assertions.findIndex((a) => sameId(a) && isPendingAssertion(a));
356
+ if (pendingIndex === -1) this._assertions.push(entry);
357
+ else this._assertions[pendingIndex] = entry;
253
358
  this._persistInProgress();
254
359
  return entry;
255
360
  });
@@ -332,7 +437,7 @@ class ResultStore {
332
437
  return notes;
333
438
  }
334
439
 
335
- finalize({ status, durationSeconds = 0, summary, metadata, measurements } = {}) {
440
+ finalize({ status, durationSeconds = 0, summary, metadata, measurements, executor } = {}) {
336
441
  return withLock(this._lock, () => {
337
442
  this._refreshFromDisk();
338
443
 
@@ -369,9 +474,15 @@ class ResultStore {
369
474
  summary:
370
475
  summary ||
371
476
  `${resolvedStatus}: ${passed}/${total} assertion(s) passed across ${this._steps.length} step(s)` +
372
- `${stepFailureSuffix(this._steps)}.`,
477
+ `${stepFailureSuffix(this._steps)}${pendingSuffix(this._steps, this._assertions)}.`,
373
478
  };
374
479
 
480
+ // Who produced the result and from what (#275). Absent only when no
481
+ // finalize has ever been told, so a store driven without one writes the
482
+ // file it always wrote.
483
+ this._executor = mergeExecutor(this._executor, executor);
484
+ if (this._executor) result.executor = this._executor;
485
+
375
486
  // Additive and OMITTED when absent: a result file from a run with no
376
487
  // trace must stay shaped exactly as 0.24.0 wrote it, so finalize never
377
488
  // emits an empty measurements object as a placeholder.
@@ -396,8 +507,9 @@ function isInProgress(parsed) {
396
507
  // path segment: a non-empty string with no separator and no NUL. `.` and `..`
397
508
  // pass, harmlessly: the appended `.json` keeps them inside results/. This is
398
509
  // deliberately NOT the result schema's run_id pattern nor observe/paths.js's
399
- // isValidRunId: the writer (add-step / finalize) accepts any id, so a stricter
400
- // reader would refuse runs finalize wrote successfully.
510
+ // isValidRunId: it is the one rule shared by the writers (the ResultStore
511
+ // constructor and the `result` write verbs, #295) and the reader
512
+ // (readFinalizedResult), so an id finalize accepted is always exportable.
401
513
  function isResultRunId(runId) {
402
514
  return (
403
515
  typeof runId === 'string' &&
@@ -407,6 +519,32 @@ function isResultRunId(runId) {
407
519
  );
408
520
  }
409
521
 
522
+ // Typed error for a run id isResultRunId refuses, carrying the envelope's kind
523
+ // and hint (the DeviceResolutionError pattern). Thrown by the ResultStore
524
+ // constructor, returned as data by readFinalizedResult — one wording for both.
525
+ class InvalidRunIdError extends Error {
526
+ constructor(projectRoot, runId) {
527
+ super(`invalid run id "${runId}"`);
528
+ this.name = 'InvalidRunIdError';
529
+ this.kind = 'invalid_input';
530
+ this.hint = `A run id names a file in ${resultsDir(projectRoot)}; it cannot contain a path separator.`;
531
+ }
532
+ }
533
+
534
+ // Typed error for `pending` recorded over an assertion already decided (#275):
535
+ // a decided verdict is never turned back into an undecided one. Carries the
536
+ // envelope's kind and hint, like InvalidRunIdError.
537
+ class AlreadyDecidedError extends Error {
538
+ constructor(assertionId, status) {
539
+ super(`assertion "${assertionId}" is already decided (${status}); it cannot go back to pending`);
540
+ this.name = 'AlreadyDecidedError';
541
+ this.kind = 'invalid_input';
542
+ this.hint =
543
+ `Record a verdict for "${assertionId}" with --pass true|false, or use a different --assertion-id ` +
544
+ 'for a new pending assertion.';
545
+ }
546
+ }
547
+
410
548
  // Read a finalized result file for a report, WITHOUT going through the
411
549
  // ResultStore constructor: that constructor renames a corrupt file aside as a
412
550
  // `.corrupt.<ts>` sidecar, and a reader must never mutate the workspace it
@@ -425,10 +563,8 @@ function isResultRunId(runId) {
425
563
  function readFinalizedResult(projectRoot, runId) {
426
564
  const invalid = (message, hint) => ({ error: { kind: 'invalid_input', message, hint } });
427
565
  if (!isResultRunId(runId)) {
428
- return invalid(
429
- `invalid run id "${runId}"`,
430
- `A run id names a file in ${resultsDir(projectRoot)}; it cannot contain a path separator.`
431
- );
566
+ const { kind, message, hint } = new InvalidRunIdError(projectRoot, runId);
567
+ return { error: { kind, message, hint } };
432
568
  }
433
569
  const file = resultFile(projectRoot, runId);
434
570
  let raw;
@@ -464,4 +600,11 @@ function readFinalizedResult(projectRoot, runId) {
464
600
  return { result: parsed };
465
601
  }
466
602
 
467
- module.exports = { ResultStore, readFinalizedResult, resultFile, isResultRunId };
603
+ module.exports = {
604
+ ResultStore,
605
+ readFinalizedResult,
606
+ resultFile,
607
+ isResultRunId,
608
+ InvalidRunIdError,
609
+ AlreadyDecidedError,
610
+ };
@@ -0,0 +1,21 @@
1
+ 'use strict';
2
+
3
+ const { FatalStepError } = require('../fatal');
4
+ const { resolveStep } = require('./gestures');
5
+
6
+ // capture_value: read the target's displayed text (the evaluator's own
7
+ // textOf, label fallback included) into a scenario variable, so a later
8
+ // value_matches_variable assertion can compare against it.
9
+ async function captureValue(step, ctx) {
10
+ if (!step.capture_to) throw new FatalStepError('capture_value step has no capture_to');
11
+ const declared = (ctx.scenario && ctx.scenario.variables) || {};
12
+ if (!Object.prototype.hasOwnProperty.call(declared, step.capture_to)) {
13
+ throw new FatalStepError(`capture_value step captures to undeclared variable "${step.capture_to}"`);
14
+ }
15
+ const { element } = await resolveStep(step, ctx);
16
+ const value = ctx.evaluator.textOf(element);
17
+ ctx.variables[step.capture_to] = value;
18
+ ctx.store.captureVariable(step.capture_to, value);
19
+ }
20
+
21
+ module.exports = { captureValue };
@@ -0,0 +1,89 @@
1
+ 'use strict';
2
+
3
+ const { FatalStepError } = require('../fatal');
4
+ const { resolveTarget } = require('../resolve');
5
+
6
+ const DIRECTIONS = ['up', 'down', 'left', 'right'];
7
+
8
+ // Resolve a scenario target (or target_pattern) against the current screen
9
+ // with the CLI's own matcher (ctx.evaluator). When the first-match rule had a
10
+ // choice to make, it says so through ctx.observe, which runStep records on
11
+ // the step.
12
+ async function resolveOnScreen(target, { bridge, evaluator, observe }, pattern) {
13
+ // An invalid target_pattern cannot be fixed by retrying.
14
+ if (typeof pattern === 'string' && pattern !== '') {
15
+ try {
16
+ new RegExp(pattern);
17
+ } catch (err) {
18
+ throw new FatalStepError(`invalid target_pattern ${JSON.stringify(pattern)}: ${err.message}`);
19
+ }
20
+ }
21
+ const r = resolveTarget(await bridge.listElements(), target, evaluator, { pattern });
22
+ if (r.matches.length > 1) {
23
+ const what = typeof target === 'string' && target.trim() !== '' ? JSON.stringify(target) : `pattern /${pattern}/`;
24
+ observe(`target ${what} matched ${r.matches.length} elements; used the first`);
25
+ }
26
+ return r;
27
+ }
28
+
29
+ const resolveStep = (step, ctx) => resolveOnScreen(step.target, ctx, step.target_pattern);
30
+
31
+ function requireValue(step) {
32
+ if (step.value === undefined || step.value === null || String(step.value).trim() === '') {
33
+ throw new FatalStepError(`${step.action} step has no value`);
34
+ }
35
+ return String(step.value);
36
+ }
37
+
38
+ function directionOf(step, fallback) {
39
+ const raw = step.value === undefined || step.value === null ? fallback : step.value;
40
+ const direction = typeof raw === 'string' ? raw.toLowerCase() : raw;
41
+ if (!DIRECTIONS.includes(direction)) {
42
+ throw new FatalStepError(`${step.action} step needs a direction (${DIRECTIONS.join(' | ')}), got ${JSON.stringify(step.value)}`);
43
+ }
44
+ return direction;
45
+ }
46
+
47
+ async function tap(step, ctx) {
48
+ const { center } = await resolveStep(step, ctx);
49
+ await ctx.bridge.tap({ x: center[0], y: center[1] });
50
+ }
51
+
52
+ async function type(step, { bridge }) {
53
+ if (step.value === undefined || step.value === null) throw new FatalStepError('type step has no value');
54
+ await bridge.type(String(step.value));
55
+ }
56
+
57
+ // A numeric `value` is the press duration in ms; anything else leaves the
58
+ // engine's default.
59
+ async function longPress(step, ctx) {
60
+ const { center } = await resolveStep(step, ctx);
61
+ const args = { x: center[0], y: center[1] };
62
+ const ms = Number(step.value);
63
+ if (step.value !== undefined && step.value !== null && step.value !== '' && Number.isFinite(ms) && ms > 0) {
64
+ args.duration = ms;
65
+ }
66
+ await ctx.bridge.longPress(args);
67
+ }
68
+
69
+ async function doubleTap(step, ctx) {
70
+ const { center } = await resolveStep(step, ctx);
71
+ await ctx.bridge.doubleTap({ x: center[0], y: center[1] });
72
+ }
73
+
74
+ async function swipe(step, { bridge }) {
75
+ await bridge.swipe({ direction: directionOf(step) });
76
+ }
77
+
78
+ async function pressButton(step, { bridge }) {
79
+ await bridge.pressButton(requireValue(step).toUpperCase());
80
+ }
81
+
82
+ async function openUrl(step, { bridge }) {
83
+ await bridge.openUrl(requireValue(step));
84
+ }
85
+
86
+ module.exports = {
87
+ resolveOnScreen, resolveStep, directionOf, DIRECTIONS,
88
+ tap, type, longPress, doubleTap, swipe, pressButton, openUrl,
89
+ };
@@ -0,0 +1,48 @@
1
+ 'use strict';
2
+
3
+ // Scenario action -> how `mauto run` performs it. Each handler is
4
+ // `async (step, ctx)`: resolves on success, throws on failure (a throw with
5
+ // `fatal: true` is not retried). `ctx.observe(message)` notes something worth
6
+ // knowing about a step that did not fail it; runStep records each note as a
7
+ // state_context observation. Every action the action catalog does not mark
8
+ // `unsupported` has a handler here, and every `unsupported` one maps to the
9
+ // needs-agent handler (the guard is tests/lint/run-action-coverage.test.js).
10
+ // An action with no entry is a loud fatal step error rather than a skip, so a
11
+ // scenario can never pass by exercising less than it claims.
12
+
13
+ const { FatalStepError } = require('../fatal');
14
+ const { launchApp } = require('./launch');
15
+ const { tap, type, longPress, doubleTap, swipe, pressButton, openUrl } = require('./gestures');
16
+ const { scrollToElement } = require('./scroll');
17
+ const { captureValue } = require('./capture');
18
+ const { SEMANTIC_HANDLERS } = require('./semantic');
19
+ const { NEEDS_AGENT_HANDLERS } = require('../needs-agent');
20
+ const { waitForElement, waitForElementGone, waitForLoadingComplete } = require('./wait');
21
+
22
+ const ACTION_HANDLERS = Object.freeze({
23
+ launch_app: launchApp,
24
+ tap,
25
+ type,
26
+ long_press: longPress,
27
+ double_tap: doubleTap,
28
+ swipe,
29
+ press_button: pressButton,
30
+ open_url: openUrl,
31
+ scroll_to_element: scrollToElement,
32
+ wait_for_element: waitForElement,
33
+ wait_for_element_gone: waitForElementGone,
34
+ wait_for_loading_complete: waitForLoadingComplete,
35
+ capture_value: captureValue,
36
+ ...SEMANTIC_HANDLERS,
37
+ ...NEEDS_AGENT_HANDLERS,
38
+ });
39
+
40
+ function unsupported(step) {
41
+ return Promise.reject(new FatalStepError(`action "${step.action}" is not supported by mauto run yet`));
42
+ }
43
+
44
+ function handlerFor(action) {
45
+ return Object.prototype.hasOwnProperty.call(ACTION_HANDLERS, action) ? ACTION_HANDLERS[action] : unsupported;
46
+ }
47
+
48
+ module.exports = { ACTION_HANDLERS, handlerFor };
@@ -0,0 +1,30 @@
1
+ 'use strict';
2
+
3
+ const { FatalStepError } = require('../fatal');
4
+
5
+ // launch_app: cold start by default (#255), resume when the action catalog
6
+ // maps the step's fields to `--resume` (`cold: false`). The catalog is the one
7
+ // place that decision lives, shared with `mauto launch` and the harness.
8
+ async function launchApp(step, { scenario, bridge, catalog, pollUntil }) {
9
+ const appId = scenario.app_package;
10
+ const resume = catalog.stepFlagsFor('launch_app', step).includes('--resume');
11
+ await (resume ? bridge.launchApp(appId) : bridge.restartApp(appId));
12
+
13
+ // The drift gate. A launch that succeeded and a screen with nothing on it
14
+ // is not "the target is missing": it is the engine's element response
15
+ // changing shape under us, or the app failing to render. Reporting it as a
16
+ // missing target blames the app for an engine fault, which is how #199 was
17
+ // first misread.
18
+ const { outcome, timeoutMs } = await pollUntil(step, async () => {
19
+ const elements = await bridge.listElements();
20
+ return { done: Array.isArray(elements) && elements.length > 0 };
21
+ });
22
+ if (!outcome.done) {
23
+ throw new FatalStepError(
24
+ `engine returned zero elements after a successful launch of ${appId} ` +
25
+ `(waited ${timeoutMs}ms): the element response shape drifted or the app did not render`
26
+ );
27
+ }
28
+ }
29
+
30
+ module.exports = { launchApp };
@@ -0,0 +1,44 @@
1
+ 'use strict';
2
+
3
+ const { FatalStepError } = require('../fatal');
4
+ const { NeedsAgentError, NEEDS_AGENT_HANDLERS } = require('../needs-agent');
5
+
6
+ // Precondition `device_actions` (scenario.preconditions): run before step 1,
7
+ // each as a synthetic step `precondition_<n>`. Same handler contract as the
8
+ // step actions.
9
+
10
+ // A run has no pre-flight build to fall back on, so install_app needs an
11
+ // explicit artifact path in `value`; without one the agent installs the app.
12
+ async function installApp(step, { bridge }) {
13
+ if (step.value === undefined || step.value === null || String(step.value).trim() === '') {
14
+ throw new NeedsAgentError(
15
+ 'install_app has no value (a build path) and mauto run has no pre-flight build: install the app by hand, then finish the run'
16
+ );
17
+ }
18
+ await bridge.installApp(String(step.value));
19
+ }
20
+
21
+ async function uninstallApp(step, { bridge, scenario }) {
22
+ await bridge.uninstallApp(step.target_package || scenario.app_package);
23
+ }
24
+
25
+ async function setOrientation(step, { bridge }) {
26
+ if (step.value === undefined || step.value === null || String(step.value).trim() === '') {
27
+ throw new FatalStepError('set_orientation precondition has no value');
28
+ }
29
+ await bridge.setOrientation(String(step.value));
30
+ }
31
+
32
+ const PRECONDITION_HANDLERS = Object.freeze({
33
+ install_app: installApp,
34
+ uninstall_app: uninstallApp,
35
+ set_orientation: setOrientation,
36
+ ...NEEDS_AGENT_HANDLERS,
37
+ });
38
+
39
+ function preconditionHandlerFor(action) {
40
+ if (Object.prototype.hasOwnProperty.call(PRECONDITION_HANDLERS, action)) return PRECONDITION_HANDLERS[action];
41
+ return (step) => Promise.reject(new FatalStepError(`precondition action "${step.action}" is not supported by mauto run yet`));
42
+ }
43
+
44
+ module.exports = { PRECONDITION_HANDLERS, preconditionHandlerFor };
@@ -0,0 +1,22 @@
1
+ 'use strict';
2
+
3
+ const { resolveStep, directionOf } = require('./gestures');
4
+
5
+ // scroll_to_element: look for the target, swiping `step.value` (default up)
6
+ // between looks, up to run.scroll_max_swipes swipes. Only a miss is retried;
7
+ // a device fault propagates at once.
8
+ async function scrollToElement(step, ctx) {
9
+ const direction = directionOf(step, 'up');
10
+ const max = ctx.settings.scrollMaxSwipes;
11
+ for (let swipes = 0; ; swipes++) {
12
+ try {
13
+ return await resolveStep(step, ctx);
14
+ } catch (err) {
15
+ if (err.name !== 'TargetNotFoundError') throw err;
16
+ if (swipes >= max) throw new Error(`${err.message} (after ${max} swipes ${direction})`);
17
+ }
18
+ await ctx.bridge.swipe({ direction });
19
+ }
20
+ }
21
+
22
+ module.exports = { scrollToElement };
@@ -0,0 +1,16 @@
1
+ 'use strict';
2
+
3
+ const { SEMANTIC_ACTIONS, pressSemantic } = require('../../device/semantic-press');
4
+
5
+ // The four agnostic semantic actions, each resolved to per-platform mechanics
6
+ // by the same pressSemantic that backs `mauto press <action>`.
7
+ const SEMANTIC_HANDLERS = Object.fromEntries(
8
+ SEMANTIC_ACTIONS.map((action) => [
9
+ action,
10
+ async (_step, { bridge }) => {
11
+ await pressSemantic(bridge, action);
12
+ },
13
+ ])
14
+ );
15
+
16
+ module.exports = { SEMANTIC_HANDLERS };