Flow YAML reference
A flow is a YAML file in .argent/flows/<name>.yaml. The agent records the file with the flow tools. You can also write or edit the file by hand. This page lists the file shape, the selectors, the directives and the argent flow command. For the concept, see Record and replay flows.
File shape
steps:
- launch: com.example.app
- await: { visible: { id: home-screen } }
- await: { idle: true }
The file has two top-level keys:
| Key | Required | Description |
|---|---|---|
steps | yes | The list of steps. Argent runs the steps in order |
executionPrerequisite | no | One sentence that names the start state. Only a fragment can declare it |
A flow has one of two shapes:
| Shape | First step that is not echo: or script: | Start state |
|---|---|---|
| End-to-end flow | launch: | Argent starts the app from scratch |
| Fragment | Any other step | The app is already in the state that the flow needs |
Argent skips leading echo and script steps when it classifies a flow. A flow that opens with an echo step and then a launch: step is still end-to-end. A flow that opens with a script step and then a launch: step is also end-to-end. Put the named start state of an end-to-end flow in a leading echo step.
A file does not store a device id. The runner selects the device. A launch: restarts the process but does not clear the app data, the account or the backend data.
When a step fails, Argent stops the flow and reports the later steps as skipped.
Selectors
A selector finds an element on the screen. Write a selector as an explicit map:
{ id: save-button }
{ text: Save }
{ role: button }
{ id: settings-row, text: Notifications }
{ text: { matches: '^Order #\d+$' } }
| Field | Match |
|---|---|
id | Exact, case-insensitive. The test id or accessibility id |
text | Case-insensitive substring, or { matches: <regex> } |
role | Case-insensitive substring of the element role |
any | Any element. Takes only true. Pair it with a relational scope |
All fields in a selector must match. An unqualified Android id also matches its qualified resource id. identifier is an alias of id. Use single quotes for a regex with a backslash. any: true is the only selector without its own id, text or role, so it needs a relational scope, for example { any: true, after: { text: Danger zone } }.
A bare string, for example tap: Save, is a loose selector. It tries id first, then text. Prefer the map form.
When several elements match:
| Directive type | Chosen element |
|---|---|
Action (tap, long-press, swipe, type, scroll-to, pinch, rotate) | The most specific visible match: exact text or id, then the smallest frame, then reading order |
Condition (await, assert) | exists and visible hold when any match qualifies. hidden holds when no match qualifies. text reads the first visible match |
Relational scopes
A selector can scope its matches by the frames of other elements:
| Key | Meaning |
|---|---|
within | The target is inside the frame of the anchor |
after | The target follows the anchor in reading order |
next | The target is the nearest match that follows the anchor |
- tap: { text: Delete, within: { id: profile-card } }
- assert: { visible: { role: Button, after: { text: Danger zone } } }
- tap: { role: Switch, next: { text: Wi-Fi } }
within uses the visual frame, not the source tree. Reading order is top to bottom, left to right. Scopes nest, with at most six scope keys in one selector. The await-ui-element tool does not support scopes.
Runner tree and discovery tree
The runner resolves a selector against a different tree than the describe tool:
| Platform | Runner tree | describe tree |
|---|---|---|
| iOS simulator | Native UIView hierarchy | Accessibility tree |
| Physical iPhone | Accessibility snapshot of describe | Same snapshot |
| Android | Full accessibility hierarchy | Trimmed interactable nodes |
| Chromium | DOM nodes with an id, label, value or handler | Full DOM |
| Vega | Toolkit page source | Same source |
On an iOS simulator and Android, an id absent from describe can still resolve in a flow. On Chromium, an element absent from describe cannot resolve. On an iOS simulator, do not copy a role from describe into a selector: the runner derives the role from the view class, describe from the accessibility traits. On a physical iPhone, the runner and describe read one tree: copy ids and roles from describe.
Directives
Each step contains one directive. A failed directive stops the flow.
| Directive | Shape | Description |
|---|---|---|
launch | <app id> or { native, ios, android, vega, chromium } | Terminate and start the app, then wait until the app is ready |
tap | <selector>, { on: <selector>, times } or { x, y } | Tap an element. times: 2 double-taps. x, y are normalized coordinates |
long-press | <selector> or { on: <selector>, duration } | Press and hold. duration in milliseconds |
swipe | <direction> or { from, direction, to, by, momentum, duration } | Move one finger across the screen. direction is the travel of the finger. See Swipe |
type | { into: <selector>, text, submit } | Focus the element and type. Presses Enter unless submit: false |
scroll-to | { target: <selector>, direction, within } | Scroll until the target is visible. direction is down (default), up, left or right |
pinch | { on: <selector>, scale } | Pinch around the element, or the screen center when on is absent. scale > 1 zooms in |
rotate | { on: <selector>, by } | Two-finger rotation in degrees, clockwise positive. This is a gesture, not the device orientation |
await | { <condition>, timeout } or { idle: true, stableFor, timeout } | Wait for a condition. Default timeout 7500 ms |
assert | { <condition> } | Check a condition now, with a fixed 1000 ms grace. Rejects timeout |
wait | <milliseconds> | Pause for a fixed time |
snapshot | <name> or { name, maxMismatch, cropOn } | Compare a screenshot with a stored baseline. See Snapshots |
run | <path> | Run another flow file inline. See Composition |
script | { path, timeout } | Run a local .mjs file in a new Node process. See Local scripts |
when | { <condition> } or { platform }, with steps: | Run the nested steps only when the condition holds. See Optional steps |
echo | <message> | Print a message in the report |
tool | <tool name>, with args: and optional delayMs: | Call any Argent tool with the given arguments |
tap, type and long-press do not scroll. Add scroll-to before them when the target can be off-screen.
A type step can contain a {{secret:NAME}} placeholder. The tool-server fills the value at run time and redacts the value in the report. See Secrets.
A gesture that resolves no selector passes with a warning when the runner cannot read the UI tree. This covers a coordinate tap, a swipe with no selector at either end, and a pinch or rotate without on. The warning says that Argent sent the gesture, not that the gesture reached the element.
Launch map
Use the map form for a flow that runs on more than one platform:
- launch: { native: com.acme.app, chromium: ../../app }
- launch: { ios: com.acme.app, android: com.acme.app.android, chromium: ../../app }
native is one id for iOS, Android and Vega. A per-platform key replaces it for that platform. chromium accepts a relative or absolute app path, or { path, args }. A launch that has no id for the platform of the run is an error.
A run on a remote simulator uses the ios entry. If the map has no ios entry, the run uses the native entry.
An Android app that starts from a non-launcher activity has no launch: form. Record restart-app with activity as a tool step and keep the flow as a fragment.
Swipe
- swipe: left
- swipe: { from: { id: story-card }, direction: left }
- swipe: { by: { y: -0.4 }, duration: 600 }
- swipe: { from: { id: drag-handle }, to: { id: drop-zone }, momentum: false }
A swipe moves one finger across the screen. direction is the travel of the finger, not the travel of the content. To bring an element on screen use scroll-to not swipe.
| Option | Value |
|---|---|
from | The start point. A selector or { x, y }. Argent selects the start when from is absent |
direction | up, down, left or right. Argent moves the finger a preset distance. With from, Argent clamps the travel on screen |
to | The end point. A selector or { x, y } |
by | A signed delta { x, y } in screen fractions. Argent delivers the exact delta. With from, a delta that leaves the screen fails the step |
momentum | false removes the fling at the default duration. Default true |
duration | The travel time in milliseconds. Default 300, minimum 150, maximum 10000 |
A step takes exactly one of direction, to and by. Each travel must cover at least 0.03 of the screen. Parsing rejects a shorter by. A shorter to fails the step during the run.
On Chromium, Argent runs a swipe as a mouse drag. On Vega, a swipe fails like the other touch directives.
Conditions
- await: { visible: { id: settings-screen } }
- await: { hidden: { id: loading-spinner }, timeout: 15000 }
- assert: { exists: { id: notifications-toggle } }
- assert: { text: { in: { id: preference-status }, equals: Enabled } }
- assert: { text: { in: { id: result-count }, matches: '^\d+ results$' } }
| Condition | Holds when |
|---|---|
exists | An element matches the selector |
visible | A visible element matches the selector |
hidden | No visible element matches the selector |
text | The text of the element in in satisfies exactly one comparator |
The text comparators:
| Comparator | Match |
|---|---|
contains | Case-insensitive substring |
equals | Case-insensitive full match |
matches | Case-sensitive JavaScript regex |
A negative condition passes before the element appears, for a typo, and on the wrong screen. First prove the screen and the same selector with visible. Then perform the action and check hidden.
Prove a navigation
Each screen change needs two checks:
- await: { visible: { id: profile-screen } } # identity
- await: { idle: true } # readiness
The identity selector must exist only on the destination. idle waits until the screen has content and stops changing in the UI tree and in the pixels.
- await: { idle: true, stableFor: 400, timeout: 9000 }
| Option | Default | Description |
|---|---|---|
stableFor | 250 ms | How long the screen must stay still |
timeout | 7500 ms | The budget of the whole wait |
idle never fails a run. A screen that does not settle passes with a warning. The warning names the reason: the screen kept moving, a small part kept moving, the wait ended mid-hold, the tree stayed empty, only the tree settled, or too few reads. Read the warning before you accept the step.
One outcome stops the run: the runner cannot read the UI tree at all. Argent marks the step as errored and skips the later steps.
idle has no assert form and no when form.
Optional steps
- when: { visible: { text: Got it } }
steps:
- tap: { text: Got it }
The guard accepts one exists, visible, hidden or text condition, or { platform: ios | android | chromium | vega }. A run on a remote simulator matches ios. A UI guard uses the assert grace and rejects timeout. There is no else. A skipped block reports as skipped. A failure inside an entered block is a real failure. Do not put a required check inside when:.
Composition
- run: ../shared/login.yaml
A run: path resolves against the directory of the flow file that contains the step. The .yaml suffix is optional.
| Platform | Behavior |
|---|---|
| iOS, Android | A nested fragment or end-to-end flow runs inline. A nested launch restarts the app |
| Chromium | Each launch step boots one instance. A later launch boots a fresh instance and stops the previous one of that app. Argent runs swipe as a mouse drag. pinch and rotate are rejected |
| Vega | Use tool: tv-remote and tool: keyboard. The touch directives are unsupported |
A fragment whose run: chain reaches a launch cannot declare executionPrerequisite. Parsing accepts the file, the run rejects it.
Snapshots
- snapshot: checkout-summary
- snapshot: { name: price-card, cropOn: { id: price-card }, maxMismatch: 0.2 }
A snapshot compares the current screen, or the frame of cropOn, with a stored baseline. A missing baseline fails the step. A mismatch above maxMismatch percent fails the step. The default maxMismatch is 0.5. A cropOn element whose size changed fails the step.
Baselines live in .argent/flows/__baselines__/<flow>/. Argent keys a baseline by platform and capture geometry, plus the selector for cropOn. A run on a remote simulator uses ios in the key. It uses the same baseline as a local iOS run with the same capture geometry. Run argent flow run <name> --update-baselines to write the baselines from a known-good state. A run on a remote simulator with --update-baselines rewrites the same baseline file that a local run uses. The step reason then says that a remote simulator wrote the baseline. Review each baseline before you commit it.
Use a snapshot for layout, color, spacing, typography, clipping and icons. Do not use a snapshot as the only proof of navigation, data or network behavior. Avoid timestamps, live data, ads and animation in the captured region. The runner pins the mobile status bar during a visual run.
Local scripts
- script: { path: ../../scripts/seed-order.mjs }
- script: { path: ../../scripts/seed-order.mjs, timeout: 60000 }
Use a script step for setup or cleanup that device steps cannot do. The script must be a local .mjs file.
A script step needs no device. A flow of script steps alone runs with no simulator, emulator or browser, and the report names no device. A run step or a when step beside it makes the flow resolve one again, so a script inside a when: { platform: ios } block needs a booted iOS device.
The value is always a map. Parsing rejects a bare script: scripts/seed.mjs.
| Key | Required | Description |
|---|---|---|
path | yes | An .mjs file, relative to the flow file that holds the step. Write the extension in lowercase, and match the letter case on disk |
timeout | no | The time limit of the step in milliseconds. The minimum is 100, and the default is 30000 |
Argent runs the script with the project root as the working directory. Argent gives the script an allowlist of environment names. Argent copies each value from the tool-server, not from the shell that starts the run. The tool-server is a long-lived process, so the values are the ones it held when it started. A variable you export now reaches a script only after you restart the tool-server. See Environment variables. The allowlist holds these groups:
PATH,HOMEand the equivalent Windows names- The identity, shell, locale, terminal, temporary-directory and cache names of the host
- The Windows platform names
- The proxy names and the TLS certificate names
- The Node, npm, Android, Java and Apple toolchain names
CI,SSH_AUTH_SOCK, and each name that starts withnpm_config_
Argent removes each other name. Argent removes its own token, its own port and each ARGENT_SECRET_ value. Argent does not read a project .env file, so a name such as NODE_ENV or DATABASE_URL is absent. There is no env key. Let the script read a secret or a URL from a file.
Three entries in the list give access to a credential. Each entry holds the value of the tool-server. SSH_AUTH_SOCK reaches the SSH agent of the session that started the tool-server. An npm_config_ name can hold a registry token. HOME is the home directory of that session, so the script reads ~/.npmrc, ~/.aws/credentials and ~/.argent/ from there. Run a script only when you trust it.
PATH is the value of the tool-server too. A script that runs psql, docker or pnpm finds the binary on that PATH. An editor that starts the tool-server gives it the PATH of the editor. The script also runs under the Node binary of the tool-server, not the binary on the PATH of your shell.
A failed step stops the flow. The verdict names the side that caused the failure.
| Verdict | Cause | Examples |
|---|---|---|
| Failed | The script | A missing file, a load error, a thrown error, or a non-zero exit code |
| Errored | The host | A time limit, a heap limit, a signal, a process that did not start, a full queue, a cancelled run, or a mis-cased filename |
A step that a thrown error stopped reports the message of the error and the frames of the script. Argent gives each frame a path relative to the project root. Argent removes the frames of Node and of its own runner, and keeps at most six.
The split holds only when the timeout is generous. Argent needs about a second to tell a script that never settles from a script the host stopped. Below that, the same defect of the script becomes a time limit, and the step is errored. Give a script a second or more before you read errored as a fact about the machine.
Parsing rejects a timeout below 100 milliseconds. The step starts a Node process before the script runs, and that start alone costs tens of milliseconds. A smaller limit ends the step at the time limit, or makes the result depend on the load of the host.
timeout bounds the run of the script, not the duration of the step. The tool-server runs a limited number of scripts at the same time, and it takes the number from the CPU count of the host. A step waits for a free slot before the script starts. The step reports the wait in its reason, and the wait can be longer than the timeout of the step. A step that finds the queue full is an errored step. Every project on the host shares one queue, because every project shares one tool-server.
scripts.maxTimeoutMs caps the timeout of each step, and scripts.heapLimitMb sets the heap of the process. Argent reads both keys from the global configuration file of the tool-server's own home directory. See Available keys.
On iOS, Android and Vega, a script step above the launch step runs before Argent restarts the app.
On Chromium, Argent boots the app before step 1 only when the run has no device and the leading launch names a Chromium app alone. A script step above that launch then runs while the app is up. In every other case Argent boots nothing before step 1: the script step runs first, and the launch step attaches to a running instance. Two cases reach it — a run you pin with --device, and a launch that names more than one platform when you pass no --platform.
The argent flow command
argent flow run replays a flow without an agent and exits non-zero on failure. The command always uses a local tool-server.
| Command | Description |
|---|---|
argent flow run <name> | Run .argent/flows/<name>.yaml |
argent flow run <path>.yaml | Run any flow file. The path must not contain .. |
argent flow run <dir> | Run every flow in the directory, one after the other |
argent flow list | List the flow files in .argent/flows |
| Option | Description |
|---|---|
--device <id> | The device to run on. Argent detects the device when you omit the option. A physical iPhone is never detected; name it here |
--platform <p> | ios, android, chromium, vega or ios-remote. Narrows the detection. ios still never picks a physical iPhone, and never picks a remote simulator either |
--update-baselines | Write the snapshot baselines instead of comparing them |
--output <dir> | Write the failed baseline, current and diff images to <dir>/<flow>/, for a CI artifact upload |
-r, --recursive | With a directory, also run the flows in subdirectories. Dot-directories and node_modules are skipped |
--json | Print the JSON report of the flow, or the JSON aggregate of the directory |
--json-stream | Print one JSON record per line: each step, then the result. One flow, and not with --json |
-- | End of options, for a flow name that starts with - |
argent flow run checkout --platform ios
argent flow run .argent/flows/checkout.yaml --output flow-artifacts --json
argent flow run ~/shared-flows/checkout.yaml --device <UDID> --update-baselines
argent flow run .argent/flows --recursive
The file name without .yaml names the report and the artifacts. It contains only letters, numbers, _ and -.
Each step line shows the time of the step before the reason, for example (1.2s). A step that did not run shows no time. The time of a when or run step does not include the steps in its block or fragment. The last line of a flow run shows the time of the run. The summary of a directory run shows the time of all flows, for example (1m 32s).
A directory run prints a numbered header for each flow. Under the header Argent prints each step of that flow that failed or carries a warning, with its artifact paths. Argent then prints one outcome line. Argent prints a summary of all flows at the end.
A flow that fails its steps lets the directory run continue. So does a flow that the tool-server rejects up front, such as an invalid file or a device that Argent cannot resolve. A transport failure ends the directory run. So does a rejection that the tool-server does not mark as a validation error, and a reply that is not a report. Argent counts the flows after the failure as skipped.
The outcome line of a flow that produced a report gives the result, the step counts and the time of that flow. The outcome line of a flow that produced no report states the reason. A single flow run prints the same reason under the name of the flow.
| Outcome line | Meaning |
|---|---|
not run (invalid flow) | The tool-server rejected the flow file or one of its steps |
not run (no device resolved) | Argent did not resolve one device for the flow |
not run (rejected) | The tool-server rejected the flow for another reason |
did not finish (run error) | The run failed before it produced a report |
did not finish (no run report) | The tool-server answered without a run report |
not run (batch stopped) | An earlier failure ended the directory run. Directory runs only |
--json and --json-stream print no header, no outcome line and no summary.
A directory run with --json writes one document. The document holds ok, total, passed, failed, skipped, durationMs and a flows array. durationMs is the time of the directory run in milliseconds. The array holds one entry for each flow. Each entry holds the path and the status. An entry holds report when the flow produced one, whether it passed or failed its steps. An entry holds error instead when the tool call produced no report — a rejected run, a run error, or a reply that is not a report. Such an entry also holds error_code and error_kind when the tool-server sends them. An entry with the status skip holds neither, because Argent made no call for that flow. --json-stream puts the same two fields on its error record.
A single flow run with --json writes the report of that flow. The report holds startedAt, the start of the run in epoch milliseconds, and durationMs, the time of the run in milliseconds. Each step that ran holds its own durationMs. Each progress record of --json-stream holds one step, with the same durationMs. When the run gets no report, Argent puts the reason on stderr instead. Use --json-stream to get the failure as a record.
Pin --platform and --device on iOS, Android and Vega. On Chromium, pass --platform chromium and omit --device. Then the runner boots the declared app path with a reproducible window size.
Remote runs
The flow-execute tool takes one flow source: name for a saved flow, or flow_path for any file. run: targets and baselines resolve on the file system of the tool-server. When the tool-server runs on a different machine, a name run sends only that one file. Argent checks the whole flow before it runs any step, and rejects a run:, script: or snapshot step at any depth with an error about the missing co-location, not about a missing fragment, script or baseline. flow_path is refused when the agent and the tool-server do not share a file system.
YAML safety
Quote a string that contains #, : or quotes. Quote a number, true or false in a text slot. Use single quotes for a regex with backslashes. Parsing rejects an unknown directive, an invalid selector, an invalid regex, else, an unsupported option, and an end-to-end flow that declares executionPrerequisite.