> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosana.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Writing Effective Flow Instructions
> Write resilient flows that test user-visible behavior instead of UI implementation details.
## Default to journey-style
Users don't care if your button says "Continue" or "Next." They care whether they can do what they came to do — and your tests should reflect that.
By default, treat a flow as a contract with the **user-visible behavior** rather than the **UI implementation**. Behavior-level tests survive UI refactors; tests bound to specific buttons, colors, and positions don't.
Describe what the *user is doing*, not what the *UI looks like*. For tests where the UI itself is the contract, see [When the UI is the test](#when-the-ui-is-the-test).
## Structure
* **End with verification** — close the flow by asserting on the behavior you actually care about.
* **Bullets and multi-line steps are fine** whenever they read more naturally, such as a bulleted list of checks at the end of a flow.
* **Avoid numbered lists** — numbering locks in a rigid ordering that's painful to update later. Use plain lines or bullets instead.
## Good vs Bad Examples
**BAD — vague, no assertion:**
```
login to the app
type email
click submit
check if it works
```
**BAD — over-specified and brittle:**
```
Open the app
Tap the "Sign In" button at the bottom of the screen
Enter "test@example.com" in the email field
Enter "SecurePass123" in the password field
Tap the blue "Continue" button
Wait for the page to load
Verify that the heading "Welcome back!" is displayed
Verify that a profile icon is visible in the top right corner
```
This style locks the test to today's exact UI — a button rename or layout tweak makes it fail. Save it for tests whose subject **is** a single screen's behavior.
**Quoted UI labels are treated as exact ground truth.** Writing `Tap the "Sign In" button` couples the test to that exact label — rename the button to "Continue" and the test fails, even if the test isn't about that button. Only quote UI text when you're explicitly testing that the text appears, or when you need it to disambiguate between similar elements on the screen.
**GOOD — specific about intent, flexible about the steps in between:**
```
Login with these credentials:
email: test@example.com
password: SecurePass123
Submit and verify you land on the welcome screen.
```
## When the UI is the test
When the UI itself is the contract — such as form validation, error messages, disabled states, or exact copy — spell out the specifics.
## Use environment variables
Don't hardcode anything sensitive, such as passwords, API keys, or tokens, or environment-specific values, such as URLs, test IDs, or feature flags. Use `${env:VAR_NAME}` so the same flow runs across environments. Mark sensitive values as **secrets** to encrypt them at rest and hide them from logs.
```
Log in with email ${env:TEST_EMAIL} and password ${env:TEST_PASSWORD}.
Open the account settings from the user menu.
Verify your email address is displayed.
```
See [Variables](/variables) for the full environment, suite, flow, build, and agent variable model.
The same `${env:VAR_NAME}` references work in [code-managed flow files](/code-managed-files#referencing-variables) — values stay defined in the dashboard, never in your repo.
**Goal-oriented instructions create more flexible tests.** Instead of "click the gear icon, click Profile, click Change Email, type the new address, click Save, verify the success toast appears", write "update the user's email to '[new@example.com](mailto:new@example.com)' and verify it saves".
**Always include verification.** Close every flow by asserting on the outcome you care about — "verify the welcome screen appears", "verify the order shows in the list", or "check that the error message is shown".
**Web tests auto-load the site.** Don't include URLs unless you're explicitly testing URL functionality.