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.

Loading the live Studio…
A failed run and the step that failed. Live, in your browser.Open in Studio

A flow file

Flows live in .squiggle/flows/. This one signs in, adds a product to the cart and checks out:

.squiggle/flows/checkout.yaml
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 is the name you run it by: squiggle flow checkout. 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 runFlow instead of writing one long file.
  • Name controls by what they are. A testID survives copy edits, translations and redesigns. See Selectors.
  • End with an assert. A tap passes once it reaches the button, whether or not the app reacted. 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.

Run it

Terminal
squiggle flow checkout

The same file runs in Studio, in CI and from your coding agent. See Run flows.

Run a flowStudio tour · 5 steps

In this section

Moving from Maestro? See Coming from Maestro. To write a step as a goal and let your coding agent work out the taps, see Agentic flows.