Skip to content

Replay and E2E testing

Record a session as an .ad script, then run it again with replay or run a folder of scripts as an E2E suite with test.

replay has a 60-second wall-clock budget within a 90-second client timeout. Use replay workflow.ad --timeout 300000 for a five-minute operation budget and a five-minute, 30-second client timeout. At the budget, the running step receives the same cancellation as a canceled request. When it settles, a failed replay includes details.reason: daemon_request_timeout and details.timeoutMs. The daemon and other sessions stay available if it responds to the client. An authored close may already have ended its session. A failed replay keeps the failing script path and line. A replay that completes every step returns success even if it settles shortly after the deadline. Cancellation does not prove that native device work has stopped. If a step ignores cancellation beyond the remaining 30 seconds, the client may report a transport timeout. For a daemon that does not respond, the client’s existing liveness check can reset it. Direct test runs keep their own timeout behavior.

If a resource step cannot run within replay’s budget, the error includes details.reason: bounded_composite_resource_unsupported, details.shape, details.dispatched: no for that step, and details.standaloneCommandName for a known public command. This can affect perf, audio, record, trace, and some logs operations. It also affects close when it would dispose owned resources or release a provider lease, and acquisition that would recover another session’s durable resources. Opening another app in the same session keeps its owned resource handles. An Android test IME alone is restored by authored close, even when restoration settles after the remaining replay time. A failed restore on a session that holds a device claim keeps the session and its claim; inspect the device, then retry close with the same options, leaving out --save-script once the script is published. A session without a claim is retired. The name is not a complete command. Inspect the failed script path and line, then run that original operation separately with its original arguments and options, the same --session value, and the same private CLI context. If steps remain and the report offers resume.alternateFrom, use it with planDigest after completing the refused step directly. resume.from retries the same bounded step and refuses it again. A final unrecorded logs or audio step leaves no replay tail to resume. Inspect completed steps before retrying; earlier steps may have changed the app. A nested test with an attempt timeout or --record-video is refused before its first attempt. Direct test retains its own timeout behavior. If a nested test reaches a bounded resource refusal, it stops after that attempt even when you configured retries. Other test failures can still retry. An authored .ad command without a resource classification fails closed with details.shape: <command>:unclassified and the same original-input guidance.

To run Maestro YAML flows or export .ad scripts to Maestro YAML, see Run Maestro flows.

How it works

You work in two passes:

  1. Explore: discover elements and act on refs (snapshot -> click @e.. / fill @e..) while recording.
  2. Replay: run the recorded .ad script with replay for a deterministic run.

Record a replay script

Pass --save-script to open. When you close the session, the script is written:

Terminal window
agent-device open Settings --platform ios --session e2e --save-script
agent-device snapshot -i --session e2e
agent-device click @e13 --session e2e
agent-device close --session e2e

By default, the script goes to:

~/.agent-device/sessions/<session>-<timestamp>.ad

Each recorded element step writes its target as a selector. When the element’s id is unique on the recorded screen, the step writes only that id, for example press 'id="submit"'. Otherwise, it writes alternatives such as role and label, joined with ||, for example press 'role="button" label="Submit" || label="Submit"'.

To choose the output file, pass a path to --save-script:

