flow-execute
Run saved automation sequences that launch apps, interact with UI elements, verify conditions, and capture screenshots across iOS, Android, and Chromium.
Instructions
Run a saved flow from the .argent/flows/ directory.
Steps run in order: launch starts an app from scratch (terminate + relaunch) and waits until it is
ready; tool calls dispatch through the registry; tap/long-press/type resolve a selector to an
element and act on it (tap: { on, times: 2 } double-taps; long-press: { on, duration } presses and
holds; tap/long-press alternatively take a raw normalized point — bare { x, y } or on: { x, y });
scroll-to scrolls (momentum-free) until a target is visible; pinch zooms
(pinch: { on?, scale } — scale > 1 in, < 1 out; screen center when on is omitted); rotate is the
two-finger rotation gesture (rotate: { on?, by } — degrees, + clockwise, within ±3000°; screen center
when on is omitted; distinct from the rotate tool, which changes device orientation); await waits
for a UI condition; wait pauses for a fixed number of milliseconds; assert checks one now; snapshot
diffs a screenshot against a stored baseline (a missing baseline fails the step — set updateBaselines
to adopt the current screen); echo annotates; run executes a referenced fragment inline.
A when: block (condition + steps:, no else) runs its steps only if the condition holds —
checked once with the short assert grace — for one-sided divergences like interstitials and coach
marks; a skipped block reports distinctly and failures inside an entered block are real failures.
A flow that begins with a launch step is a self-contained e2e flow; one that doesn't runs against the
device's current state. Device id is injected by the runner (flows store none) — pass device or
platform to pick one, else the single booted device is used. For a Chromium e2e flow the launch
step's chromium value is an Electron app path ({ chromium: | { path, args } }); the runner boots a
fresh instance from it (on the tool-server host) and tears it down when the run ends, unless an explicit
device pins an already-running instance. Every step hard-stops the flow on failure;
later steps are reported as skipped. Returns a structured report ({ ok, passed, failed, skipped, errored, steps }).
If a fragment has an execution prerequisite and prerequisiteAcknowledged is not set to true, the tool returns a notice with the prerequisite instead of running.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the flow to run (e.g. "settings-explore") | |
| device | No | Device id to run against (iOS UDID, Android/Vega serial, Chromium id). Auto-detected when omitted. | |
| platform | No | Restrict auto-detection to this platform when several devices are booted. | |
| flow_file | No | Path to the flow .yaml as readable by the tool-server. Internal — the argent client derives it from project_root and name automatically; leave unset. | |
| project_root | Yes | Absolute path to the project root directory that contains `.argent/flows/<name>.yaml`. | |
| updateBaselines | No | Write/refresh screenshot baselines for `snapshot` steps instead of diffing against them. | |
| prerequisiteAcknowledged | No | Set to true to confirm the execution prerequisite has been met. Required (LLM path) when a fragment defines an executionPrerequisite. |