Record and replay flows
A flow is a recorded sequence of interactions with the app. The agent records the flow one time. Then the agent, or a CI job, replays the flow as many times as you need. Each replay follows the same path. Thus a manual reproduction, a smoke test or a comparison of two builds becomes repeatable.
Use a flow when:
- you profile the app again after a fix and you need the same path both times,
- you compare two builds on the same screens,
- you check a regression on each branch with the same steps,
- you worked through a long path with the agent and you want to keep it.
Recording a flow
The agent records a flow while it operates the app. You describe the path in one instruction. The agent starts a recording, performs each step on the device and records the step. Each step runs live during the recording. Thus the agent sees the result of a step before the agent records the step.
The agent adds a label between the steps. A label explains what the step does and which screen the agent expects. During a replay, Argent prints each label. Thus the report of a replay is readable.
When the agent has recorded the last step, the agent finishes the recording. Argent writes the flow to a file in the project.
Argent makes a recorded tap portable. When the tapped element has a stable text or identifier, Argent records the element instead of the coordinates. During a replay, Argent finds the element on the screen again. When the element has no stable text or identifier, Argent records the coordinates and adds a warning.
The flow file
Argent stores each flow as a YAML file in the .argent/flows/ directory of the project. The file contains a list of steps. The file does not contain a device identifier. Thus the same flow runs on a different simulator or a different emulator.
A flow has one of two shapes:
| Shape | First app step | 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 |
A fragment declares its start state in a prerequisite. The prerequisite is a sentence, for example "The Settings screen is open". Before a replay, the agent reads the prerequisite and puts the app into that state.
A flow can contain more than taps and text. A step can wait for an element, wait for the screen to settle, check a condition, take a screenshot and compare it to a baseline, run a different flow, or run a local script. See Baselines in flows for the screenshot comparison.
Use a local script for setup or cleanup that device steps cannot do. Ask the agent to add the script at the required point in the flow.
The file is plain text. You can commit the file, review the file in a pull request and edit a step by hand.
Replaying a flow
You ask the agent to run a flow by its name. The agent replays each step in order on the connected device. When a step fails, Argent stops the flow. Argent reports the later steps as skipped. At the end, the agent receives a report with the result of each step.
A flow also runs without an agent. The argent flow run command replays a flow from the terminal. The command prints the result of each step and exits with a status code. Thus a flow runs in a CI job or in a script. The command runs one flow, a flow file in a different location, or all flows in a directory.
Example instructions
- "Record the path from the start screen to the checkout summary as a flow named checkout."
- "Run the checkout flow and tell me which step fails."
- "Run the login flow on the iOS simulator and on the Android emulator. Compare the results."
- "Add a label before each screen change in the onboarding flow."
- "Record the checkout flow. Before the app starts, seed the cart with
scripts/seed-cart.mjs." - "Profile the app while you run the search flow. Then apply my fix and run the flow again."
Limits
- A replay runs on one booted device. When more than one device is booted, name the device in the instruction. A physical iPhone is never chosen automatically, even when nothing else is booted: name it in the instruction.
- A recorded tap with coordinates breaks when the layout changes. Give the element a stable text or identifier, then record the step again.
- A flow does not reset the data of the app. When a step creates data, for example a new item, each replay creates the data again. Start the flow with a launch of the app or with a step that restores a known state.
- The agent records a launch step for iOS, Android and Vega apps. For a Chromium or Electron app, add the launch step to the file by hand.
- On Android, a flow resolves each selector with the Argent Android helper, an instrumentation app that Argent installs over
adb. Argent installs the helper again when the device reports that the helper is absent, for example after a wipe. When the helper still does not start, the error message contains the error that the device reports. - A replay needs the same connected instrumentation as the recording. When the agent cannot read the UI tree, a step that still uses coordinates sends the tap anyway and adds a warning. A step that uses a stable identifier fails instead, because it has no coordinates to fall back on.
Argent does this with the flow-start-recording, flow-add-step, flow-add-echo, flow-add-script, flow-finish-recording, flow-read-prerequisite and flow-execute tools, and with the argent flow command. The tools reference contains all tools. The Flow YAML reference contains the file format and the command options.