opencode-agent-harness 0.0.0-stage → 0.2.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/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +590 -2
- package/bin/agent-harness.js +3059 -0
- package/contrib/global-plugins/README.md +49 -0
- package/contrib/global-plugins/harness-freshness.ts +355 -0
- package/package.json +48 -4
- package/templates/.agents/AGENTS.md +204 -0
- package/templates/.agents/features/INDEX.md +10 -0
- package/templates/.agents/handoffs/README.md +87 -0
- package/templates/.agents/memory/dev-loop.md +59 -0
- package/templates/.agents/memory/domain-map.md +29 -0
- package/templates/.agents/memory/environments.md +35 -0
- package/templates/.agents/memory/flow-map.md +23 -0
- package/templates/.agents/memory/history.md +7 -0
- package/templates/.agents/memory/locations.md +14 -0
- package/templates/.agents/memory/model-routing.md +261 -0
- package/templates/.agents/memory/orchestration.md +183 -0
- package/templates/.agents/memory/owned-files.md +19 -0
- package/templates/.agents/memory/product-principles.md +37 -0
- package/templates/.agents/memory/quality-parameters.md +37 -0
- package/templates/.agents/memory/stack-versions.md +35 -0
- package/templates/.agents/memory/test-design-parameters.md +36 -0
- package/templates/.agents/nightly.json +17 -0
- package/templates/.agents/qa-plans/README.md +70 -0
- package/templates/.agents/qa-runs/README.md +21 -0
- package/templates/.agents/reviews/README.md +47 -0
- package/templates/.agents/rules/00-operating.md +199 -0
- package/templates/.agents/skills/data-engineer/SKILL.md +31 -0
- package/templates/.agents/skills/devops-engineer/SKILL.md +50 -0
- package/templates/.agents/skills/diagnostics-expert/SKILL.md +44 -0
- package/templates/.agents/skills/docs/SKILL.md +140 -0
- package/templates/.agents/skills/features/SKILL.md +187 -0
- package/templates/.agents/skills/frontend-engineer/SKILL.md +81 -0
- package/templates/.agents/skills/handoff/SKILL.md +85 -0
- package/templates/.agents/skills/mobile-engineer/SKILL.md +101 -0
- package/templates/.agents/skills/planner/SKILL.md +112 -0
- package/templates/.agents/skills/product-manager/SKILL.md +115 -0
- package/templates/.agents/skills/qa-architect/SKILL.md +224 -0
- package/templates/.agents/skills/qa-runner/SKILL.md +64 -0
- package/templates/.agents/skills/security-engineer/SKILL.md +53 -0
- package/templates/.agents/skills/system-architect/SKILL.md +42 -0
- package/templates/.agents/skills/ui-designer/SKILL.md +71 -0
- package/templates/.github/workflows/ci.yml +148 -0
- package/templates/.github/workflows/deploy-uat.yml +95 -0
- package/templates/.github/workflows/nightly.yml +83 -0
- package/templates/.github/workflows/uat-health.yml +41 -0
- package/templates/.husky/pre-push +23 -0
- package/templates/.ignore +28 -0
- package/templates/.opencode/agents/data-engineer.md +37 -0
- package/templates/.opencode/agents/devops-engineer.md +37 -0
- package/templates/.opencode/agents/diagnostics-expert.md +37 -0
- package/templates/.opencode/agents/docs.md +37 -0
- package/templates/.opencode/agents/features.md +21 -0
- package/templates/.opencode/agents/frontend-engineer.md +37 -0
- package/templates/.opencode/agents/handoff.md +21 -0
- package/templates/.opencode/agents/mobile-engineer.md +37 -0
- package/templates/.opencode/agents/planner.md +34 -0
- package/templates/.opencode/agents/product-manager.md +29 -0
- package/templates/.opencode/agents/qa-architect.md +27 -0
- package/templates/.opencode/agents/qa-runner.md +17 -0
- package/templates/.opencode/agents/security-engineer.md +37 -0
- package/templates/.opencode/agents/system-architect.md +37 -0
- package/templates/.opencode/agents/ui-designer.md +37 -0
- package/templates/.opencode/commands/board.md +15 -0
- package/templates/.opencode/commands/checkpoint.md +25 -0
- package/templates/.opencode/commands/feature.md +56 -0
- package/templates/.opencode/commands/finish.md +36 -0
- package/templates/.opencode/commands/next.md +49 -0
- package/templates/.opencode/commands/report.md +55 -0
- package/templates/.opencode/commands/resume.md +39 -0
- package/templates/.opencode/commands/switch-model.md +34 -0
- package/templates/.opencode/commands/tidy.md +49 -0
- package/templates/.opencode/plugins/backlog-notify.ts +57 -0
- package/templates/.opencode/plugins/backlog.ts +272 -0
- package/templates/.opencode/plugins/checkpoint.ts +160 -0
- package/templates/.opencode/plugins/context-guard.ts +1164 -0
- package/templates/.opencode/plugins/diff.ts +85 -0
- package/templates/.opencode/plugins/gates.ts +71 -0
- package/templates/.opencode/plugins/job-notify.ts +241 -0
- package/templates/.opencode/plugins/orient.ts +67 -0
- package/templates/.opencode/plugins/session.ts +89 -0
- package/templates/.opencode/plugins/wait.ts +101 -0
- package/templates/.opencode/plugins/where.ts +70 -0
- package/templates/.opencode/skills/bounded-explore/SKILL.md +38 -0
- package/templates/.opencode/skills/dev-loop/SKILL.md +87 -0
- package/templates/.vercelignore +16 -0
- package/templates/AGENTS.md +27 -0
- package/templates/BACKLOG.md +95 -0
- package/templates/docs/ci-cd-pipeline.md +81 -0
- package/templates/docs/gates.md +128 -0
- package/templates/docs/mcp-integrations.md +97 -0
- package/templates/docs/mobile-testing.md +555 -0
- package/templates/docs/nightly-testing.md +106 -0
- package/templates/docs/wsl-optimizations.md +290 -0
- package/templates/opencode.json +188 -0
- package/templates/scripts/agent-report.js +541 -0
- package/templates/scripts/agent-search.sh +117 -0
- package/templates/scripts/backlog.js +1864 -0
- package/templates/scripts/board-service.sh +207 -0
- package/templates/scripts/checkpoint.js +290 -0
- package/templates/scripts/finalize.js +277 -0
- package/templates/scripts/nightly.js +913 -0
- package/templates/scripts/orient.js +514 -0
- package/templates/scripts/qa/board-client.js +260 -0
- package/templates/scripts/qa/board-lib.js +96 -0
- package/templates/scripts/qa/board-sync.js +469 -0
- package/templates/scripts/qa/capacity-lib.js +916 -0
- package/templates/scripts/qa/check-backlog.js +427 -0
- package/templates/scripts/qa/check-capacity.js +85 -0
- package/templates/scripts/qa/check-ci-policy.js +164 -0
- package/templates/scripts/qa/check-concurrency.js +344 -0
- package/templates/scripts/qa/check-dispatch-config.js +296 -0
- package/templates/scripts/qa/check-docs.js +284 -0
- package/templates/scripts/qa/check-integrate.js +98 -0
- package/templates/scripts/qa/check-linger.js +160 -0
- package/templates/scripts/qa/check-prefix-stability.js +183 -0
- package/templates/scripts/qa/check-product.js +177 -0
- package/templates/scripts/qa/check-qa-plan.js +378 -0
- package/templates/scripts/qa/check-qa-scripts.js +85 -0
- package/templates/scripts/qa/check-quality.js +249 -0
- package/templates/scripts/qa/check-test-wiring.js +253 -0
- package/templates/scripts/qa/ci-triage.js +346 -0
- package/templates/scripts/qa/ci-usage-lib.js +185 -0
- package/templates/scripts/qa/ci-wait-lib.js +294 -0
- package/templates/scripts/qa/command-classifier.js +552 -0
- package/templates/scripts/qa/context-guard-core.js +1618 -0
- package/templates/scripts/qa/diff.js +174 -0
- package/templates/scripts/qa/feature-scaffold.js +224 -0
- package/templates/scripts/qa/fixtures/backlog.md +104 -0
- package/templates/scripts/qa/governance.js +174 -0
- package/templates/scripts/qa/hash-file.js +32 -0
- package/templates/scripts/qa/lease-lib.js +263 -0
- package/templates/scripts/qa/merge-backlog.js +324 -0
- package/templates/scripts/qa/mobile-e2e/analyze-timings.js +300 -0
- package/templates/scripts/qa/mobile-e2e/apk-cache.js +420 -0
- package/templates/scripts/qa/mobile-e2e/backend-build-cache.js +203 -0
- package/templates/scripts/qa/mobile-e2e/boot-emulator.sh +432 -0
- package/templates/scripts/qa/mobile-e2e/build-apk.sh +210 -0
- package/templates/scripts/qa/mobile-e2e/check-flows.js +453 -0
- package/templates/scripts/qa/mobile-e2e/config.yaml +18 -0
- package/templates/scripts/qa/mobile-e2e/device-down.sh +88 -0
- package/templates/scripts/qa/mobile-e2e/device-up.sh +258 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-down.sh +72 -0
- package/templates/scripts/qa/mobile-e2e/ios-simulator-up.sh +153 -0
- package/templates/scripts/qa/mobile-e2e/job-events.js +181 -0
- package/templates/scripts/qa/mobile-e2e/prewarm.sh +56 -0
- package/templates/scripts/qa/mobile-e2e/run-detached.sh +222 -0
- package/templates/scripts/qa/mobile-e2e/run-maestro.js +1543 -0
- package/templates/scripts/qa/mobile-e2e/ui-dump.js +327 -0
- package/templates/scripts/qa/models.allowlist.txt +32 -0
- package/templates/scripts/qa/provider-stats.js +878 -0
- package/templates/scripts/qa/run-clean.js +83 -0
- package/templates/scripts/qa/run-gates.js +212 -0
- package/templates/scripts/qa/run-loop.js +220 -0
- package/templates/scripts/qa/session-recon.js +512 -0
- package/templates/scripts/qa/store-lib.js +324 -0
- package/templates/scripts/qa/tool-lib.js +134 -0
- package/templates/scripts/qa/where.js +214 -0
- package/templates/scripts/qa/wslconfig-merge.js +157 -0
- package/templates/scripts/serve.js +1328 -0
- package/templates/scripts/setup-nightly.sh +185 -0
- package/templates/scripts/setup-tmpfs.sh +374 -0
- package/templates/scripts/ship.js +586 -0
- package/templates/scripts/switch-reasoning-model.ps1 +101 -0
- package/templates/scripts/switch-reasoning-model.sh +104 -0
- package/templates/scripts/wait-for.js +342 -0
- package/templates/scripts/wsl-gpu.sh +180 -0
- package/templates/scripts/wsl-tune.sh +261 -0
|
@@ -0,0 +1,1543 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* mobile E2E device-run entrypoint (Maestro) — harness-owned.
|
|
6
|
+
*
|
|
7
|
+
* Encapsulates the operator-run device tier: guards the environment boundary
|
|
8
|
+
* (never mutate UAT/production), optionally resets the dev DB via a
|
|
9
|
+
* project-provided `reset.js` (seed + actor auth, unless `--no-reset`), prints
|
|
10
|
+
* the documented sequence, and hands off to `maestro test`. It never starts
|
|
11
|
+
* servers itself — the operator/agent starts the dev backend + emulator first.
|
|
12
|
+
*
|
|
13
|
+
* This file is harness-owned and overwritten by `agent-harness update`; project
|
|
14
|
+
* specifics live in the sibling `local.json` (appId / defaultActor) and in the
|
|
15
|
+
* project's own `flows/`, `matrix.yaml`, and `reset.js`.
|
|
16
|
+
*
|
|
17
|
+
* Performance layer (all additive; coverage and assertions unchanged):
|
|
18
|
+
* * `--config <file>` (default `config.yaml`) enables
|
|
19
|
+
* `platform.android.disableAnimations: true`, which removes the per-command
|
|
20
|
+
* animation-settle wait that dominates device-run wall time.
|
|
21
|
+
* * `--no-reinstall-driver` is passed to every `maestro test` (the driver
|
|
22
|
+
* APKs only need installing once per device), via `--reinstall-driver` to
|
|
23
|
+
* opt back in.
|
|
24
|
+
* * `--reuse-session` signs in once per actor instead of once per flow. The
|
|
25
|
+
* shared `_shared/session.yaml` subflow reuses an existing session and
|
|
26
|
+
* never `clearState`s, so each actor's one-time first-login walkthrough
|
|
27
|
+
* stays dismissed for the whole run; consecutive same-actor, setup-free
|
|
28
|
+
* journeys are batched into one `maestro test` invocation (fewer JVMs). A
|
|
29
|
+
* journey whose `actor:` changes is its own invocation with
|
|
30
|
+
* `MOBILE_E2E_SWITCH=1` (sign the current actor out, then sign in).
|
|
31
|
+
* * A journey with `firstLogin: true` in `flows/matrix.yaml` is run first and
|
|
32
|
+
* alone: it is the single scenario allowed to `clearState` and assert the
|
|
33
|
+
* fresh onboarding/walkthrough, and ordering it first keeps its app-data
|
|
34
|
+
* wipe from resetting the sessions every other journey reuses.
|
|
35
|
+
* * `--no-seed` runs `reset.js --no-seed` (mint actor auth against the
|
|
36
|
+
* existing dev data) for fast re-verification runs.
|
|
37
|
+
* * `--failed` re-runs only the journeys that failed in the previous run
|
|
38
|
+
* (read from `.serve/mobile-e2e-last-run.json`, written after every run).
|
|
39
|
+
* * A journey may opt into setup batching with `batchSetup: true` in
|
|
40
|
+
* `matrix.yaml`: its additive `setup:` runs before a shared warm invocation
|
|
41
|
+
* instead of forcing a standalone one. Refused for a clearing setup, an
|
|
42
|
+
* oracle, a firstLogin, or an `endsAs` change.
|
|
43
|
+
* * The run report carries per-journey `durationMs` (from Maestro's summary in
|
|
44
|
+
* a batch, else the invocation wall clock) plus the invocation count and
|
|
45
|
+
* total wall time, so the slowest journeys are visible without parsing the
|
|
46
|
+
* Maestro logs. Batched failures match on the extension-free flow key, so a
|
|
47
|
+
* `[Failed] manager-approvals` summary is not mistaken for a pass.
|
|
48
|
+
*
|
|
49
|
+
* Usage:
|
|
50
|
+
* node scripts/qa/mobile-e2e/run-maestro.js --help
|
|
51
|
+
* node scripts/qa/mobile-e2e/run-maestro.js --flows auth-join,discovery-borrow
|
|
52
|
+
*
|
|
53
|
+
* Options:
|
|
54
|
+
* --flows <a,b,...> journey ids (flow basenames) or `all` (required to run)
|
|
55
|
+
* --api-url <url> EXPO_PUBLIC_API_URL for the dev backend (default http://localhost:3000)
|
|
56
|
+
* --app-id <id> app under test (default local.json `appId`, then com.example.app)
|
|
57
|
+
* --platform <p> target platform android (default) or ios
|
|
58
|
+
* --udid <id> iOS Simulator UDID (default MOBILE_E2E_IOS_UDID or a booted sim)
|
|
59
|
+
* --no-reset skip the reset.js step (use the current dev DB state)
|
|
60
|
+
* --no-seed run reset.js --no-seed (mint actor auth only; keep seeded data)
|
|
61
|
+
* --reuse-session sign in once per actor and batch same-actor setup-free flows
|
|
62
|
+
* --failed re-run only the journeys that failed in the last run
|
|
63
|
+
* --config <file> Maestro workspace config (default config.yaml — disables animations)
|
|
64
|
+
* --reinstall-driver force Maestro to reinstall its device driver (default: skip)
|
|
65
|
+
* --max-same-reason <n> stop after n flows fail for the same reason (default 3; 0 disables)
|
|
66
|
+
* --root <dir> repository root (default: the script's repository)
|
|
67
|
+
* -h, --help print this usage and exit 0
|
|
68
|
+
*/
|
|
69
|
+
|
|
70
|
+
const fs = require('fs');
|
|
71
|
+
const path = require('path');
|
|
72
|
+
const os = require('os');
|
|
73
|
+
const { spawnSync, spawn } = require('node:child_process');
|
|
74
|
+
const jobEvents = require('./job-events.js');
|
|
75
|
+
|
|
76
|
+
const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
|
|
77
|
+
const FLOWS_DIR = path.join(__dirname, 'flows');
|
|
78
|
+
const RESET_SCRIPT = path.join(__dirname, 'reset.js');
|
|
79
|
+
const MATRIX_FILE = path.join(FLOWS_DIR, 'matrix.yaml');
|
|
80
|
+
const CONFIG_FILE = path.join(__dirname, 'config.yaml');
|
|
81
|
+
const LOCAL_CONFIG_FILE = path.join(__dirname, 'local.json');
|
|
82
|
+
const REPORT_FILE = path.join(REPO_ROOT, '.serve', 'mobile-e2e-last-run.json');
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Liveness cadence for a running invocation. While `maestro test` runs, the
|
|
86
|
+
* runner appends an `invocation_heartbeat` to the job-events stream every
|
|
87
|
+
* HEARTBEAT_MS, and a one-shot `invocation_stalled` once the child has produced
|
|
88
|
+
* NO output for STALL_MS — so a long-but-healthy batch no longer looks identical
|
|
89
|
+
* to a hang, and a real hang is named automatically. Both env-tunable.
|
|
90
|
+
*/
|
|
91
|
+
const HEARTBEAT_MS = Math.max(1000, Number(process.env.MOBILE_E2E_HEARTBEAT_MS) || 15000);
|
|
92
|
+
const STALL_MS = Math.max(0, Number(process.env.MOBILE_E2E_STALL_MS) || 120000);
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Optional project-owned defaults (`local.json` in this directory, written by
|
|
96
|
+
* the project, never by the harness): `{ "appId": "...", "defaultActor": "..." }`.
|
|
97
|
+
* The harness ships the mechanism; the project names its app and actor. Env
|
|
98
|
+
* vars `MOBILE_E2E_APP_ID` / `MOBILE_E2E_DEFAULT_ACTOR` override the file.
|
|
99
|
+
*/
|
|
100
|
+
function readLocalConfig() {
|
|
101
|
+
try {
|
|
102
|
+
return JSON.parse(fs.readFileSync(LOCAL_CONFIG_FILE, 'utf8'));
|
|
103
|
+
} catch {
|
|
104
|
+
return {};
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
const LOCAL_CONFIG = readLocalConfig();
|
|
108
|
+
const DEFAULT_APP_ID = process.env.MOBILE_E2E_APP_ID || LOCAL_CONFIG.appId || 'com.example.app';
|
|
109
|
+
const DEFAULT_ACTOR = process.env.MOBILE_E2E_DEFAULT_ACTOR || LOCAL_CONFIG.defaultActor || '';
|
|
110
|
+
/**
|
|
111
|
+
* Target platform: env MOBILE_E2E_PLATFORM > local.json `platform` > android.
|
|
112
|
+
* `android` is the historical behavior (byte-identical); `ios` switches the
|
|
113
|
+
* preflight off adb and onto an iOS Simulator UDID passed to `maestro test`.
|
|
114
|
+
*/
|
|
115
|
+
const DEFAULT_PLATFORM =
|
|
116
|
+
String(process.env.MOBILE_E2E_PLATFORM || LOCAL_CONFIG.platform || 'android').toLowerCase() === 'ios'
|
|
117
|
+
? 'ios'
|
|
118
|
+
: 'android';
|
|
119
|
+
const SEED_STATE_FILE = 'mobile-e2e-seed.json';
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Resolve the development DATABASE_URL exactly the way `reset.js` does — process
|
|
123
|
+
* env wins, then `.env`/`.env.local`, then the localhost dev fallback — by
|
|
124
|
+
* importing the project's own `scripts/env-util.js`. The runner and the reset can
|
|
125
|
+
* therefore never disagree, and the runner stops printing the false
|
|
126
|
+
* "DATABASE_URL is not set" warning when the value lives in `.env` (which is the
|
|
127
|
+
* normal local setup and made the old warning fire on every run).
|
|
128
|
+
*/
|
|
129
|
+
function resolveDevDatabaseUrl(root = REPO_ROOT) {
|
|
130
|
+
if (process.env.DATABASE_URL) return process.env.DATABASE_URL;
|
|
131
|
+
try {
|
|
132
|
+
const util = require(path.join(root, 'scripts', 'env-util.js'));
|
|
133
|
+
if (util && typeof util.databaseUrlFor === 'function') {
|
|
134
|
+
return util.databaseUrlFor('development') || '';
|
|
135
|
+
}
|
|
136
|
+
} catch {
|
|
137
|
+
/* project has no env-util: fall through to the bare env value */
|
|
138
|
+
}
|
|
139
|
+
return process.env.DATABASE_URL || '';
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Content-addressed seed fingerprint: the reset script + the project's seed
|
|
144
|
+
* scripts + `env-util.js` + the resolved dev URL. A change to any of these
|
|
145
|
+
* invalidates it and forces a full reseed; an app-code change (which does not
|
|
146
|
+
* touch seed inputs) keeps it stable so a subset re-run can skip the ~90 s seed.
|
|
147
|
+
*/
|
|
148
|
+
function seedFingerprint(root = REPO_ROOT) {
|
|
149
|
+
const crypto = require('crypto');
|
|
150
|
+
const hash = crypto.createHash('sha256');
|
|
151
|
+
const scriptsDir = path.join(root, 'scripts');
|
|
152
|
+
const rels = new Set(['qa/mobile-e2e/reset.js', 'db-seed.js', 'env-util.js']);
|
|
153
|
+
try {
|
|
154
|
+
for (const name of fs.readdirSync(scriptsDir)) {
|
|
155
|
+
if (/^seed[-_.]/.test(name) || name === 'seed.ts' || name === 'seed.js') rels.add(name);
|
|
156
|
+
}
|
|
157
|
+
} catch {
|
|
158
|
+
/* no scripts dir */
|
|
159
|
+
}
|
|
160
|
+
for (const rel of [...rels].sort()) {
|
|
161
|
+
hash.update(rel);
|
|
162
|
+
hash.update('\0');
|
|
163
|
+
try {
|
|
164
|
+
hash.update(fs.readFileSync(path.join(scriptsDir, rel)));
|
|
165
|
+
} catch {
|
|
166
|
+
hash.update('MISSING');
|
|
167
|
+
}
|
|
168
|
+
hash.update('\0');
|
|
169
|
+
}
|
|
170
|
+
hash.update('db=');
|
|
171
|
+
hash.update(resolveDevDatabaseUrl(root));
|
|
172
|
+
return hash.digest('hex');
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* The dev Postgres is one shared database across every worktree, so the seed
|
|
177
|
+
* state lives in the MAIN checkout's `.serve/` (a worktree's own `.serve/` is
|
|
178
|
+
* separate and would miss the seed another tree performed).
|
|
179
|
+
*/
|
|
180
|
+
function seedStatePath() {
|
|
181
|
+
const main = mainWorktreeRoot();
|
|
182
|
+
return path.join(main || REPO_ROOT, '.serve', SEED_STATE_FILE);
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
function readSeedState() {
|
|
186
|
+
try {
|
|
187
|
+
return JSON.parse(fs.readFileSync(seedStatePath(), 'utf8'));
|
|
188
|
+
} catch {
|
|
189
|
+
return null;
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
function writeSeedState(state) {
|
|
194
|
+
try {
|
|
195
|
+
const file = seedStatePath();
|
|
196
|
+
fs.mkdirSync(path.dirname(file), { recursive: true });
|
|
197
|
+
fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
|
|
198
|
+
} catch {
|
|
199
|
+
/* best-effort */
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
|
|
203
|
+
/**
|
|
204
|
+
* Pure decision seam (unit-tested). Auto-skip the full seed ONLY for a subset
|
|
205
|
+
* re-run with an unchanged fingerprint; a full matrix run always reseeds (it
|
|
206
|
+
* lands the known baseline), and an explicit --no-seed / --no-reset /
|
|
207
|
+
* --force-reset always wins.
|
|
208
|
+
*/
|
|
209
|
+
function shouldAutoNoSeed({ explicitNoSeed, noReset, forceReset, subset, stateMatches }) {
|
|
210
|
+
if (explicitNoSeed || noReset || forceReset) return false;
|
|
211
|
+
return Boolean(subset && stateMatches);
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
function usage() {
|
|
215
|
+
return [
|
|
216
|
+
'F-285/F-291 mobile E2E device-run entrypoint (Maestro)',
|
|
217
|
+
'',
|
|
218
|
+
'Usage:',
|
|
219
|
+
' node scripts/qa/mobile-e2e/run-maestro.js --flows <a,b,...|all> [options]',
|
|
220
|
+
' node scripts/qa/mobile-e2e/run-maestro.js --help',
|
|
221
|
+
'',
|
|
222
|
+
'Options:',
|
|
223
|
+
' --flows <a,b,...> journey ids (flow basenames) or `all` (required to run)',
|
|
224
|
+
' --api-url <url> EXPO_PUBLIC_API_URL for the dev backend (default http://localhost:3000)',
|
|
225
|
+
' --app-id <id> app under test (default com.libraryos.app; Expo Go = host.exp.exponent)',
|
|
226
|
+
' --platform <p> target platform: android (default) or ios',
|
|
227
|
+
' --udid <id> iOS Simulator UDID to target (default: MOBILE_E2E_IOS_UDID or a booted sim)',
|
|
228
|
+
' --no-reset skip reset.js (use the current dev DB state)',
|
|
229
|
+
' --no-seed run reset.js --no-seed (mint actor auth only)',
|
|
230
|
+
' --force-reset always run the full seed (disable the automatic subset skip)',
|
|
231
|
+
' --reuse-session reuse the device session; batch same-actor setup-free flows (no clearState)',
|
|
232
|
+
' --failed re-run only the journeys that failed in the last run',
|
|
233
|
+
' --report <file> last-run report for --failed (default: this checkout, then the main checkout)',
|
|
234
|
+
' --config <file> Maestro workspace config (default config.yaml — disables animations)',
|
|
235
|
+
' --reinstall-driver force Maestro to reinstall its device driver (default: skip)',
|
|
236
|
+
' --max-same-reason <n> stop after n flows fail for the same reason (default 3; 0 disables)',
|
|
237
|
+
' --preflight assert adb/maestro/SDK prerequisites and exit (no run, no DB)',
|
|
238
|
+
' --root <dir> repository root (default: the script\'s repository)',
|
|
239
|
+
' -h, --help print this usage and exit 0',
|
|
240
|
+
'',
|
|
241
|
+
'Documented operator sequence (run these once before this script):',
|
|
242
|
+
' 1. node scripts/qa/mobile-e2e/boot-emulator.sh # or serve.js start the emulator',
|
|
243
|
+
' 2. node scripts/serve.js start --cmd "npm run dev" --url http://localhost:3000',
|
|
244
|
+
' 3. npm run mobile-e2e:reset # seed dev DB + mint E2E actors',
|
|
245
|
+
' 4. node scripts/qa/mobile-e2e/run-maestro.js --flows all',
|
|
246
|
+
'',
|
|
247
|
+
'By default this runner performs step 3 itself (reset.js); pass --no-reset to',
|
|
248
|
+
'reuse the current database state.',
|
|
249
|
+
'',
|
|
250
|
+
'For the full matrix, prefer the detached helper (keeps the run observable and',
|
|
251
|
+
'never blocks the tool for half an hour):',
|
|
252
|
+
' scripts/qa/mobile-e2e/run-detached.sh --flows all --reuse-session',
|
|
253
|
+
].join('\n');
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
function parseMaxSameReason(raw, fallback) {
|
|
257
|
+
const parsed = Number.parseInt(String(raw), 10);
|
|
258
|
+
return Number.isNaN(parsed) || parsed < 0 ? fallback : parsed;
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
/** Coerce a `--platform` value to one of `android` / `ios` (default android). */
|
|
262
|
+
function normalizePlatform(raw) {
|
|
263
|
+
return String(raw || '').trim().toLowerCase() === 'ios' ? 'ios' : 'android';
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
function parseArgs(argv) {
|
|
267
|
+
const options = {
|
|
268
|
+
help: false,
|
|
269
|
+
flows: null,
|
|
270
|
+
apiUrl: 'http://localhost:3000',
|
|
271
|
+
appId: DEFAULT_APP_ID,
|
|
272
|
+
platform: DEFAULT_PLATFORM,
|
|
273
|
+
udid: null,
|
|
274
|
+
noReset: false,
|
|
275
|
+
noSeed: false,
|
|
276
|
+
forceReset: false,
|
|
277
|
+
reuseSession: false,
|
|
278
|
+
failed: false,
|
|
279
|
+
config: CONFIG_FILE,
|
|
280
|
+
reinstallDriver: false,
|
|
281
|
+
maxSameReason: 3,
|
|
282
|
+
root: REPO_ROOT,
|
|
283
|
+
report: null,
|
|
284
|
+
preflight: false,
|
|
285
|
+
};
|
|
286
|
+
for (let i = 0; i < argv.length; i += 1) {
|
|
287
|
+
const arg = argv[i];
|
|
288
|
+
if (arg === '--help' || arg === '-h') options.help = true;
|
|
289
|
+
else if (arg === '--flows' && argv[i + 1]) options.flows = argv[++i];
|
|
290
|
+
else if (arg.startsWith('--flows=')) options.flows = arg.slice('--flows='.length);
|
|
291
|
+
else if (arg === '--api-url' && argv[i + 1]) options.apiUrl = argv[++i];
|
|
292
|
+
else if (arg.startsWith('--api-url=')) options.apiUrl = arg.slice('--api-url='.length);
|
|
293
|
+
else if (arg === '--app-id' && argv[i + 1]) options.appId = argv[++i];
|
|
294
|
+
else if (arg.startsWith('--app-id=')) options.appId = arg.slice('--app-id='.length);
|
|
295
|
+
else if (arg === '--platform' && argv[i + 1]) options.platform = normalizePlatform(argv[++i]);
|
|
296
|
+
else if (arg.startsWith('--platform=')) options.platform = normalizePlatform(arg.slice('--platform='.length));
|
|
297
|
+
else if (arg === '--udid' && argv[i + 1]) options.udid = argv[++i];
|
|
298
|
+
else if (arg.startsWith('--udid=')) options.udid = arg.slice('--udid='.length);
|
|
299
|
+
else if (arg === '--no-reset') options.noReset = true;
|
|
300
|
+
else if (arg === '--no-seed') options.noSeed = true;
|
|
301
|
+
else if (arg === '--force-reset') options.forceReset = true;
|
|
302
|
+
else if (arg === '--reuse-session') options.reuseSession = true;
|
|
303
|
+
else if (arg === '--failed') options.failed = true;
|
|
304
|
+
else if (arg === '--report' && argv[i + 1]) options.report = path.resolve(argv[++i]);
|
|
305
|
+
else if (arg.startsWith('--report=')) options.report = path.resolve(arg.slice('--report='.length));
|
|
306
|
+
else if (arg === '--config' && argv[i + 1]) options.config = path.resolve(argv[++i]);
|
|
307
|
+
else if (arg.startsWith('--config=')) options.config = path.resolve(arg.slice('--config='.length));
|
|
308
|
+
else if (arg === '--reinstall-driver') options.reinstallDriver = true;
|
|
309
|
+
else if (arg === '--preflight') options.preflight = true;
|
|
310
|
+
else if (arg === '--no-reinstall-driver') options.reinstallDriver = false;
|
|
311
|
+
else if (arg === '--max-same-reason' && argv[i + 1]) options.maxSameReason = parseMaxSameReason(argv[++i], options.maxSameReason);
|
|
312
|
+
else if (arg.startsWith('--max-same-reason=')) options.maxSameReason = parseMaxSameReason(arg.slice('--max-same-reason='.length), options.maxSameReason);
|
|
313
|
+
else if (arg === '--root' && argv[i + 1]) options.root = path.resolve(argv[++i]);
|
|
314
|
+
else if (arg.startsWith('--root=')) options.root = path.resolve(arg.slice('--root='.length));
|
|
315
|
+
else if (!options.unknown) options.unknown = arg;
|
|
316
|
+
}
|
|
317
|
+
return options;
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
function assertDevDatabase() {
|
|
321
|
+
const dbUrl = resolveDevDatabaseUrl();
|
|
322
|
+
if (!dbUrl) {
|
|
323
|
+
console.warn(' ! DATABASE_URL is not set — the flows need a dedicated DEV database.');
|
|
324
|
+
console.warn(' Set DATABASE_URL to the local dev connection before running.');
|
|
325
|
+
return;
|
|
326
|
+
}
|
|
327
|
+
if (/uat|prod/i.test(dbUrl)) {
|
|
328
|
+
console.error('FAIL — refusing to run against a non-dev DATABASE_URL (contains "uat"/"prod").');
|
|
329
|
+
console.error(' The mobile E2E harness must only mutate the dedicated DEV database.');
|
|
330
|
+
process.exit(2);
|
|
331
|
+
}
|
|
332
|
+
}
|
|
333
|
+
|
|
334
|
+
function resolveFlowFiles(selection) {
|
|
335
|
+
if (!selection) return null;
|
|
336
|
+
if (selection.trim() === 'all') {
|
|
337
|
+
// Sort so the run order (and therefore warm-session batching) is
|
|
338
|
+
// deterministic rather than dependent on filesystem readdir order.
|
|
339
|
+
return fs
|
|
340
|
+
.readdirSync(FLOWS_DIR)
|
|
341
|
+
.filter((name) => name.endsWith('.yaml') && name !== 'matrix.yaml')
|
|
342
|
+
.sort()
|
|
343
|
+
.map((name) => path.join(FLOWS_DIR, name));
|
|
344
|
+
}
|
|
345
|
+
return selection
|
|
346
|
+
.split(',')
|
|
347
|
+
.map((id) => id.trim())
|
|
348
|
+
.filter(Boolean)
|
|
349
|
+
.map((id) => path.join(FLOWS_DIR, id.endsWith('.yaml') ? id : `${id}.yaml`));
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* Bounded, dependency-free parser for `flows/matrix.yaml`. Returns a Map of
|
|
354
|
+
* flow basename -> `{ id, actor, setup, oracle }`. A missing/blank manifest
|
|
355
|
+
* yields an empty map (the runner still works).
|
|
356
|
+
*/
|
|
357
|
+
function parseJourneySteps(matrixPath) {
|
|
358
|
+
const map = new Map();
|
|
359
|
+
let content;
|
|
360
|
+
try {
|
|
361
|
+
content = fs.readFileSync(matrixPath, 'utf8');
|
|
362
|
+
} catch {
|
|
363
|
+
return map;
|
|
364
|
+
}
|
|
365
|
+
let current = null;
|
|
366
|
+
content.split(/\r?\n/).forEach((line) => {
|
|
367
|
+
const trimmed = line.trim();
|
|
368
|
+
if (trimmed === '' || trimmed.startsWith('#')) return;
|
|
369
|
+
if (trimmed === 'journeys:') return;
|
|
370
|
+
const idMatch = trimmed.match(/^-\s+id:\s*(.+)$/);
|
|
371
|
+
if (idMatch) {
|
|
372
|
+
current = {
|
|
373
|
+
id: idMatch[1].trim(),
|
|
374
|
+
actor: null,
|
|
375
|
+
endsAs: null,
|
|
376
|
+
setup: null,
|
|
377
|
+
oracle: null,
|
|
378
|
+
firstLogin: false,
|
|
379
|
+
batchSetup: false,
|
|
380
|
+
};
|
|
381
|
+
return;
|
|
382
|
+
}
|
|
383
|
+
const kvMatch = trimmed.match(/^([A-Za-z]+):\s*(.*)$/);
|
|
384
|
+
if (!kvMatch || !current) return;
|
|
385
|
+
const [, key, rawValue] = kvMatch;
|
|
386
|
+
if (key === 'flow') {
|
|
387
|
+
current.flow = rawValue.trim();
|
|
388
|
+
if (current.flow) map.set(current.flow, current);
|
|
389
|
+
} else if (key === 'actor') {
|
|
390
|
+
current.actor = rawValue.trim().replace(/^["']|["']$/g, '');
|
|
391
|
+
} else if (key === 'endsAs') {
|
|
392
|
+
current.endsAs = rawValue.trim().replace(/^["']|["']$/g, '');
|
|
393
|
+
} else if (key === 'setup') {
|
|
394
|
+
current.setup = rawValue.trim();
|
|
395
|
+
} else if (key === 'oracle') {
|
|
396
|
+
current.oracle = rawValue.trim();
|
|
397
|
+
} else if (key === 'firstLogin') {
|
|
398
|
+
current.firstLogin = rawValue.trim() === 'true';
|
|
399
|
+
} else if (key === 'batchSetup') {
|
|
400
|
+
current.batchSetup = rawValue.trim() === 'true';
|
|
401
|
+
}
|
|
402
|
+
});
|
|
403
|
+
return map;
|
|
404
|
+
}
|
|
405
|
+
|
|
406
|
+
/** Split a declaration into commands: the manifest convention joins them with ` + `. */
|
|
407
|
+
function commandSegments(declaration) {
|
|
408
|
+
return String(declaration)
|
|
409
|
+
.split(/\s+\+\s+/)
|
|
410
|
+
.map((segment) => segment.trim())
|
|
411
|
+
.filter(Boolean);
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
/**
|
|
415
|
+
* A parametric command carries an unresolved `<placeholder>` (an id minted at
|
|
416
|
+
* device-run time) and cannot be auto-invoked — it is printed for the operator.
|
|
417
|
+
*/
|
|
418
|
+
function isParametricCommand(command) {
|
|
419
|
+
return /<[A-Za-z_][A-Za-z0-9_]*>/.test(command);
|
|
420
|
+
}
|
|
421
|
+
|
|
422
|
+
/** Resolve the declared setup/oracle steps for the selected flow files, in order. */
|
|
423
|
+
function resolveDeclaredSteps(flowFiles, stepsByFlow) {
|
|
424
|
+
const setups = [];
|
|
425
|
+
const oracles = [];
|
|
426
|
+
flowFiles.forEach((file) => {
|
|
427
|
+
const journey = stepsByFlow.get(path.basename(file));
|
|
428
|
+
if (!journey) return;
|
|
429
|
+
commandSegments(journey.setup || '').forEach((command) => setups.push({ journey: journey.id, command }));
|
|
430
|
+
commandSegments(journey.oracle || '').forEach((command) => oracles.push({ journey: journey.id, command }));
|
|
431
|
+
});
|
|
432
|
+
return { setups, oracles };
|
|
433
|
+
}
|
|
434
|
+
|
|
435
|
+
function printDeclaredSteps(declared) {
|
|
436
|
+
if (declared.setups.length === 0 && declared.oracles.length === 0) return;
|
|
437
|
+
console.log('Declared journey setup/oracle steps:');
|
|
438
|
+
declared.setups.forEach((step) => console.log(` setup [${step.journey}]: ${step.command}`));
|
|
439
|
+
declared.oracles.forEach((step) => console.log(` oracle [${step.journey}]: ${step.command}`));
|
|
440
|
+
console.log('');
|
|
441
|
+
}
|
|
442
|
+
|
|
443
|
+
/** Directories the device tooling lives in but which a headless (systemd timer,
|
|
444
|
+
* CI) PATH usually omits: the resolved adb's dir, the Maestro bin dir, and the
|
|
445
|
+
* SDK platform-tools/emulator. Prepended to the step environment so a journey's
|
|
446
|
+
* own `adb …` setup/teardown resolves. */
|
|
447
|
+
function toolPathDirs() {
|
|
448
|
+
const dirs = [];
|
|
449
|
+
const adb = resolveAdb();
|
|
450
|
+
if (adb && adb !== 'adb' && adb !== 'adb.exe') dirs.push(path.dirname(adb));
|
|
451
|
+
const maestro = resolveMaestro();
|
|
452
|
+
if (maestro && maestro !== 'maestro' && maestro !== 'maestro.bat') dirs.push(path.dirname(maestro));
|
|
453
|
+
for (const sdk of [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT]) {
|
|
454
|
+
if (sdk) dirs.push(path.join(sdk, 'platform-tools'), path.join(sdk, 'emulator'), path.join(sdk, 'cmdline-tools', 'latest', 'bin'));
|
|
455
|
+
}
|
|
456
|
+
return [...new Set(dirs.filter((dir) => dir && fs.existsSync(dir)))];
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
/** The environment declared steps run under: the tool dirs prepended to PATH. */
|
|
460
|
+
function toolEnv() {
|
|
461
|
+
const dirs = toolPathDirs();
|
|
462
|
+
const PATH = [...dirs, process.env.PATH || ''].filter(Boolean).join(path.delimiter);
|
|
463
|
+
return { ...process.env, PATH };
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
/**
|
|
467
|
+
* Invoke declared `setup:` (pre-run) or `oracle:` (post-run) commands. A runnable
|
|
468
|
+
* step that exits non-zero aborts the run (fail loud), while a parametric step
|
|
469
|
+
* (unresolved `<id>`) is printed for the operator.
|
|
470
|
+
*
|
|
471
|
+
* The step runs under `toolEnv()`: a journey's `adb …` step is shell-resolved, and
|
|
472
|
+
* a headless PATH omits platform-tools — the 2026-10-16 `device-e2e code 127`
|
|
473
|
+
* (`/bin/sh: 1: adb: not found`, after 23 minutes of a passing run). The harness
|
|
474
|
+
* resolves the SDK itself, so it must hand that resolution to the step.
|
|
475
|
+
*/
|
|
476
|
+
function runDeclaredSteps(steps, phase) {
|
|
477
|
+
steps.forEach((step) => {
|
|
478
|
+
if (isParametricCommand(step.command)) {
|
|
479
|
+
console.log(` (manual ${phase}) [${step.journey}]: ${step.command}`);
|
|
480
|
+
return;
|
|
481
|
+
}
|
|
482
|
+
console.log(`Running ${phase} [${step.journey}]: ${step.command}`);
|
|
483
|
+
const result = spawnSync(step.command, { stdio: 'inherit', shell: true, env: toolEnv() });
|
|
484
|
+
if (result.status !== 0) {
|
|
485
|
+
console.error(`FAIL — ${phase} step for journey "${step.journey}" exited ${result.status}.`);
|
|
486
|
+
console.error(` ${step.command}`);
|
|
487
|
+
process.exit(result.status === null ? 1 : result.status);
|
|
488
|
+
}
|
|
489
|
+
});
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
/**
|
|
493
|
+
* Resolve the Maestro CLI: an explicit `MOBILE_E2E_MAESTRO` override, then the
|
|
494
|
+
* conventional per-user install (`~/.maestro/bin`), then PATH. A headless
|
|
495
|
+
* invocation (the nightly systemd timer, CI) has a minimal PATH that excludes
|
|
496
|
+
* `~/.maestro/bin`, so PATH alone is not enough — mirroring `resolveAdb()`
|
|
497
|
+
* below, which resolves the SDK from a fixed location for the same reason.
|
|
498
|
+
* Returns the runnable path, or null when Maestro is genuinely absent.
|
|
499
|
+
*/
|
|
500
|
+
function resolveMaestro() {
|
|
501
|
+
const override = process.env.MOBILE_E2E_MAESTRO;
|
|
502
|
+
if (override && fs.existsSync(override)) return override;
|
|
503
|
+
const exe = process.platform === 'win32' ? 'maestro.bat' : 'maestro';
|
|
504
|
+
const installed = path.join(os.homedir(), '.maestro', 'bin', exe);
|
|
505
|
+
if (fs.existsSync(installed)) return installed;
|
|
506
|
+
const probe = process.platform === 'win32' ? 'where' : 'which';
|
|
507
|
+
const result = spawnSync(probe, ['maestro'], { stdio: 'ignore', shell: false });
|
|
508
|
+
return result.status === 0 ? 'maestro' : null;
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
/** Resolve the project's adb: `ANDROID_HOME`/`ANDROID_SDK_ROOT`, else PATH. */
|
|
512
|
+
function resolveAdb() {
|
|
513
|
+
const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT;
|
|
514
|
+
const exe = process.platform === 'win32' ? 'adb.exe' : 'adb';
|
|
515
|
+
if (sdk) {
|
|
516
|
+
const candidate = path.join(sdk, 'platform-tools', exe);
|
|
517
|
+
if (fs.existsSync(candidate)) return candidate;
|
|
518
|
+
}
|
|
519
|
+
return exe;
|
|
520
|
+
}
|
|
521
|
+
|
|
522
|
+
/**
|
|
523
|
+
* Bounded adb readiness preflight. A wedged/absent adb server makes `adb`
|
|
524
|
+
* hang forever (the reason a device run looks frozen before it starts), so this
|
|
525
|
+
* probes with a hard timeout and fails fast with the exact recovery step rather
|
|
526
|
+
* than blocking. `boot-emulator.sh` owns starting the server; this only checks.
|
|
527
|
+
*/
|
|
528
|
+
function preflightAdb() {
|
|
529
|
+
const adb = resolveAdb();
|
|
530
|
+
const probe = spawnSync(adb, ['devices'], { encoding: 'utf8', timeout: 10000 });
|
|
531
|
+
const output = `${probe.stdout || ''}\n${probe.stderr || ''}`;
|
|
532
|
+
const devices = (output.match(/^\S+\s+device\b/gm) || []).length;
|
|
533
|
+
if (!probe.error && probe.status === 0 && devices > 0) {
|
|
534
|
+
console.log(`adb: ${devices} device(s) online`);
|
|
535
|
+
return;
|
|
536
|
+
}
|
|
537
|
+
console.error('FAIL — adb has no ready device (probed with a 10s timeout, so this never hangs).');
|
|
538
|
+
console.error(' Bring up the device tier first:');
|
|
539
|
+
console.error(' node scripts/qa/mobile-e2e/boot-emulator.sh');
|
|
540
|
+
console.error(' If the adb server itself is wedged, boot-emulator.sh restarts it detached;');
|
|
541
|
+
console.error(' the equivalent is:');
|
|
542
|
+
console.error(` node scripts/serve.js start --cmd "${adb} -a nodaemon server" --name adb-server --port 5037 --timeout 30000`);
|
|
543
|
+
process.exit(1);
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
/**
|
|
547
|
+
* `--preflight`: assert the device tier's EXTERNAL prerequisites and exit without
|
|
548
|
+
* touching the app, the DB or the emulator. It runs before `device-up` inside the
|
|
549
|
+
* nightly so a missing tool names itself instead of burning the full run and
|
|
550
|
+
* failing with a bare exit code (2026-10-16: `device-e2e code 127` after 23 min,
|
|
551
|
+
* the real cause a journey `adb …` step with platform-tools off the headless
|
|
552
|
+
* PATH). Returns an exit code: 0 when every FATAL check passes, 1 otherwise.
|
|
553
|
+
* Advisories (a non-WSL box, no booted device yet) are printed but never fatal.
|
|
554
|
+
*/
|
|
555
|
+
function runPreflight(options) {
|
|
556
|
+
const checks = [];
|
|
557
|
+
const add = (name, ok, { detail = '', hint = '', fatal = true } = {}) => {
|
|
558
|
+
checks.push({ name, ok, detail, hint, fatal });
|
|
559
|
+
};
|
|
560
|
+
|
|
561
|
+
const adb = resolveAdb();
|
|
562
|
+
const adbProbe = adb ? spawnSync(adb, ['devices'], { encoding: 'utf8', timeout: 10000, env: toolEnv() }) : { status: 1, error: new Error('adb not resolved') };
|
|
563
|
+
const adbRuns = !adbProbe.error && adbProbe.status === 0;
|
|
564
|
+
add('adb', adbRuns, {
|
|
565
|
+
detail: adbRuns ? `${adb} runs` : `${adb || 'adb'} is not runnable${adbProbe.error ? ` (${adbProbe.error.code || adbProbe.error.message})` : ''}`,
|
|
566
|
+
hint: 'Install Android platform-tools and set ANDROID_HOME/ANDROID_SDK_ROOT (or add platform-tools to PATH).',
|
|
567
|
+
});
|
|
568
|
+
|
|
569
|
+
const maestro = resolveMaestro();
|
|
570
|
+
add('maestro', Boolean(maestro), {
|
|
571
|
+
detail: maestro || 'not resolvable',
|
|
572
|
+
hint: 'curl -Ls "https://get.maestro.mobile.dev" | bash (needs JDK 17+), or set MOBILE_E2E_MAESTRO.',
|
|
573
|
+
});
|
|
574
|
+
|
|
575
|
+
if (options.platform === 'ios') {
|
|
576
|
+
let udid = '';
|
|
577
|
+
try {
|
|
578
|
+
udid = resolveIosUdid(options) || '';
|
|
579
|
+
} catch (_) {
|
|
580
|
+
udid = '';
|
|
581
|
+
}
|
|
582
|
+
add('ios-udid', Boolean(udid), {
|
|
583
|
+
detail: udid || 'no booted simulator resolved',
|
|
584
|
+
hint: 'Boot a simulator (xcrun simctl boot <udid>) or pass --udid / set MOBILE_E2E_IOS_UDID.',
|
|
585
|
+
});
|
|
586
|
+
} else {
|
|
587
|
+
const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || '';
|
|
588
|
+
add('android-sdk-env', Boolean(sdk), {
|
|
589
|
+
detail: sdk || 'ANDROID_HOME / ANDROID_SDK_ROOT unset',
|
|
590
|
+
hint: 'Set ANDROID_HOME so `adb` resolves in a headless (systemd/CI) shell.',
|
|
591
|
+
fatal: false,
|
|
592
|
+
});
|
|
593
|
+
// A booted device is NOT required here (the nightly boots it after this
|
|
594
|
+
// step); report readiness as an advisory only.
|
|
595
|
+
const devices = adbRuns ? (`${adbProbe.stdout || ''}`.match(/^\S+\s+device\b/gm) || []).length : 0;
|
|
596
|
+
add('device-ready', devices > 0, {
|
|
597
|
+
detail: devices > 0 ? `${devices} device(s) online` : 'none online yet',
|
|
598
|
+
hint: 'device-up.sh boots the emulator; a run without it will fail at the adb preflight.',
|
|
599
|
+
fatal: false,
|
|
600
|
+
});
|
|
601
|
+
}
|
|
602
|
+
|
|
603
|
+
const toolDirs = toolPathDirs();
|
|
604
|
+
add('step-path', toolDirs.length > 0 || Boolean(adb) || Boolean(maestro), {
|
|
605
|
+
detail: toolDirs.length ? `platform-tools/maestro added: ${toolDirs.join(', ')}` : 'nothing to add (tools already on PATH)',
|
|
606
|
+
fatal: false,
|
|
607
|
+
});
|
|
608
|
+
|
|
609
|
+
const failed = checks.filter((c) => c.fatal && !c.ok);
|
|
610
|
+
for (const c of checks) {
|
|
611
|
+
const mark = c.ok ? 'ok' : c.fatal ? 'FAIL' : 'warn';
|
|
612
|
+
console.log(`device-preflight: ${mark.padEnd(4)} ${c.name} — ${c.detail}`);
|
|
613
|
+
if (!c.ok && c.hint) console.log(` ${c.hint}`);
|
|
614
|
+
}
|
|
615
|
+
console.log(failed.length ? `device-preflight: FAILED (${failed.map((c) => c.name).join(', ')})` : 'device-preflight: OK');
|
|
616
|
+
return failed.length ? 1 : 0;
|
|
617
|
+
}
|
|
618
|
+
|
|
619
|
+
/**
|
|
620
|
+
* Resolve the iOS Simulator UDID to hand to `maestro test --device`. Priority:
|
|
621
|
+
* an explicit `--udid`, then `MOBILE_E2E_IOS_UDID`, then a booted simulator
|
|
622
|
+
* discovered via `xcrun simctl list devices booted -j` and matched against
|
|
623
|
+
* local.json `ios.deviceName`. Fails loudly when nothing resolves — a run with
|
|
624
|
+
* no target device would otherwise fail later with a cryptic Maestro error.
|
|
625
|
+
*/
|
|
626
|
+
function resolveIosUdid(options = {}) {
|
|
627
|
+
const explicit = options.udid || process.env.MOBILE_E2E_IOS_UDID;
|
|
628
|
+
if (explicit) return String(explicit).trim();
|
|
629
|
+
const deviceName =
|
|
630
|
+
process.env.MOBILE_E2E_IOS_DEVICE_NAME || (LOCAL_CONFIG.ios && LOCAL_CONFIG.ios.deviceName) || '';
|
|
631
|
+
const probe = spawnSync('xcrun', ['simctl', 'list', 'devices', 'booted', '-j'], {
|
|
632
|
+
encoding: 'utf8',
|
|
633
|
+
timeout: 10000,
|
|
634
|
+
});
|
|
635
|
+
if (probe.error || probe.status !== 0) {
|
|
636
|
+
console.error('FAIL — could not list booted iOS simulators (is this a macOS host with Xcode?).');
|
|
637
|
+
console.error(' Bring one up first: node scripts/qa/mobile-e2e/ios-simulator-up.sh');
|
|
638
|
+
process.exit(1);
|
|
639
|
+
}
|
|
640
|
+
let list;
|
|
641
|
+
try {
|
|
642
|
+
list = JSON.parse(probe.stdout || '{}');
|
|
643
|
+
} catch {
|
|
644
|
+
list = {};
|
|
645
|
+
}
|
|
646
|
+
const all = [];
|
|
647
|
+
for (const devices of Object.values(list.devices || {})) {
|
|
648
|
+
for (const device of devices) all.push(device);
|
|
649
|
+
}
|
|
650
|
+
const match = deviceName ? all.find((d) => d.name === deviceName) : null;
|
|
651
|
+
const udid = (match || all[0] || {}).udid;
|
|
652
|
+
if (!udid) {
|
|
653
|
+
console.error('FAIL — no booted iOS Simulator found.');
|
|
654
|
+
console.error(' Bring one up first: node scripts/qa/mobile-e2e/ios-simulator-up.sh');
|
|
655
|
+
console.error(' Or pass --udid <id> / set MOBILE_E2E_IOS_UDID.');
|
|
656
|
+
process.exit(1);
|
|
657
|
+
}
|
|
658
|
+
return String(udid);
|
|
659
|
+
}
|
|
660
|
+
|
|
661
|
+
/** Strip ANSI SGR escape sequences so a captured reason is stable text. */
|
|
662
|
+
function stripAnsi(text) {
|
|
663
|
+
return String(text).replace(/\u001b\[[0-9;]*[A-Za-z]/g, '');
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
/**
|
|
667
|
+
* Extract the failure reason from a single flow's captured output. Maestro ends
|
|
668
|
+
* with a per-flow summary line shaped:
|
|
669
|
+
* [Failed] approve-handoff (2m 31s) (Element not found: Id matching regex: tx-approve-{id})
|
|
670
|
+
* where the final parenthesised group is the reason. When no summary is present,
|
|
671
|
+
* fall back to the last non-empty output line.
|
|
672
|
+
*/
|
|
673
|
+
function extractFailureReason(output, flowName) {
|
|
674
|
+
const lines = stripAnsi(output)
|
|
675
|
+
.split(/\r?\n/)
|
|
676
|
+
.map((line) => line.trim());
|
|
677
|
+
const summary = /^\[Failed\]\s+\S+\s+.*\((.*)\)\s*$/;
|
|
678
|
+
for (let i = lines.length - 1; i >= 0; i -= 1) {
|
|
679
|
+
const match = lines[i].match(summary);
|
|
680
|
+
if (match) return match[1].trim();
|
|
681
|
+
}
|
|
682
|
+
// Maestro's single-flow output ends with a human failure block whose last line
|
|
683
|
+
// is the debug-artifacts path — meaningless as a "reason" and identical across
|
|
684
|
+
// unrelated failures, which would make the fail-fast collapse them. Prefer the
|
|
685
|
+
// first meaningful failure line (scanning the preferred categories in order,
|
|
686
|
+
// each from the end), and never return the artifact path.
|
|
687
|
+
const preferred = [
|
|
688
|
+
/^Assertion .* failed/i,
|
|
689
|
+
/^Assertion is false:/i,
|
|
690
|
+
/^No visible element found/i,
|
|
691
|
+
/^Could not find a visible element/i,
|
|
692
|
+
/^Element not found/i,
|
|
693
|
+
/failed to (connect|launch)/i,
|
|
694
|
+
];
|
|
695
|
+
for (const pattern of preferred) {
|
|
696
|
+
for (let i = lines.length - 1; i >= 0; i -= 1) {
|
|
697
|
+
if (pattern.test(lines[i])) return lines[i].replace(/\s+/g, ' ');
|
|
698
|
+
}
|
|
699
|
+
}
|
|
700
|
+
const isNoise = (line) =>
|
|
701
|
+
line === '' ||
|
|
702
|
+
/^=+\s*Debug output/i.test(line) ||
|
|
703
|
+
/^Possible causes:/i.test(line) ||
|
|
704
|
+
/^[-·*]\s/.test(line) ||
|
|
705
|
+
/debug artifacts/i.test(line) ||
|
|
706
|
+
/\.maestro[/\\]tests[/\\]/.test(line) ||
|
|
707
|
+
/^cacheException/i.test(line);
|
|
708
|
+
for (let i = lines.length - 1; i >= 0; i -= 1) {
|
|
709
|
+
if (!isNoise(lines[i])) return lines[i];
|
|
710
|
+
}
|
|
711
|
+
return `flow ${flowName} failed`;
|
|
712
|
+
}
|
|
713
|
+
|
|
714
|
+
/**
|
|
715
|
+
* Normalise a flow reference to the key both the manifest and Maestro's summary
|
|
716
|
+
* agree on: the basename with any `.yaml`/`.yml` extension stripped. Maestro's
|
|
717
|
+
* per-flow summary prints `manager-approvals` (no extension) while the runner
|
|
718
|
+
* tracks `manager-approvals.yaml`; matching on the raw string silently treated
|
|
719
|
+
* every batched failure as a pass (manager-approvals + offline-sync-recovery
|
|
720
|
+
* were lost in the 2026-10-01 full matrix).
|
|
721
|
+
*/
|
|
722
|
+
function flowKey(name) {
|
|
723
|
+
return String(name).replace(/\.ya?ml$/i, '');
|
|
724
|
+
}
|
|
725
|
+
|
|
726
|
+
/**
|
|
727
|
+
* Parse every `[Failed] <flow> (<duration>) (<reason>)` summary line out of a
|
|
728
|
+
* (possibly multi-flow) `maestro test` output. Returns a Map of normalised flow
|
|
729
|
+
* key -> reason. Flows absent from the map ran clean. This is what lets a
|
|
730
|
+
* batched invocation still report per-journey results.
|
|
731
|
+
*/
|
|
732
|
+
function parseFailedFlows(output) {
|
|
733
|
+
const failed = new Map();
|
|
734
|
+
const pattern = /^\[Failed\]\s+(\S+)\s+\([^)]*\)\s*\(([\s\S]*)\)\s*$/;
|
|
735
|
+
stripAnsi(output)
|
|
736
|
+
.split(/\r?\n/)
|
|
737
|
+
.map((line) => line.trim())
|
|
738
|
+
.forEach((line) => {
|
|
739
|
+
const match = line.match(pattern);
|
|
740
|
+
if (match) failed.set(flowKey(match[1]), match[2].trim());
|
|
741
|
+
});
|
|
742
|
+
return failed;
|
|
743
|
+
}
|
|
744
|
+
|
|
745
|
+
/**
|
|
746
|
+
* Parse Maestro's per-flow duration from `[Passed|Failed] <flow> (<dur>)` summary
|
|
747
|
+
* lines (e.g. `1m 23s`, `59s`) into milliseconds, keyed by the normalised flow
|
|
748
|
+
* key. Absent for single-flow invocations, whose duration the caller measures
|
|
749
|
+
* directly from the invocation wall clock.
|
|
750
|
+
*/
|
|
751
|
+
function parseFlowDurations(output) {
|
|
752
|
+
const durations = new Map();
|
|
753
|
+
const pattern = /^\[(?:Passed|Failed)\]\s+(\S+)\s+\(([^)]*)\)/;
|
|
754
|
+
stripAnsi(output)
|
|
755
|
+
.split(/\r?\n/)
|
|
756
|
+
.map((line) => line.trim())
|
|
757
|
+
.forEach((line) => {
|
|
758
|
+
const match = line.match(pattern);
|
|
759
|
+
if (match) durations.set(flowKey(match[1]), parseMaestroDuration(match[2]));
|
|
760
|
+
});
|
|
761
|
+
return durations;
|
|
762
|
+
}
|
|
763
|
+
|
|
764
|
+
/** Parse a Maestro duration token (`1m 23s`, `59s`, `2m`, `500ms`) to ms. */
|
|
765
|
+
function parseMaestroDuration(token) {
|
|
766
|
+
const text = String(token).trim();
|
|
767
|
+
const ms = text.match(/^(\d+)ms$/);
|
|
768
|
+
if (ms) return Number(ms[1]);
|
|
769
|
+
const m = text.match(/^(?:(\d+)m)?\s*(?:(\d+)s)?$/);
|
|
770
|
+
if (!m || (!m[1] && !m[2])) return null;
|
|
771
|
+
return (Number(m[1] || 0) * 60 + Number(m[2] || 0)) * 1000;
|
|
772
|
+
}
|
|
773
|
+
|
|
774
|
+
/**
|
|
775
|
+
* Reduce a failure reason to a signature so two flows that fail for the same
|
|
776
|
+
* root cause collapse to one signature: strip ANSI, drop volatile values (UUIDs,
|
|
777
|
+
* any digit run), and remove a leading `[Failed] <flow> (<duration>)` prefix.
|
|
778
|
+
*/
|
|
779
|
+
function normaliseFailureReason(reason, flowName) {
|
|
780
|
+
let signature = stripAnsi(reason).trim();
|
|
781
|
+
signature = signature.replace(/[0-9a-fA-F]{8}-[0-9a-fA-F-]{27,}/g, '<uuid>');
|
|
782
|
+
signature = signature.replace(/\d+/g, '#');
|
|
783
|
+
signature = signature.replace(/^\[Failed\]\s+\S+\s+\((.*?)\)\s*/, '');
|
|
784
|
+
signature = signature.replace(/\s+/g, ' ').trim();
|
|
785
|
+
return signature || `flow ${flowName} failed`;
|
|
786
|
+
}
|
|
787
|
+
|
|
788
|
+
/** Choose a suggested fix for a repeated failure signature (heuristic). */
|
|
789
|
+
function suggestFix(reason) {
|
|
790
|
+
const signature = String(reason);
|
|
791
|
+
if (/Id matching regex/.test(signature) && /[{]|\\\{/.test(signature)) {
|
|
792
|
+
return 'the selector still uses a literal placeholder / unresolved regex; convert it to `foo-.*` or check the testID registry in mobile/.';
|
|
793
|
+
}
|
|
794
|
+
if (/first launch/i.test(signature) || /entry state|login screen/i.test(signature)) {
|
|
795
|
+
return 'flows cannot reach the entry state after `clearState`; use an embedded-bundle build (release), not a Metro dev-client (clearState wipes the dev-server URL); also check the device blocker.';
|
|
796
|
+
}
|
|
797
|
+
if (/Multiple elements/.test(signature)) {
|
|
798
|
+
return 'the `-.*` regex is ambiguous; narrow it / add an index.';
|
|
799
|
+
}
|
|
800
|
+
return 'inspect the shared error; it is the common root cause for these flows.';
|
|
801
|
+
}
|
|
802
|
+
|
|
803
|
+
/**
|
|
804
|
+
* A declared setup that wipes the app's data dir (`pm clear`/`clearState`) also
|
|
805
|
+
* wipes the signed-in session, so the flow must re-establish it. The planner
|
|
806
|
+
* otherwise only switches on an actor change / firstLogin — `scan-add` clears
|
|
807
|
+
* the app in its setup yet was planned as a warm reuse, limping through the
|
|
808
|
+
* login fallback with a 25 s wasted probe (2026-10-01 full matrix).
|
|
809
|
+
*/
|
|
810
|
+
function setupClearsAppState(setup) {
|
|
811
|
+
return /(^|[^A-Za-z])pm\s+clear\b/i.test(String(setup || '')) || /clearState/i.test(String(setup || ''));
|
|
812
|
+
}
|
|
813
|
+
|
|
814
|
+
/**
|
|
815
|
+
* A journey whose declared setup is additive and explicitly opted into batching
|
|
816
|
+
* (`batchSetup: true`) may share a warm invocation with other opt-in journeys of
|
|
817
|
+
* the same actor: the runner runs every setup immediately before the batch. It
|
|
818
|
+
* is deliberately off by default — the project asserts its setups are
|
|
819
|
+
* order-independent and non-clearing in `matrix.yaml`.
|
|
820
|
+
*/
|
|
821
|
+
function isSetupGroupable(journey) {
|
|
822
|
+
return Boolean(
|
|
823
|
+
journey &&
|
|
824
|
+
journey.batchSetup &&
|
|
825
|
+
journey.setup &&
|
|
826
|
+
!journey.oracle &&
|
|
827
|
+
!journey.firstLogin &&
|
|
828
|
+
!setupClearsAppState(journey.setup) &&
|
|
829
|
+
(!journey.endsAs || journey.endsAs === (journey.actor || DEFAULT_ACTOR))
|
|
830
|
+
);
|
|
831
|
+
}
|
|
832
|
+
|
|
833
|
+
/** Build the ordered per-flow records the planner consumes. */
|
|
834
|
+
function buildFlowRecords(flowFiles, stepsByFlow) {
|
|
835
|
+
return flowFiles.map((file) => {
|
|
836
|
+
const name = path.basename(file);
|
|
837
|
+
const journey = stepsByFlow.get(name) || {};
|
|
838
|
+
return {
|
|
839
|
+
file,
|
|
840
|
+
name,
|
|
841
|
+
actor: journey.actor || DEFAULT_ACTOR,
|
|
842
|
+
endsAs: journey.endsAs || journey.actor || DEFAULT_ACTOR,
|
|
843
|
+
setup: journey.setup || null,
|
|
844
|
+
oracle: journey.oracle || null,
|
|
845
|
+
hasSetup: Boolean(journey.setup),
|
|
846
|
+
hasOracle: Boolean(journey.oracle),
|
|
847
|
+
firstLogin: Boolean(journey.firstLogin),
|
|
848
|
+
clearsAppState: setupClearsAppState(journey.setup),
|
|
849
|
+
batchSetup: isSetupGroupable(journey),
|
|
850
|
+
};
|
|
851
|
+
});
|
|
852
|
+
}
|
|
853
|
+
|
|
854
|
+
/**
|
|
855
|
+
* Move journeys that declare `firstLogin: true` to the front (stable). A
|
|
856
|
+
* first-login scenario `clearState`s the app to prove the fresh onboarding, and
|
|
857
|
+
* `pm clear` wipes the whole app data dir — including every actor's persisted
|
|
858
|
+
* "walkthrough seen" flag. Running it first means that wipe happens before the
|
|
859
|
+
* other journeys reuse a mixed set of sessions; running it mid-run would reset
|
|
860
|
+
* the flag and re-onboard the actors the rest of the run depends on.
|
|
861
|
+
*/
|
|
862
|
+
function orderFirstLoginFirst(flowFiles, stepsByFlow) {
|
|
863
|
+
const first = [];
|
|
864
|
+
const rest = [];
|
|
865
|
+
flowFiles.forEach((file) => {
|
|
866
|
+
const journey = stepsByFlow.get(path.basename(file));
|
|
867
|
+
(journey && journey.firstLogin ? first : rest).push(file);
|
|
868
|
+
});
|
|
869
|
+
return [...first, ...rest];
|
|
870
|
+
}
|
|
871
|
+
|
|
872
|
+
/**
|
|
873
|
+
* Order the selected flows to maximise warm-session batching (`--reuse-session`).
|
|
874
|
+
*
|
|
875
|
+
* The planner only batches *consecutive* same-actor, setup/oracle-free journeys,
|
|
876
|
+
* so the alphabetical order a cold run uses scatters an actor's batchable flows
|
|
877
|
+
* among standalone ones — the F-296 run batched just 2 of 26 journeys (24
|
|
878
|
+
* invocations). Regroup: the `firstLogin` scenario first (unchanged), then each
|
|
879
|
+
* actor's flows together with the standalone (setup/oracle/`endsAs`) ones before
|
|
880
|
+
* its batchable run so the batch is never interrupted. Deterministic: actors and
|
|
881
|
+
* flows keep their incoming order.
|
|
882
|
+
*/
|
|
883
|
+
function orderForSessionReuse(flowFiles, stepsByFlow) {
|
|
884
|
+
const first = [];
|
|
885
|
+
const groups = new Map();
|
|
886
|
+
flowFiles.forEach((file) => {
|
|
887
|
+
const journey = stepsByFlow.get(path.basename(file)) || {};
|
|
888
|
+
if (journey.firstLogin) {
|
|
889
|
+
first.push(file);
|
|
890
|
+
return;
|
|
891
|
+
}
|
|
892
|
+
const actor = journey.actor || DEFAULT_ACTOR;
|
|
893
|
+
// A setup-bearing journey is standalone unless it explicitly opted into
|
|
894
|
+
// setup batching (`batchSetup: true`) and qualifies as order-independent.
|
|
895
|
+
const standalone = Boolean(
|
|
896
|
+
(journey.setup && !isSetupGroupable(journey)) ||
|
|
897
|
+
journey.oracle ||
|
|
898
|
+
(journey.endsAs && journey.endsAs !== actor)
|
|
899
|
+
);
|
|
900
|
+
if (!groups.has(actor)) groups.set(actor, { standalone: [], batchable: [] });
|
|
901
|
+
groups.get(actor)[standalone ? 'standalone' : 'batchable'].push(file);
|
|
902
|
+
});
|
|
903
|
+
const ordered = [...first];
|
|
904
|
+
[...groups.keys()].sort().forEach((actor) => {
|
|
905
|
+
const group = groups.get(actor);
|
|
906
|
+
ordered.push(...group.standalone, ...group.batchable);
|
|
907
|
+
});
|
|
908
|
+
return ordered;
|
|
909
|
+
}
|
|
910
|
+
|
|
911
|
+
/**
|
|
912
|
+
* Turn the ordered flow records into `maestro test` invocations.
|
|
913
|
+
*
|
|
914
|
+
* Default: one invocation per flow (preserves per-flow fail-fast granularity).
|
|
915
|
+
* With `reuseSession`: a run of consecutive same-actor, setup/oracle-free,
|
|
916
|
+
* non-first-login journeys becomes one warm invocation (shared session, one
|
|
917
|
+
* JVM). A journey whose actor changes — or that declares a `setup:`/`oracle:`
|
|
918
|
+
* step or `firstLogin:` — is always its own invocation. `switchUser` maps to
|
|
919
|
+
* `MOBILE_E2E_SWITCH` in `_shared/session.yaml`: it means "sign the current
|
|
920
|
+
* actor out first, then sign in as this journey's actor" (never `clearState`,
|
|
921
|
+
* so the device's per-actor onboarding state survives the run).
|
|
922
|
+
*/
|
|
923
|
+
function planInvocations(records, reuseSession) {
|
|
924
|
+
const invocations = [];
|
|
925
|
+
let currentActor = null;
|
|
926
|
+
let batch = null;
|
|
927
|
+
const flush = () => {
|
|
928
|
+
if (batch && batch.length > 0) {
|
|
929
|
+
invocations.push({ records: batch.slice(), actor: batch[0].actor, switchUser: false });
|
|
930
|
+
}
|
|
931
|
+
batch = null;
|
|
932
|
+
};
|
|
933
|
+
records.forEach((record) => {
|
|
934
|
+
const actorChanged = record.actor !== currentActor;
|
|
935
|
+
// A flow that leaves a different actor signed in (`endsAs`) changes the
|
|
936
|
+
// device session, so it must run alone and the next flow must switch. A
|
|
937
|
+
// setup-bearing flow is standalone unless it opted into setup batching
|
|
938
|
+
// (`batchSetup: true`); a setup that clears app data always stands alone.
|
|
939
|
+
const standalone =
|
|
940
|
+
record.hasOracle ||
|
|
941
|
+
record.firstLogin ||
|
|
942
|
+
record.endsAs !== record.actor ||
|
|
943
|
+
record.clearsAppState ||
|
|
944
|
+
(record.hasSetup && !record.batchSetup);
|
|
945
|
+
if (reuseSession && !actorChanged && !standalone) {
|
|
946
|
+
if (!batch) batch = [];
|
|
947
|
+
batch.push(record);
|
|
948
|
+
} else {
|
|
949
|
+
flush();
|
|
950
|
+
invocations.push({
|
|
951
|
+
records: [record],
|
|
952
|
+
actor: record.actor,
|
|
953
|
+
switchUser: Boolean(!reuseSession || actorChanged || record.firstLogin || record.clearsAppState),
|
|
954
|
+
});
|
|
955
|
+
}
|
|
956
|
+
currentActor = record.endsAs || record.actor;
|
|
957
|
+
});
|
|
958
|
+
flush();
|
|
959
|
+
return invocations;
|
|
960
|
+
}
|
|
961
|
+
|
|
962
|
+
/**
|
|
963
|
+
* Run one or more flow files via a single `maestro test` invocation, streaming
|
|
964
|
+
* the child's output LIVE as it arrives.
|
|
965
|
+
*
|
|
966
|
+
* This used to be `spawnSync(...)`, which buffers the child's entire stdout
|
|
967
|
+
* until it exits: a batched invocation (up to a dozen journeys in one JVM) then
|
|
968
|
+
* wrote nothing to the log or the job-events stream for its whole duration, so a
|
|
969
|
+
* healthy multi-minute batch was indistinguishable from a hang (the 2026-10-02
|
|
970
|
+
* "frozen matrix" — the log sat at the batch header for 10+ minutes while a
|
|
971
|
+
* 12-flow invocation ran). Streaming each chunk through (while still capturing
|
|
972
|
+
* the whole text for failure parsing) fixes the observability gap; `onChunk`
|
|
973
|
+
* lets the caller reset its stall watchdog.
|
|
974
|
+
*/
|
|
975
|
+
function runMaestroFlows(files, options, session, onChunk) {
|
|
976
|
+
const args = ['test'];
|
|
977
|
+
if (options.config && fs.existsSync(options.config)) {
|
|
978
|
+
args.push('--config', options.config);
|
|
979
|
+
}
|
|
980
|
+
if (!options.reinstallDriver) args.push('--no-reinstall-driver');
|
|
981
|
+
// iOS: every invocation targets the resolved Simulator explicitly. Android
|
|
982
|
+
// leaves `udid` null, so its command line is byte-identical to before.
|
|
983
|
+
if (options.udid) args.push('--device', options.udid);
|
|
984
|
+
args.push('-e', `APP_ID=${options.appId}`);
|
|
985
|
+
args.push('-e', `MOBILE_E2E_SWITCH=${session.switchUser ? '1' : '0'}`);
|
|
986
|
+
args.push('-e', `MOBILE_E2E_PHONE=${session.actor}`);
|
|
987
|
+
args.push(...files);
|
|
988
|
+
|
|
989
|
+
return new Promise((resolve) => {
|
|
990
|
+
let settled = false;
|
|
991
|
+
const done = (result) => {
|
|
992
|
+
if (settled) return;
|
|
993
|
+
settled = true;
|
|
994
|
+
resolve(result);
|
|
995
|
+
};
|
|
996
|
+
const stdout = [];
|
|
997
|
+
const stderr = [];
|
|
998
|
+
const relay = (buf, sink, stream) => {
|
|
999
|
+
const text = buf.toString();
|
|
1000
|
+
sink.push(text);
|
|
1001
|
+
stream.write(text);
|
|
1002
|
+
if (typeof onChunk === 'function') onChunk(text);
|
|
1003
|
+
};
|
|
1004
|
+
let child;
|
|
1005
|
+
try {
|
|
1006
|
+
child = spawn(resolveMaestro() || 'maestro', args, { shell: false });
|
|
1007
|
+
} catch (err) {
|
|
1008
|
+
const text = `\nmaestro failed to start: ${err && err.message ? err.message : err}\n`;
|
|
1009
|
+
stderr.push(text);
|
|
1010
|
+
process.stderr.write(text);
|
|
1011
|
+
return done({ status: 1, output: `${stdout.join('')}\n${stderr.join('')}` });
|
|
1012
|
+
}
|
|
1013
|
+
child.stdout.on('data', (buf) => relay(buf, stdout, process.stdout));
|
|
1014
|
+
child.stderr.on('data', (buf) => relay(buf, stderr, process.stderr));
|
|
1015
|
+
child.on('error', (err) => {
|
|
1016
|
+
const text = `\nmaestro failed to start: ${err && err.message ? err.message : err}\n`;
|
|
1017
|
+
stderr.push(text);
|
|
1018
|
+
process.stderr.write(text);
|
|
1019
|
+
done({ status: 1, output: `${stdout.join('')}\n${stderr.join('')}` });
|
|
1020
|
+
});
|
|
1021
|
+
child.on('close', (code) => {
|
|
1022
|
+
done({ status: code === null ? 1 : code, output: `${stdout.join('')}\n${stderr.join('')}` });
|
|
1023
|
+
});
|
|
1024
|
+
});
|
|
1025
|
+
}
|
|
1026
|
+
|
|
1027
|
+
function reportFailFast(signature, flowNames, skipped) {
|
|
1028
|
+
console.error('');
|
|
1029
|
+
console.error('============================================================');
|
|
1030
|
+
console.error(`FAIL-FAST STOP — ${flowNames.length} flow(s) failed for the same reason.`);
|
|
1031
|
+
console.error(`Shared reason: ${signature}`);
|
|
1032
|
+
console.error(`Flows (${flowNames.length}): ${flowNames.join(', ')}`);
|
|
1033
|
+
console.error(`Skipped (${skipped.length}): ${skipped.length > 0 ? skipped.join(', ') : '(none)'}`);
|
|
1034
|
+
console.error(`Suggested fix: ${suggestFix(signature)}`);
|
|
1035
|
+
console.error('============================================================');
|
|
1036
|
+
}
|
|
1037
|
+
|
|
1038
|
+
function printSequence(options) {
|
|
1039
|
+
console.log('Mobile E2E (Maestro) — device run');
|
|
1040
|
+
console.log(`appId: ${options.appId}`);
|
|
1041
|
+
if (options.platform === 'ios') console.log('platform: ios (Simulator)');
|
|
1042
|
+
if (options.reuseSession) console.log('mode: reuse-session (one sign-in per actor, batched)');
|
|
1043
|
+
console.log('');
|
|
1044
|
+
console.log('Documented sequence:');
|
|
1045
|
+
console.log(
|
|
1046
|
+
options.platform === 'ios'
|
|
1047
|
+
? ' 1. node scripts/qa/mobile-e2e/ios-simulator-up.sh'
|
|
1048
|
+
: ' 1. node scripts/qa/mobile-e2e/boot-emulator.sh'
|
|
1049
|
+
);
|
|
1050
|
+
console.log(' 2. node scripts/serve.js start --cmd "npm run dev" --url http://localhost:3000');
|
|
1051
|
+
console.log(
|
|
1052
|
+
options.noReset
|
|
1053
|
+
? ' 3. npm run mobile-e2e:reset # skipped (--no-reset); using the current dev DB state'
|
|
1054
|
+
: options.noSeed
|
|
1055
|
+
? ' 3. node scripts/qa/mobile-e2e/reset.js --no-seed # actor auth only'
|
|
1056
|
+
: ' 3. npm run mobile-e2e:reset # seed dev DB + mint the E2E actor UserAuth rows'
|
|
1057
|
+
);
|
|
1058
|
+
console.log(' 4. node scripts/qa/mobile-e2e/run-maestro.js --flows all');
|
|
1059
|
+
console.log('');
|
|
1060
|
+
}
|
|
1061
|
+
|
|
1062
|
+
/**
|
|
1063
|
+
* Deterministic dev-DB reset before the device run. Invokes `reset.js` (which
|
|
1064
|
+
* owns the uat/prod boundary guard + seed + actor UserAuth mint) unless
|
|
1065
|
+
* `--no-reset` was passed. `--no-seed` is forwarded so a re-verification run can
|
|
1066
|
+
* mint actor auth without re-seeding everything.
|
|
1067
|
+
*
|
|
1068
|
+
* Speed: for a SUBSET re-run whose seed fingerprint is unchanged, the ~90 s full
|
|
1069
|
+
* seed is skipped automatically (mint actor auth only). The full matrix
|
|
1070
|
+
* (`--flows all`) always reseeds so it lands a known baseline, and an explicit
|
|
1071
|
+
* `--no-seed`/`--force-reset` always wins. A matched fingerprint can still be
|
|
1072
|
+
* stale (the dev DB volume was recreated), so a failed `--no-seed` retries once
|
|
1073
|
+
* with the full seed instead of failing the run.
|
|
1074
|
+
*/
|
|
1075
|
+
function runReset(options, ctx = {}) {
|
|
1076
|
+
if (options.noReset) {
|
|
1077
|
+
console.log('Skipping reset (--no-reset); using the current dev DB state.');
|
|
1078
|
+
return;
|
|
1079
|
+
}
|
|
1080
|
+
if (!fs.existsSync(RESET_SCRIPT)) {
|
|
1081
|
+
console.log('No reset.js in this project — skipping the dev-DB reset.');
|
|
1082
|
+
return;
|
|
1083
|
+
}
|
|
1084
|
+
|
|
1085
|
+
const dbUrl = resolveDevDatabaseUrl();
|
|
1086
|
+
const fingerprint = seedFingerprint();
|
|
1087
|
+
const state = readSeedState();
|
|
1088
|
+
const stateMatches = !!(state && state.fingerprint === fingerprint && state.db === dbUrl);
|
|
1089
|
+
const autoNoSeed = shouldAutoNoSeed({
|
|
1090
|
+
explicitNoSeed: options.noSeed,
|
|
1091
|
+
noReset: options.noReset,
|
|
1092
|
+
forceReset: options.forceReset,
|
|
1093
|
+
subset: !!ctx.subset,
|
|
1094
|
+
stateMatches,
|
|
1095
|
+
});
|
|
1096
|
+
const useNoSeed = options.noSeed || autoNoSeed;
|
|
1097
|
+
|
|
1098
|
+
if (autoNoSeed) {
|
|
1099
|
+
console.log('Seed fingerprint unchanged; subset re-run — minting actor auth only (use --force-reset to reseed).');
|
|
1100
|
+
}
|
|
1101
|
+
|
|
1102
|
+
const attempt = (noSeed) => {
|
|
1103
|
+
const args = [RESET_SCRIPT];
|
|
1104
|
+
if (noSeed) args.push('--no-seed');
|
|
1105
|
+
console.log(
|
|
1106
|
+
`Resetting the dev database + minting actor auth: ${path.relative(options.root, RESET_SCRIPT)}${noSeed ? ' --no-seed' : ''}`
|
|
1107
|
+
);
|
|
1108
|
+
return spawnSync(process.execPath, args, { stdio: 'inherit', shell: false });
|
|
1109
|
+
};
|
|
1110
|
+
|
|
1111
|
+
let result = attempt(useNoSeed);
|
|
1112
|
+
// A matched fingerprint can be stale/wiped (docker volume recreated): recover
|
|
1113
|
+
// with a full seed rather than aborting the run. Never second-guess an
|
|
1114
|
+
// EXPLICIT --no-seed (the operator asked for exactly that).
|
|
1115
|
+
if (result.status !== 0 && useNoSeed && !options.noSeed) {
|
|
1116
|
+
console.log(' ! --no-seed reset failed (stale DB state?) — falling back to a full seed.');
|
|
1117
|
+
result = attempt(false);
|
|
1118
|
+
}
|
|
1119
|
+
if (result.status !== 0) {
|
|
1120
|
+
console.error(`FAIL — reset.js exited ${result.status}.`);
|
|
1121
|
+
console.error(' Run it manually to inspect: node scripts/qa/mobile-e2e/reset.js');
|
|
1122
|
+
process.exit(result.status === null ? 1 : result.status);
|
|
1123
|
+
}
|
|
1124
|
+
// Only a full seed earns the fingerprint; a --no-seed run leaves the prior
|
|
1125
|
+
// state untouched (and there may be none for a first-ever subset run).
|
|
1126
|
+
if (!useNoSeed) writeSeedState({ fingerprint, db: dbUrl, at: new Date().toISOString() });
|
|
1127
|
+
}
|
|
1128
|
+
|
|
1129
|
+
/** Read the previous run report's failed journeys (for `--failed`). */
|
|
1130
|
+
function readFailedFlowNames(reportPath) {
|
|
1131
|
+
try {
|
|
1132
|
+
const report = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
|
|
1133
|
+
return (report.flows || [])
|
|
1134
|
+
.filter((flow) => flow.status !== 'pass')
|
|
1135
|
+
.map((flow) => flow.name)
|
|
1136
|
+
.filter(Boolean);
|
|
1137
|
+
} catch {
|
|
1138
|
+
return [];
|
|
1139
|
+
}
|
|
1140
|
+
}
|
|
1141
|
+
|
|
1142
|
+
/** The MAIN worktree root, or null. A feature worktree has its OWN empty
|
|
1143
|
+
* `.serve/`, so `--failed` run from a worktree cannot see the report the matrix
|
|
1144
|
+
* wrote in the MAIN checkout (the F-302 "nothing to re-run" dead end). */
|
|
1145
|
+
function mainWorktreeRoot() {
|
|
1146
|
+
try {
|
|
1147
|
+
const r = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
|
|
1148
|
+
cwd: REPO_ROOT,
|
|
1149
|
+
encoding: 'utf8',
|
|
1150
|
+
});
|
|
1151
|
+
if (r.status === 0 && r.stdout && r.stdout.trim()) {
|
|
1152
|
+
const common = r.stdout.trim();
|
|
1153
|
+
if (path.basename(common) === '.git') return path.dirname(common);
|
|
1154
|
+
}
|
|
1155
|
+
} catch {
|
|
1156
|
+
/* not a git checkout */
|
|
1157
|
+
}
|
|
1158
|
+
return null;
|
|
1159
|
+
}
|
|
1160
|
+
|
|
1161
|
+
/** Resolve the last-run report `--failed` reads: an explicit `--report`, else the
|
|
1162
|
+
* newest report among this checkout, the MAIN checkout, and sibling worktrees.
|
|
1163
|
+
* `opts` (primaryReport/mainRoot) is a test seam. */
|
|
1164
|
+
function resolveFailedReport(explicit, opts = {}) {
|
|
1165
|
+
if (explicit) return fs.existsSync(explicit) ? explicit : null;
|
|
1166
|
+
const candidates = [opts.primaryReport || REPORT_FILE];
|
|
1167
|
+
const main = opts.mainRoot !== undefined ? opts.mainRoot : mainWorktreeRoot();
|
|
1168
|
+
if (main) {
|
|
1169
|
+
candidates.push(path.join(main, '.serve', 'mobile-e2e-last-run.json'));
|
|
1170
|
+
const wtBase = path.join(path.dirname(main), '.worktrees', path.basename(main));
|
|
1171
|
+
try {
|
|
1172
|
+
for (const id of fs.readdirSync(wtBase)) {
|
|
1173
|
+
candidates.push(path.join(wtBase, id, '.serve', 'mobile-e2e-last-run.json'));
|
|
1174
|
+
}
|
|
1175
|
+
} catch {
|
|
1176
|
+
/* no sibling worktrees */
|
|
1177
|
+
}
|
|
1178
|
+
}
|
|
1179
|
+
let best = null;
|
|
1180
|
+
for (const c of candidates) {
|
|
1181
|
+
let stat;
|
|
1182
|
+
try {
|
|
1183
|
+
stat = fs.statSync(c);
|
|
1184
|
+
} catch {
|
|
1185
|
+
continue;
|
|
1186
|
+
}
|
|
1187
|
+
if (stat.isFile() && (!best || stat.mtimeMs > best.mtimeMs)) best = { file: c, mtimeMs: stat.mtimeMs };
|
|
1188
|
+
}
|
|
1189
|
+
return best ? best.file : null;
|
|
1190
|
+
}
|
|
1191
|
+
|
|
1192
|
+
/**
|
|
1193
|
+
* Persist a compact machine report so `--failed` (and post-hoc analysis) can
|
|
1194
|
+
* re-run exactly the journeys that were red. Best-effort: a write failure must
|
|
1195
|
+
* never fail an otherwise valid run.
|
|
1196
|
+
*/
|
|
1197
|
+
function writeReport(reportPath, report) {
|
|
1198
|
+
try {
|
|
1199
|
+
fs.mkdirSync(path.dirname(reportPath), { recursive: true });
|
|
1200
|
+
fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
|
|
1201
|
+
} catch (error) {
|
|
1202
|
+
console.warn(` ! could not write run report (${reportPath}): ${error.message}`);
|
|
1203
|
+
}
|
|
1204
|
+
}
|
|
1205
|
+
|
|
1206
|
+
async function main() {
|
|
1207
|
+
const options = parseArgs(process.argv.slice(2));
|
|
1208
|
+
|
|
1209
|
+
if (options.help) {
|
|
1210
|
+
console.log(usage());
|
|
1211
|
+
process.exit(0);
|
|
1212
|
+
}
|
|
1213
|
+
|
|
1214
|
+
if (options.unknown) {
|
|
1215
|
+
console.error(`Unknown argument: ${options.unknown}`);
|
|
1216
|
+
console.error(usage());
|
|
1217
|
+
process.exit(2);
|
|
1218
|
+
}
|
|
1219
|
+
|
|
1220
|
+
// `--preflight` is a standalone check: it needs no flows and no seeded DB, and
|
|
1221
|
+
// must run before any of that is required.
|
|
1222
|
+
if (options.preflight) {
|
|
1223
|
+
process.exit(runPreflight(options));
|
|
1224
|
+
}
|
|
1225
|
+
|
|
1226
|
+
if (!options.flows && !options.failed) {
|
|
1227
|
+
console.log(usage());
|
|
1228
|
+
process.exit(0);
|
|
1229
|
+
}
|
|
1230
|
+
|
|
1231
|
+
assertDevDatabase();
|
|
1232
|
+
|
|
1233
|
+
const stepsByFlow = parseJourneySteps(MATRIX_FILE);
|
|
1234
|
+
|
|
1235
|
+
let flowFiles;
|
|
1236
|
+
if (options.failed) {
|
|
1237
|
+
const reportFile = resolveFailedReport(options.report);
|
|
1238
|
+
if (!reportFile) {
|
|
1239
|
+
console.log(
|
|
1240
|
+
'No previous run report found (checked this checkout, the main checkout, and sibling worktrees) — nothing to re-run.'
|
|
1241
|
+
);
|
|
1242
|
+
process.exit(0);
|
|
1243
|
+
}
|
|
1244
|
+
const failedNames = readFailedFlowNames(reportFile);
|
|
1245
|
+
if (failedNames.length === 0) {
|
|
1246
|
+
console.log(`No failed journeys recorded in ${reportFile} — nothing to re-run.`);
|
|
1247
|
+
process.exit(0);
|
|
1248
|
+
}
|
|
1249
|
+
flowFiles = failedNames.map((name) => path.join(FLOWS_DIR, name.endsWith('.yaml') ? name : `${name}.yaml`));
|
|
1250
|
+
console.log(`Re-running ${flowFiles.length} failed journey(s) from ${reportFile}.`);
|
|
1251
|
+
} else {
|
|
1252
|
+
flowFiles = resolveFlowFiles(options.flows) || [];
|
|
1253
|
+
}
|
|
1254
|
+
|
|
1255
|
+
const missing = flowFiles.filter((file) => !fs.existsSync(file));
|
|
1256
|
+
if (flowFiles.length === 0 || missing.length > 0) {
|
|
1257
|
+
missing.forEach((file) => console.error(`FAIL — flow file not found: ${path.relative(options.root, file)}`));
|
|
1258
|
+
if (flowFiles.length === 0) console.error('FAIL — no flows selected (use --flows <a,b,...|all>).');
|
|
1259
|
+
process.exit(2);
|
|
1260
|
+
}
|
|
1261
|
+
// A `firstLogin` journey `clearState`s the app (wiping every actor's on-device
|
|
1262
|
+
// onboarding flag); run it first so the rest of the run reuses intact sessions.
|
|
1263
|
+
// With `--reuse-session`, additionally regroup by actor so a warm run batches
|
|
1264
|
+
// an actor's setup-free journeys into one invocation instead of interleaving
|
|
1265
|
+
// them with standalone flows (the F-296 run batched 2 of 26).
|
|
1266
|
+
flowFiles = options.reuseSession
|
|
1267
|
+
? orderForSessionReuse(flowFiles, stepsByFlow)
|
|
1268
|
+
: orderFirstLoginFirst(flowFiles, stepsByFlow);
|
|
1269
|
+
|
|
1270
|
+
printSequence(options);
|
|
1271
|
+
printDeclaredSteps(resolveDeclaredSteps(flowFiles, stepsByFlow));
|
|
1272
|
+
|
|
1273
|
+
if (!resolveMaestro()) {
|
|
1274
|
+
console.error('FAIL — Maestro CLI is not on PATH and not at ~/.maestro/bin/maestro.');
|
|
1275
|
+
console.error(' Install it with: curl -Ls "https://get.maestro.mobile.dev" | bash');
|
|
1276
|
+
console.error(' (requires JDK 17+), or point MOBILE_E2E_MAESTRO at the binary. Then re-run this command.');
|
|
1277
|
+
process.exit(1);
|
|
1278
|
+
}
|
|
1279
|
+
|
|
1280
|
+
if (options.platform === 'ios') {
|
|
1281
|
+
// iOS Simulator: resolve the UDID and target `maestro test --device`. adb
|
|
1282
|
+
// is Android-only, so the adb preflight is skipped entirely.
|
|
1283
|
+
options.udid = resolveIosUdid(options);
|
|
1284
|
+
console.log(`target: ios simulator ${options.udid}`);
|
|
1285
|
+
} else {
|
|
1286
|
+
preflightAdb();
|
|
1287
|
+
}
|
|
1288
|
+
|
|
1289
|
+
// A subset selection (--failed, or an explicit list rather than `all`) may skip
|
|
1290
|
+
// the full seed when the seed fingerprint is unchanged; a full matrix run
|
|
1291
|
+
// always reseeds. See runReset.
|
|
1292
|
+
const subset = options.failed || (typeof options.flows === 'string' && options.flows.trim() !== 'all');
|
|
1293
|
+
runReset(options, { subset });
|
|
1294
|
+
|
|
1295
|
+
const records = buildFlowRecords(flowFiles, stepsByFlow);
|
|
1296
|
+
// Actor is only needed to decide session reuse/batching; a cold per-flow run
|
|
1297
|
+
// does not use it, so a project that has not adopted `actor:` yet still runs.
|
|
1298
|
+
if (options.reuseSession) {
|
|
1299
|
+
const missingActor = records.filter((record) => !record.actor);
|
|
1300
|
+
if (missingActor.length > 0) {
|
|
1301
|
+
console.error(`FAIL — --reuse-session needs an actor for: ${missingActor.map((record) => record.name).join(', ')}`);
|
|
1302
|
+
console.error(' Add `actor: "<phone>"` to the journey in flows/matrix.yaml, or set local.json `defaultActor`.');
|
|
1303
|
+
process.exit(2);
|
|
1304
|
+
}
|
|
1305
|
+
}
|
|
1306
|
+
const invocations = planInvocations(records, options.reuseSession);
|
|
1307
|
+
const startedAt = new Date().toISOString();
|
|
1308
|
+
const results = [];
|
|
1309
|
+
|
|
1310
|
+
// Machine-readable progress bus (see job-events.js): the notifier plugin and
|
|
1311
|
+
// `--wait` consume it so the agent never has to poll/guess.
|
|
1312
|
+
const eventsPath = process.env.MOBILE_E2E_EVENTS || null;
|
|
1313
|
+
let flowIndex = 0;
|
|
1314
|
+
jobEvents.appendEvent(eventsPath, {
|
|
1315
|
+
type: 'matrix_start',
|
|
1316
|
+
at: startedAt,
|
|
1317
|
+
mode: options.reuseSession ? 'reuse-session' : 'per-flow',
|
|
1318
|
+
total: records.length,
|
|
1319
|
+
});
|
|
1320
|
+
|
|
1321
|
+
const signatureCounts = new Map();
|
|
1322
|
+
const signatureFlows = new Map();
|
|
1323
|
+
let anyFailed = false;
|
|
1324
|
+
let stopped = false;
|
|
1325
|
+
let totalInvocationMs = 0;
|
|
1326
|
+
|
|
1327
|
+
for (let index = 0; index < invocations.length && !stopped; index += 1) {
|
|
1328
|
+
const invocation = invocations[index];
|
|
1329
|
+
const names = invocation.records.map((record) => record.name);
|
|
1330
|
+
const label = names.join(', ');
|
|
1331
|
+
|
|
1332
|
+
// Declared setup steps run immediately before the invocation. A batch is
|
|
1333
|
+
// normally setup-free (resolving to none); an explicit `batchSetup: true`
|
|
1334
|
+
// batch runs every member's setup here, in manifest order, before the one
|
|
1335
|
+
// shared `maestro test`. Oracles stay scoped to a passing single flow.
|
|
1336
|
+
const scoped = resolveDeclaredSteps(invocation.records.map((record) => record.file), stepsByFlow);
|
|
1337
|
+
runDeclaredSteps(scoped.setups, 'setup');
|
|
1338
|
+
|
|
1339
|
+
console.log(`\nRunning ${invocation.records.length > 1 ? 'flows' : 'flow'} (${index + 1}/${invocations.length}): ${label} [actor=${invocation.actor}${invocation.switchUser ? ', switch' : ', reuse'}]`);
|
|
1340
|
+
for (const record of invocation.records) {
|
|
1341
|
+
jobEvents.appendEvent(eventsPath, {
|
|
1342
|
+
type: 'flow_start',
|
|
1343
|
+
at: new Date().toISOString(),
|
|
1344
|
+
name: record.name,
|
|
1345
|
+
actor: record.actor,
|
|
1346
|
+
index: ++flowIndex,
|
|
1347
|
+
total: records.length,
|
|
1348
|
+
});
|
|
1349
|
+
}
|
|
1350
|
+
const invocationStart = Date.now();
|
|
1351
|
+
// Liveness while the invocation runs: a heartbeat event every HEARTBEAT_MS
|
|
1352
|
+
// (so a long batch is visibly ALIVE, not frozen) and a one-shot
|
|
1353
|
+
// `invocation_stalled` when the child has produced no output for STALL_MS
|
|
1354
|
+
// (so a real hang is named instead of guessed at).
|
|
1355
|
+
let lastOutputAt = invocationStart;
|
|
1356
|
+
let stallAnnounced = false;
|
|
1357
|
+
const heartbeat = setInterval(() => {
|
|
1358
|
+
const now = Date.now();
|
|
1359
|
+
const msSinceOutput = now - lastOutputAt;
|
|
1360
|
+
jobEvents.appendEvent(eventsPath, {
|
|
1361
|
+
type: 'invocation_heartbeat',
|
|
1362
|
+
at: new Date().toISOString(),
|
|
1363
|
+
index: index + 1,
|
|
1364
|
+
total: invocations.length,
|
|
1365
|
+
flows: names,
|
|
1366
|
+
actor: invocation.actor,
|
|
1367
|
+
elapsedMs: now - invocationStart,
|
|
1368
|
+
msSinceOutput,
|
|
1369
|
+
});
|
|
1370
|
+
if (STALL_MS > 0 && msSinceOutput >= STALL_MS && !stallAnnounced) {
|
|
1371
|
+
stallAnnounced = true;
|
|
1372
|
+
jobEvents.appendEvent(eventsPath, {
|
|
1373
|
+
type: 'invocation_stalled',
|
|
1374
|
+
at: new Date().toISOString(),
|
|
1375
|
+
index: index + 1,
|
|
1376
|
+
total: invocations.length,
|
|
1377
|
+
flows: names,
|
|
1378
|
+
actor: invocation.actor,
|
|
1379
|
+
elapsedMs: now - invocationStart,
|
|
1380
|
+
msSinceOutput,
|
|
1381
|
+
});
|
|
1382
|
+
console.error(
|
|
1383
|
+
`\nWARNING — invocation ${index + 1}/${invocations.length} produced no output for ` +
|
|
1384
|
+
`${Math.round(msSinceOutput / 1000)}s (possible hang): ${label}`,
|
|
1385
|
+
);
|
|
1386
|
+
}
|
|
1387
|
+
if (msSinceOutput < STALL_MS) stallAnnounced = false;
|
|
1388
|
+
}, HEARTBEAT_MS);
|
|
1389
|
+
|
|
1390
|
+
let invocationResult;
|
|
1391
|
+
try {
|
|
1392
|
+
invocationResult = await runMaestroFlows(
|
|
1393
|
+
invocation.records.map((record) => record.file),
|
|
1394
|
+
options,
|
|
1395
|
+
{ switchUser: invocation.switchUser, actor: invocation.actor },
|
|
1396
|
+
() => {
|
|
1397
|
+
lastOutputAt = Date.now();
|
|
1398
|
+
},
|
|
1399
|
+
);
|
|
1400
|
+
} finally {
|
|
1401
|
+
clearInterval(heartbeat);
|
|
1402
|
+
}
|
|
1403
|
+
const { status, output } = invocationResult;
|
|
1404
|
+
const invocationMs = Date.now() - invocationStart;
|
|
1405
|
+
totalInvocationMs += invocationMs;
|
|
1406
|
+
const failedFlows = parseFailedFlows(output);
|
|
1407
|
+
const flowDurations = parseFlowDurations(output);
|
|
1408
|
+
|
|
1409
|
+
// Oracles run only for a passing single-flow invocation.
|
|
1410
|
+
if (invocation.records.length === 1 && status === 0) {
|
|
1411
|
+
runDeclaredSteps(scoped.oracles, 'oracle');
|
|
1412
|
+
}
|
|
1413
|
+
|
|
1414
|
+
// A flow passes when Maestro did not name it as failed; when the invocation
|
|
1415
|
+
// failed but produced no `[Failed]` summary (crash/parse error), fall back to
|
|
1416
|
+
// the single-flow reason extractor so the failure is still attributed.
|
|
1417
|
+
// Matching is on the normalised flow key (extension-free) so a batched
|
|
1418
|
+
// failure is attributed to its journey instead of silently passing.
|
|
1419
|
+
const failedRecords = invocation.records.filter((record) => {
|
|
1420
|
+
const key = flowKey(record.name);
|
|
1421
|
+
const pass = failedFlows.size > 0 ? !failedFlows.has(key) : status === 0;
|
|
1422
|
+
const reason = pass ? null : failedFlows.get(key) || extractFailureReason(output, record.name);
|
|
1423
|
+
// Maestro's summary carries per-flow durations in a batch; a single-flow
|
|
1424
|
+
// invocation has no summary line, so its wall clock is the duration.
|
|
1425
|
+
const durationMs = flowDurations.has(key)
|
|
1426
|
+
? flowDurations.get(key)
|
|
1427
|
+
: invocation.records.length === 1
|
|
1428
|
+
? invocationMs
|
|
1429
|
+
: null;
|
|
1430
|
+
results.push({ name: record.name, actor: record.actor, status: pass ? 'pass' : 'fail', reason, durationMs });
|
|
1431
|
+
jobEvents.appendEvent(eventsPath, {
|
|
1432
|
+
type: 'flow_result',
|
|
1433
|
+
at: new Date().toISOString(),
|
|
1434
|
+
name: record.name,
|
|
1435
|
+
actor: record.actor,
|
|
1436
|
+
status: pass ? 'pass' : 'fail',
|
|
1437
|
+
reason,
|
|
1438
|
+
durationMs,
|
|
1439
|
+
});
|
|
1440
|
+
return !pass;
|
|
1441
|
+
});
|
|
1442
|
+
|
|
1443
|
+
if (failedRecords.length > 0) {
|
|
1444
|
+
anyFailed = true;
|
|
1445
|
+
failedRecords.forEach((record) => {
|
|
1446
|
+
const result = results.find((entry) => entry.name === record.name);
|
|
1447
|
+
const reason = (result && result.reason) || `flow ${record.name} failed`;
|
|
1448
|
+
const signature = normaliseFailureReason(reason, record.name);
|
|
1449
|
+
const count = (signatureCounts.get(signature) || 0) + 1;
|
|
1450
|
+
signatureCounts.set(signature, count);
|
|
1451
|
+
if (!signatureFlows.has(signature)) signatureFlows.set(signature, []);
|
|
1452
|
+
signatureFlows.get(signature).push(record.name);
|
|
1453
|
+
console.error(`\nFAIL — ${record.name} exited ${status}: ${signature}`);
|
|
1454
|
+
if (options.maxSameReason > 0 && count >= options.maxSameReason) {
|
|
1455
|
+
const executed = new Set(results.map((result) => result.name));
|
|
1456
|
+
const skipped = records.map((record) => record.name).filter((name) => !executed.has(name));
|
|
1457
|
+
reportFailFast(signature, signatureFlows.get(signature), skipped);
|
|
1458
|
+
jobEvents.appendEvent(eventsPath, {
|
|
1459
|
+
type: 'fail_fast',
|
|
1460
|
+
at: new Date().toISOString(),
|
|
1461
|
+
count,
|
|
1462
|
+
signature,
|
|
1463
|
+
flows: signatureFlows.get(signature),
|
|
1464
|
+
skipped,
|
|
1465
|
+
});
|
|
1466
|
+
stopped = true;
|
|
1467
|
+
}
|
|
1468
|
+
});
|
|
1469
|
+
}
|
|
1470
|
+
if (stopped) break;
|
|
1471
|
+
}
|
|
1472
|
+
|
|
1473
|
+
const finishedAt = new Date().toISOString();
|
|
1474
|
+
const flowsWithDurations = results.filter((result) => typeof result.durationMs === 'number');
|
|
1475
|
+
const slowest = [...flowsWithDurations]
|
|
1476
|
+
.sort((a, b) => b.durationMs - a.durationMs)
|
|
1477
|
+
.slice(0, 5)
|
|
1478
|
+
.map((result) => `${result.name}=${Math.round(result.durationMs / 1000)}s`);
|
|
1479
|
+
writeReport(REPORT_FILE, {
|
|
1480
|
+
startedAt,
|
|
1481
|
+
finishedAt,
|
|
1482
|
+
mode: options.reuseSession ? 'reuse-session' : 'per-flow',
|
|
1483
|
+
invocationCount: invocations.length,
|
|
1484
|
+
matrixDurationMs: Date.parse(finishedAt) - Date.parse(startedAt),
|
|
1485
|
+
invocationDurationMs: totalInvocationMs,
|
|
1486
|
+
flows: results,
|
|
1487
|
+
});
|
|
1488
|
+
if (slowest.length > 0) {
|
|
1489
|
+
console.log(`\nSlowest journeys: ${slowest.join(', ')}`);
|
|
1490
|
+
}
|
|
1491
|
+
|
|
1492
|
+
jobEvents.appendEvent(eventsPath, {
|
|
1493
|
+
type: 'matrix_done',
|
|
1494
|
+
at: finishedAt,
|
|
1495
|
+
total: records.length,
|
|
1496
|
+
passed: results.filter((result) => result.status === 'pass').length,
|
|
1497
|
+
failed: results.filter((result) => result.status !== 'pass').length,
|
|
1498
|
+
stopped,
|
|
1499
|
+
report: REPORT_FILE,
|
|
1500
|
+
});
|
|
1501
|
+
|
|
1502
|
+
if (anyFailed) process.exit(1);
|
|
1503
|
+
process.exit(0);
|
|
1504
|
+
}
|
|
1505
|
+
|
|
1506
|
+
if (require.main === module) {
|
|
1507
|
+
main().catch((err) => {
|
|
1508
|
+
console.error(`FAIL — ${err && err.stack ? err.stack : err}`);
|
|
1509
|
+
process.exit(1);
|
|
1510
|
+
});
|
|
1511
|
+
}
|
|
1512
|
+
|
|
1513
|
+
module.exports = {
|
|
1514
|
+
parseArgs,
|
|
1515
|
+
resolveMaestro,
|
|
1516
|
+
resolveIosUdid,
|
|
1517
|
+
normalizePlatform,
|
|
1518
|
+
runMaestroFlows,
|
|
1519
|
+
resolveFlowFiles,
|
|
1520
|
+
resolveFailedReport,
|
|
1521
|
+
readFailedFlowNames,
|
|
1522
|
+
runReset,
|
|
1523
|
+
resolveDevDatabaseUrl,
|
|
1524
|
+
seedFingerprint,
|
|
1525
|
+
shouldAutoNoSeed,
|
|
1526
|
+
normaliseFailureReason,
|
|
1527
|
+
extractFailureReason,
|
|
1528
|
+
suggestFix,
|
|
1529
|
+
flowKey,
|
|
1530
|
+
parseFailedFlows,
|
|
1531
|
+
parseFlowDurations,
|
|
1532
|
+
parseMaestroDuration,
|
|
1533
|
+
setupClearsAppState,
|
|
1534
|
+
isSetupGroupable,
|
|
1535
|
+
parseJourneySteps,
|
|
1536
|
+
buildFlowRecords,
|
|
1537
|
+
orderFirstLoginFirst,
|
|
1538
|
+
orderForSessionReuse,
|
|
1539
|
+
planInvocations,
|
|
1540
|
+
toolPathDirs,
|
|
1541
|
+
toolEnv,
|
|
1542
|
+
runPreflight,
|
|
1543
|
+
};
|