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.
- package/README.md +2 -0
- package/package.json +4 -2
- package/src/assertion/evaluator.js +116 -14
- package/src/assertion/fields.js +106 -0
- package/src/assertion/observe.js +17 -0
- package/src/cli.js +180 -174
- package/src/device/action-catalog.js +4 -2
- package/src/device/bridge.js +17 -1
- package/src/device/mobile-mcp-tools.js +1 -0
- package/src/device/resolve-connection.js +1 -1
- package/src/device/semantic-press/index.js +19 -0
- package/src/device/semantic-press/resolver.js +1 -1
- package/src/{device/semantic-press/labels.js → dialog/permission-labels.js} +6 -3
- package/src/guide/content/execute.agnostic.md +74 -21
- package/src/guide/content/execute.aware.md +69 -15
- package/src/guide/content/execute.invariants.md +1 -0
- package/src/guide/content/generate.agnostic.md +3 -3
- package/src/guide/content/generate.aware.md +5 -5
- package/src/guide/emitter.js +2 -0
- package/src/init/host-plan.js +1 -0
- package/src/observe/trace.js +1 -1
- package/src/observe/vocab.js +6 -0
- package/src/output/device-fail.js +41 -0
- package/src/output/envelope.js +3 -3
- package/src/output/run-human.js +37 -0
- package/src/result/capability-catalog.js +48 -0
- package/src/result/executor.js +58 -0
- package/src/result/finalize-against-scenario.js +103 -0
- package/src/result/flags.js +49 -6
- package/src/result/junit.js +39 -16
- package/src/result/outcome.js +24 -2
- package/src/result/pending-hint.js +67 -0
- package/src/result/scenario-check.js +58 -0
- package/src/result/status-guard.js +46 -0
- package/src/result/store.js +159 -16
- package/src/run/actions/capture.js +21 -0
- package/src/run/actions/gestures.js +89 -0
- package/src/run/actions/index.js +48 -0
- package/src/run/actions/launch.js +30 -0
- package/src/run/actions/preconditions.js +44 -0
- package/src/run/actions/scroll.js +22 -0
- package/src/run/actions/semantic.js +16 -0
- package/src/run/actions/wait.js +66 -0
- package/src/run/assert-reference.js +118 -0
- package/src/run/assertions.js +102 -0
- package/src/run/clock.js +10 -0
- package/src/run/condition.js +80 -0
- package/src/run/fatal.js +15 -0
- package/src/run/handle.js +151 -0
- package/src/run/needs-agent.js +39 -0
- package/src/run/poll.js +38 -0
- package/src/run/prepare.js +107 -0
- package/src/run/reference-assertion.js +172 -0
- package/src/run/reference-screenshot.js +92 -0
- package/src/run/resolve.js +95 -0
- package/src/run/run-id.js +14 -0
- package/src/run/runner.js +104 -0
- package/src/run/scale.js +52 -0
- package/src/run/screenshots.js +163 -0
- package/src/run/settings.js +35 -0
- package/src/run/state.js +22 -0
- package/src/run/step.js +138 -0
- package/src/run/summary.js +73 -0
- package/src/run/trace.js +30 -0
- package/src/run/tree.js +96 -0
- package/src/run/variables.js +56 -0
- package/src/scenario/load.js +78 -0
- package/src/schemas/config_schema.json +29 -0
- package/src/schemas/result_schema.json +45 -3
- package/src/schemas/scenario_schema.json +27 -0
- package/src/util/as-array.js +8 -0
- package/src/util/parse-positive-int.js +15 -0
- 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 };
|
package/src/result/store.js
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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:
|
|
400
|
-
//
|
|
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
|
-
|
|
429
|
-
|
|
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 = {
|
|
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 };
|