Writing flows
For AI agents: this page is Markdown at https://squiggle.sh/docs/flows.md. Every docs page is listed at https://squiggle.sh/llms.txt, and all of them are one file at https://squiggle.sh/llms-full.txt.
A flow is a YAML file that walks through one journey in your app. Each step names the control it acts on by what it is, such as its testID or label, not by where it sits on the screen, so the flow keeps working when the layout changes.
A flow file
Flows live in .squiggle/flows/. This one signs in, adds a product to the cart and checks out:
flow: checkoutenv: USER: dana@example.comsteps: - runFlow: { file: login.yaml } - tap: { testID: product-1 } - tap: { text: Add to cart } - tap: { testID: checkout } - assert: { route: OrderConfirmation } - assert: { visible: { text: "Order placed" } }flow names the journey in reports and in Studio. You run a flow by its file name: squiggle flow checkout runs .squiggle/flows/checkout.yaml. env holds test data that steps use as ${USER}. steps is the journey: each step is one action or check. The Flow syntax reference lists every key and step.
What makes a good flow
- One journey per file. Sign-in, add to cart and checkout are three flows. Join them with
runFlowinstead of writing one long file. - Name controls by what they are. A
testIDsurvives copy edits, translations and redesigns. See Selectors. - End with an assert. A tap passes when the app reacts in any way, not only the way you meant. Check the result. See Assertions.
- Never sleep. Squiggle waits for the app to stop moving before each step. To wait for something specific, use
waitFor. Only when the app shows nothing to wait on, pause for a fixed time withwait: 1500.
Run it
squiggle flow checkoutThe same file runs in Studio, in CI and from your coding agent. See Run flows. To run it on a React web app, name the app by its origin: squiggle flow checkout --udid web:http://localhost:5173. See React web apps.
In this section
- SelectorsHow a step finds the control it acts on.Selectors
- AssertionsCheck the result of a step, not only that it ran.Assertions
- HealingWhen a control moves, the flow finds it again.Healing
- Repeatable flowsStart state, network stubs, reuse and control flow.Repeatable flows
- Bad networksSlow, failing and offline runs of a flow.Bad networks
- App stateFind the saved values that make a flow fail.App state
- Gestures and scrollingSwipes, scrolls, drags and off-screen controls.Gestures
- Pickers and system alertsAttach photos, share, and answer permission prompts.Pickers
- Record and crawlDraft a flow by using the app, or let it explore.Record
- Coming from MaestroWhat carries over from Maestro, and what doesn’t.Maestro
- Coming from PlaywrightThe flow step for each Playwright call.Playwright
Moving from Maestro or Playwright? See Coming from Maestro or Coming from Playwright. To write a step as a goal and let your coding agent work out the taps, see Agentic flows.