Terminal window
agent-device open Settings --platform ios --session e2e --save-script ./workflows/e2e-settings.ad
  • The path has to end in a file name. A path ending in ., .., or a bare ~ or root is refused before anything is created, because it names a directory. A trailing / after a file name still writes that file.
  • On Windows, use a drive-letter path (C:\recordings\journey.ad) or a \\server\share path. A path relative to the current drive (\journey.ad) and an extended-length path (\\?\...) are refused on purpose, and so is a relative or ~/ path whose working directory or home has one of those forms. Paths in a pipe, IPC$ or mailslot share are refused too.
  • Missing parent directories are created, one at a time, and only once the directories above them pass the check below. Each new directory is created at mode 0700, whatever your umask, because it holds private recordings. A destination refused before any directory is created leaves nothing behind, even where its parent was missing; a refusal after creation starts can leave the empty directories already created. A path that steps back out of a directory that does not exist yet (private/missing/../../shared/recordings) is refused rather than created into existence: the directories it names would be built by a rule that never judged them. A recording’s script file, local or remote, is created at exactly mode 0600, so its own permissions open it to nobody but you. What those permissions do not settle for you is listed under the limits below.
  • Every directory the write travels through must be one that no other local user can change, with one exception: the members of the group of a directory you own and left group-writable can change it. Each directory must be owned by you or by root, and apart from that exception its permissions must prevent other users from modifying entries in it. Another local user who owns such a directory, or who can write in it, can replace a directory on the path or leave a symbolic link there, and the script then lands where they choose.
  • The check follows the path the way the system does, one name at a time, and judges every directory it looks a name up in. So a plain directory that is open to others cannot hide a link into a private destination (rec -> shared/relay/sub, where shared/relay is itself a link), and a link inside a link cannot hide the directory it crosses. A link written as ln -s ../team/rec rec is followed from the directory that holds it, and a .. inside it is applied one step at a time. A .. in the path you typed is applied to the directory the walk actually reached, not to the text: where work is a link, work/../x lands beside the link’s target, and that is the directory judged. A relative path such as ./workflows/journey.ad is expanded against your working directory first, and the whole chain from the root is then checked, so a working directory that sits in ground others can write is refused too. The file is written into that same resolved directory, temp file included, so nothing is staged in a directory the check never reached. Where the check cannot reach the directory your path names, because a name inside it does not exist, the save is refused instead of writing beside the closest directory it did reach. Following more links than the system allows is refused rather than trusted.
  • Every symbolic link the path follows is checked wherever it leads, at any depth, not only the ones you typed. A link is refused if another user could have placed it, or could replace it: in a directory where others may add entries, only a link you or root own, held in place by the sticky bit, is trusted. A group-writable directory you own is the exception: a link in it is followed, whoever placed it. Its own permission bits are not consulted: on Linux every link reports the same mode. Root-owned system links such as macOS /tmp and /var keep working.
  • A directory you or root own may still be passed through when it carries the sticky bit (chmod +t) and is open to others, because that bit stops anyone but an entry’s owner or root from replacing an entry: macOS /tmp works this way. A sticky directory owned by somebody else is refused — both bits shield other users from its owner, not the owner from you. The script is never created inside a directory others may add entries to: there, anyone could create your file’s name first. A group-writable directory that you own is accepted unless you are root or it is also world-writable, so a checkout created under umask 002, where every directory is 0775, works as it is. Its group is your responsibility: the members can replace a directory on the path, leave a link there, or create your file’s name first. Check which group it is with ls -ld, because a parent directory can pass its own group on. A group-writable directory that root owns is refused unless it is sticky and only passed through, because its members could do the same. Save under a directory you own instead: only root can close such a directory to its group.
  • Limits. The checks read owners, permission bits and link shape, and four things sit outside them. They are POSIX checks: on Windows the walk does not run at all, so owners, permission bits and link shape are not read there and a mode such as 0600 carries no Windows meaning — Windows access comes from the ACL of the directory you chose, which is outside this rule. An access control list is consulted before the permission bits, so a directory at 0700 can still grant everyone write through an ACL, and a file at 0600 can still grant everyone read; the checks do not read ACLs. On a network mount (NFS, SMB, FUSE), ownership and mode are whatever the server answers, and the user ids there are usually not the ones on this machine. A mount can also appear over a checked directory. So these checks mean that no other local user, apart from the group members of a group-writable directory you own, can steer where the recording is written on a local filesystem without ACLs on that path; they are not a promise that nobody else can read the file. On a host like that, choose a directory only you can write.
  • A refused destination names the directory at fault. A local close fails and keeps its bytes. A remote recording keeps its success and reports script_ancestor_untrusted as the scriptDeliveryFailure cause, and the next recorded action or close repeats the refusal. Choose a directory you own that only you can write.
  • On a local session the check guards every route that writes to a caller-named destination, not only the one you typed a path to: open --save-script, the close of a session, session save-script, replay --save-script and the <name>.healed.ad sibling it writes when you name no output for it, and --save-script in a batch step. Where no path is named at all, the daemon writes its own default location the way it always has, without this check.
  • With a local daemon, closing an ordinary recording writes the script on the daemon host. Relative paths resolve from the daemon’s working directory. If you omit the path, the file goes in the daemon state’s sessions directory. Use session save-script while the session is open to get the output path from the CLI. When a close writes a healed replay, the Node SDK close result includes savedScript. On macOS and Linux, a path you name resolves parent symbolic links.
  • With a remote daemon, outside a macOS app lease, the path is on your machine. The file appears when open returns, and each later recorded action in the session replaces it with the recording so far. close writes the final script there. If a process that does not share this client’s state directory closes the session, the file keeps the version from the last action.
  • Check the chosen destination after a remote open returns. The client adds savedScript and its own delivery warnings when it materializes a remote response. A raw HTTP RPC response carries no savedScript, and only the warning for a script the daemon could not write. They reach the result of open, of a recorded action and of close, and the Node SDK close result; at the default level the CLI open and close JSON output and the Node SDK open result do not carry savedScript, while close --level full prints the full close result, savedScript included. A successful batch carries it only when its response also lists the script artifact. A batch answered only through its delivery receipt, and a failed batch, carry no savedScript. For a version saved fresh, on macOS and Linux that path resolves symbolic links, and on Windows it can include a junction. A repeated version reports the stored absolute destination instead: relative and ~ paths resolved and trailing separators removed, with parent links not resolved.
  • While the client still holds the recording’s active record, an equal or older version is reported with that stored destination, without fetching it or checking the file again, and with no warning. If that file is missing while the session is still recording, the next recorded action or close writes the full recording to the destination again. A final close ends the recording. If that delivery fails, later actions cannot recover the file: record again to the original open destination: reuse your original open command, with its app, URL and device arguments, with --save-script=<path> --force; a bare --save-script would pick a new file name. The hint of a refusal for an existing file names those arguments with the path quoted for a POSIX shell (in PowerShell, write an apostrophe in the path as two apostrophes inside single quotes); for a path with a newline or another C0 or C1 control character, it names <path> instead.
  • A bare remote open --save-script writes recording-<timestamp>.ad in your working directory.
  • If the probe finds an existing entry, open fails unless you pass --force. If the probe cannot read the entry or an entry appears later, open can succeed. Without --force, the first delivery creates the file exclusively, preserving any existing entry. If delivery cannot save the script, the result includes scriptDeliveryFailure and a warning. With --force, the first delivery can replace the entry. After the first save, the session replaces the file on each update.
  • Remote session save-script, close --save-script, replay --save-script, and --save-script in batch steps are refused.
  • A remote batch updates your file once with the recording from its completed steps, including the final script when a step closes the session. If a step fails, the batch keeps that error and delivers the recording from earlier completed steps. A delivery failure adds scriptDeliveryFailure and a warning; your file may still hold the previous version.
  • The remote daemon must report the script-artifacts capability in its /health response. Through a proxy, the upstream daemon’s health response must report it. Otherwise open --save-script fails before the app opens.
  • For a bare file name that could be read as another argument, use --save-script=workflow.ad or a path-like value such as ./workflow.ad.

