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 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 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 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 with wait: 1500.

Run it

Terminal
squiggle flow checkout

The 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.

Run a flowStudio tour · 6 steps

In this section

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.