.ad line grammar

A .ad line is the CLI spelling of one command: <command> [positional ...] [flag ...]. Whitespace separates tokens, so a value with a space needs quotes.

Terminal window
open "com.example.app" --relaunch
scroll down --until 'id="far-button"'
press id="far-button"
wait 'label="Order summary"' 5000
close
  • A token quoted with " or ' is one argument. Single quotes keep a " literal, so 'id="far-button"' and "id=\"far-button\"" are the same selector — write whichever matches how you typed the command at the shell.
  • Values in double quotes are JSON strings, so escape \\, \", \t, and \n. Values in single quotes are literal, as at the shell: a backslash keeps its own character, and the only escape is \' for an apostrophe.
  • A script line keeps only the flags that command records; CLI-only spellings and per-request options are not part of a step. The common flags a script does not carry are --settle, --verify, scroll --pixels/--duration-ms, and the device-selection flags (--platform, --serial, --device).
  • help <command> prints the flags each command accepts. help scripting prints this grammar.

To reach an off-screen element, use a stop condition rather than a fixed scroll amount. A fixed amount passes on one screen size and fails on another:

Terminal window
# repeats until the element is on screen
scroll down --until 'id="checkout-submit"'
# one gesture, viewport-relative
scroll down 0.8
# run to the end of the content
scroll bottom

A # only starts a comment at the beginning of a line. A scroll line carries --until and keeps its distance as a positional (scroll down 0.8 --until <selector>). wait carries --raw, --depth <n>, and --scope <selector|@ref> to choose the capture its target is read from. Scripts use only these long spellings: the -d/-s CLI aliases are not flags in a script, so a hand-written line such as wait text -s so funny still waits for that literal text.

Run replay

Terminal window
agent-device replay ~/.agent-device/sessions/e2e-2026-02-09T12-00-00-000Z.ad --session e2e-run
  • Replay reads .ad scripts.

  • The CLI reads script paths on your machine and sends the script, with the Maestro runFlow includes it can resolve and read, to the daemon. An include it cannot read is left out, and the run fails if it reaches that include. The same replay or test command works against a local or a remote daemon without copying files. A script that doesn’t exist on your machine fails at once, naming the path you typed.

  • A script that does not end in close leaves its session open. For a script that does end in close, pass --keep-session to skip only that final action and keep working in the same session:

    Terminal window
    agent-device replay ./checkout.ad --session e2e-run --keep-session
    agent-device snapshot -i --session e2e-run

    Earlier close actions still run. test does not accept the flag because each suite attempt cleans up its own session.

  • press, click, and longpress steps do not wait for a missing target to appear. If a screen needs time to load, add an explicit wait before the interaction, such as wait 'label="Continue"' 5000. Covered, off-screen, and ambiguous targets fail as they do in live commands.

  • When the target is missing, replay stops with REPLAY_DIVERGENCE. For a step recorded with a target annotation (the # agent-device:target-v1 line above it), error.details.divergence.kind is selector-miss and the step is never sent. For a step without an annotation, error.details.reason is selector_not_found, as for a live command.

  • A step whose read names one element (is with a predicate other than exists/absent, or get attrs) that reaches dispatch with an ambiguous selector fails with AMBIGUOUS_MATCH as the divergence cause — the same code the live command reports, so an ambiguous recorded screen is not replayed as a missing one. An annotated step can also stop earlier, before the command runs: when pre-dispatch target binding cannot confirm the recorded identity (its identity set has more than one member with no sibling or viewport signal isolating one, or no fresh snapshot can be captured to verify against), the divergence cause is IDENTITY_UNVERIFIABLE instead. Both codes say the recorded screen changed; only AMBIGUOUS_MATCH proves your selector matched more than one element.

Run a lightweight .ad suite

Terminal window
agent-device test ./workflows
agent-device test "./workflows/**/*.ad" --platform android
agent-device test ./workflows --timeout 60000 --retries 1
agent-device test ./workflows --artifacts-dir ./tmp/agent-device-artifacts
agent-device test ./workflows --reporter default --reporter junit:./tmp/junit.xml
  • test discovers .ad files from files, directories, or globs and runs them serially.
  • Quote relative globs to expand them on the caller from its working directory, including when the directory name contains glob characters such as [ or {. A missing file input without glob characters reports an error.
  • The context platform=... header inside each .ad file decides which platform that file runs on.
  • --platform filters which files run; with a filter, files without a context platform= header are skipped. When filtering leaves no runnable sources, the no-match error reports how many sources were skipped for having no context platform= header versus how many declared another platform. Add the header to run a file under a filter, or omit --platform and let the selected device decide.
  • Set context timeout=... and context retries=... per script; CLI flags override them. Retries are capped at 3, and duplicate keys in the context header fail fast instead of silently overriding each other.
  • By default, suite artifacts are written under .agent-device/test-artifacts/<run-id>/.... Each attempt writes replay.ad, result.txt, and replay-timing.ndjson. Failed attempts also keep copied logs and artifact files when the replay produced them.
  • Copied diagnostic artifacts receive numbered filenames when their names collide with another artifact, a replay source, timing trace, or attempt manifest. result.txt lists the retained names in copiedArtifacts.
  • replay-timing.ndjson records attempt, cleanup, and per-step start/stop events with durations. Upload it from CI even for passing runs when comparing local and CI performance.
  • When an attempt hits its timeout, it is marked failed and the replay gets a short grace period to stop before the session is cleaned up.
  • The default text reporter streams live progress on stderr while a suite runs, then prints the final summary, failed tests, and passed-on-retry flaky tests. Use --verbose to include step traces in completed-test progress output.
  • The default reporter prints a Warnings: section after the summary when any test accumulated composable warnings — for example a Maestro step with optional: true that was skipped — whether that test passed or failed. A failing replay run repeats the warnings it accumulated as Warning: lines after the error. --json carries the same strings in each test result’s warnings array.
  • --reporter is repeatable. Built-ins are default for the console summary and junit:<path> for JUnit XML. Passing any explicit reporter list replaces the implicit default reporter, so include --reporter default when you also want terminal output. --report-junit <path> is an alias for --reporter junit:<path>.
  • JUnit reports preserve legal Unicode and whitespace, and replace characters forbidden by XML 1.0 (such as terminal ESC or NUL) with U+FFFD (�) so CI parsers can read the report. JSON and other reporters retain the original suite values.
  • When --fail-fast and retries are both set, the current test still consumes its retries before the suite stops.

Custom test reporters

A custom reporter formats suite output. It runs in the local CLI process, not the daemon, and can render both live progress and the final result.

Terminal window
agent-device test ./workflows --reporter ./scripts/replay-reporter.mjs

A reporter module can export a reporter object, reporter, createReporter, or a default factory. Factories receive a load context. Reporter hooks receive replay test objects and an IO context with stdout and stderr streams:

scripts/replay-reporter.mjs
import fs from 'node:fs';
import path from 'node:path';
export default function createReporter(loadContext) {
return {
name: 'summary-file',
onTestStep(test, context) {
context.stderr.write(`running ${test.file} ${test.stepIndex}/${test.stepTotal}\n`);
},
onSuiteEnd(suite, context) {
context.stdout.write(`finished ${suite.total} tests\n`);
fs.mkdirSync('./tmp', { recursive: true });
fs.writeFileSync(
path.join('./tmp', 'report.txt'),
JSON.stringify(
{
total: suite.total,
passed: suite.passed,
failed: suite.failed,
modulePath: loadContext.modulePath,
},
null,
2,
),
'utf8',
);
},
getExitCode(suite) {
return suite.failed > 0 ? 1 : 0;
},
};
}

For a live terminal reporter that prints each completed test as an emoji, title, and duration:

scripts/emoji-reporter.mjs
export default {
name: 'emoji-status',
onTestResult(test, context) {
const icon = test.status === 'pass' ? '✓' : test.status === 'fail' ? '⨯' : '-';
const title = test.title?.trim() || test.file;
const duration =
typeof test.durationMs === 'number' ? ` ${(test.durationMs / 1000).toFixed(2)}s` : '';
context.stderr.write(`${icon} ${title}${duration}\n`);
},
};

TypeScript reporters use the same object shape; compile them to JavaScript before passing them to --reporter:

const createReporter = () => ({
name: 'typed-reporter',
onSuiteStart(suite, context) {
context.stderr.write(`starting ${suite.runnable} tests\n`);
},
onTestResult(test, context) {
context.stderr.write(`${test.status} ${test.title ?? test.file}\n`);
},
onSuiteEnd(suite) {
// Write artifacts, annotations, or summaries from suite.
},
});
export default createReporter;

The CLI loads reporter modules with Node dynamic import(). Use .mjs or .js files at runtime; for TypeScript, compile the reporter to JavaScript before passing it to --reporter. Loading .ts files directly depends on Node’s type-stripping behavior and is not part of the supported reporter contract.

The live hooks onSuiteStart, onTestStart, onTestStep, and onTestResult run while the suite is running; reporters do not receive generic command progress. Live hooks run as events arrive and are not awaited, so keep their work synchronous and move anything async to onSuiteEnd, which the CLI awaits before exiting. onSuiteEnd receives the final suite result. getExitCode can only raise the suite exit code, never lower it: the highest reporter-provided code wins and failed tests still exit with 1 when no reporter raises it further, so a reporter cannot mask a failing suite. Return an integer from 0 to 255, or undefined to leave the exit code unchanged. Other values fail with INVALID_ARGS; in particular, codes such as 256 are rejected before they can wrap to a successful process exit.

Parametrise .ad scripts

Substitute ${VAR} tokens in .ad scripts using values from the CLI, shell env, script-local env directives, or built-ins.

Terminal window
context platform=android
env APP_ID=settings
env WAIT_SHORT=500
open ${APP_ID} --relaunch
wait ${WAIT_SHORT}
click "label=${APP_ID}"

Precedence

Source Priority Example
CLI -e KEY=VALUE highest agent-device test flow.ad -e APP_ID=demo
Shell env prefixed AD_VAR_ AD_VAR_APP_ID=demo agent-device test flow.ad (imported as APP_ID)
Script env KEY=VALUE env APP_ID=settings in header
Built-ins runtime AD_PLATFORM, AD_SESSION, AD_FILENAME, AD_DEVICE, AD_ARTIFACTS

Built-ins

replay and test provide these built-ins in the reserved AD_* namespace.

  • AD_PLATFORM - matches context platform=... or the selected platform when available
  • AD_SESSION - active session name
  • AD_FILENAME - path of the running .ad file
  • AD_DEVICE - device identifier (when --device is set)
  • AD_ARTIFACTS - attempt artifacts directory (when running under test)

User-defined keys starting with AD_ are rejected in env, -e, and shell imports such as AD_VAR_AD_FOO, so built-ins cannot be overridden.

Substitution happens inside parsed string values. It does not create extra arguments, so quote selectors or text values that contain spaces:

Terminal window
env SETTINGS="label=Account || label=Profile"
click "${SETTINGS}"

Fallback and escape

Terminal window
wait ${WAIT_MS:-500}

${VAR:-default} yields default when VAR is unset.

Terminal window
echo "Price: \${APP}"

\${APP} emits a literal ${APP} with no substitution.

Recipes

Run one flow against two app variants in CI:

Terminal window
agent-device test ./flows/login.ad -e APP_ID=com.example.debug
agent-device test ./flows/login.ad -e APP_ID=com.example.release

Tune timings locally without editing the script:

Terminal window
AD_VAR_WAIT_SHORT=2000 agent-device replay ./flow.ad

Extract a reusable selector. Before:

Terminal window
click "label=Account || label=Profile || label=User"
wait 500
click "label=Account || label=Profile || label=User"

After:

Terminal window
env SETTINGS="label=Account || label=Profile || label=User"
click "${SETTINGS}"
wait 500
click "${SETTINGS}"

Quote ${VAR} inside selector expressions so the whole expression is treated as a single argument.

Notes

  • AD_VAR_* values come from the shell that runs the CLI, so they apply the same way whether the daemon runs locally or remotely.
  • Fallbacks do not nest: ${A:-${B}} is not supported.
  • An unresolved ${VAR} fails with a file:line reference, so a misspelled variable name stops the run.

Replay divergence and resume

A failing replay/test step returns a structured REPLAY_DIVERGENCE error. The report is size-bounded and redacted, and carries:

  • step — the 1-based plan index and its source file/line (through Maestro runFlow includes).
  • screen — a fresh post-failure snapshot digest with actionable refs, or unavailable with a reason/hint when capture failed or was sparse (never a stale tree).
  • suggestions — up to 5 ranked, re-resolved candidates for the failing selector (id match ranks above role+label, which ranks above label-only), each with a basis you can inspect before acting. For a verified target-v1 annotation, equally strong candidates in the recorded scroll region rank first; document order breaks remaining ties.
  • resume — whether and how to continue without re-running the script from the top.
{
"code": "REPLAY_DIVERGENCE",
"details": {
"divergence": {
"step": { "index": 4, "source": { "path": "flow.ad", "line": 6 } },
"screen": {
"state": "available",
"refsGeneration": 3,
"refs": [
/* ... */
],
},
"suggestions": [{ "selector": "id=\"auth_continue\"", "basis": "id" }],
"resume": { "allowed": true, "from": 4, "planDigest": "…64 hex chars…" },
},
},
}

Text output prints a compact summary of the same fields; --json/MCP carry the full object.

Resume a failed replay

During a repair armed with replay --save-script, diagnostic reads stay out of the healed script. To keep a corrective read, pass --record on that invocation, or record: true in that SDK/MCP call. --record is per-invocation only: the config key record and AGENT_DEVICE_RECORD were removed, and a config file or environment still naming them fails with migration guidance. Authored replay observations are retained automatically.

replay --from <n> --plan-digest <sha256> resumes at plan step n, not after it, skipping 1..n-1 without executing them. Both flags come from a divergence report’s resume field — from is the failed step, planDigest is the digest of the exact unchanged plan that produced it.

Choose one recovery workflow:

  1. Change the replay script. Review the suggestion, edit the selector or include, then run a fresh full replay ./flow.ad. The old digest is intentionally invalid after any plan edit; do not combine it with the edited script. A later divergence supplies a new digest.
  2. Keep the replay plan unchanged. Repair app/device state so the reported failed step can succeed when retried, then resume with the report’s unchanged from and planDigest. If you manually complete the failed action itself, the reported from will execute it again; only do that when repeating the action is safe.

The unchanged-plan resume loop is:

  1. Run replay ./flow.ad. On failure, read resume from the divergence.
  2. Leave the script, includes, platform, and target unchanged. Repair app state yourself so the failed step can be retried safely. Resume does not restore app state; it only skips the earlier steps.
  3. replay ./flow.ad --from <resume.from> --plan-digest <resume.planDigest>.
Terminal window
agent-device replay ./flow.ad
# ... REPLAY_DIVERGENCE, resume: { allowed: true, from: 4, planDigest: "ab12...“ }
# (repair app state on the device)
agent-device replay ./flow.ad --from 4 --plan-digest ab12...

For how --from counts steps in a Maestro flow, see Resume a failed Maestro flow.

Passing --plan-digest that no longer matches the current script — because you edited it, an include changed, or platform-conditioned expansion differs — fails INVALID_ARGS before any action; run a fresh full replay to get a new digest. --from is replay-only; test rejects it (a suite run must stay full and deterministic).

--update/-u

--update/-u does not rewrite .ad files. The flag is accepted and does nothing: every replay divergence carries ranked suggestions whether or not you pass it. Review a suggestion, then edit the .ad file yourself if it’s right. ADR 0012 explains why replay does not rewrite scripts automatically.

Troubleshooting

  • Replay fails after UI/layout changes:
    • Read the divergence report’s suggestions and repair the selector by hand; there is no automated rewrite. Because the edit changes the plan digest, run a fresh full replay instead of using the old resume flags.
  • Repeated re-runs are slow or the app is stateful, but the script is still correct:
  • Replay file parse error:
    • Validate quoting in .ad lines (unclosed double quotes are rejected). A selector with a space needs quotes, and help scripting states how each quote form decodes.
  • A replay passes on one device size and fails on another because a target was off screen:
    • The script used a fixed scroll amount. Replace it with the stop condition, scroll down --until <selector>, which repeats until the element is actually on screen.
  • A press or click step fails because its target was not found, but the element is on the screenshot:
    • A selector-miss divergence means the target was absent from the captured accessibility tree. Check the selector for this build and whether the app exposes the element to accessibility. Add a wait step for a landmark on a loading screen before the press.