> ## 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.
# Flows
> Write E2E tests in natural language
Flows are the heart of Autosana. A **flow** is a test written in natural language that describes what you want your agent to do in your app or website.
## What is a Flow?
A flow is a set of instructions that the agent follows to interact with your app or website. Instead of writing code or recording clicks, you simply describe what you want to test in natural language.
**Example Flow:**
```
Search for "wireless mouse".
Open the top result.
Add it to the cart.
Open the cart.
Verify the cart contains the wireless mouse.
```
The agent interprets these instructions, finds the relevant UI elements, and executes a series of actions, verifying results at each step.
## Creating a Flow
### Method 1: Quick Create
1. Navigate to the **[Flows](https://autosana.ai/flows)** page
2. Click **Create Flow**
3. Enter a flow name (required)
4. Write your instructions in natural language
5. Click **Create Flow**
### Method 2: Create in Suite
Create a flow directly within a suite:
1. Navigate to the **[Flows](https://autosana.ai/flows)** page
2. Expand a suite
3. Click **Create Flow** within the suite
4. Follow the same steps as Quick Create
5. The flow is automatically added to the suite
### Method 3: Define in Your Repo
Keep flows in version control and sync them from your repository — see [Code-Managed Flows](/code-managed-flows).
## Writing Effective Flow Instructions
See [Writing Effective Flow Instructions](/writing-effective-flow-instructions)
for guidance and examples.
## Supported Agent Actions
**Universal Actions** (work on both mobile and web):
| Action | Example Instruction |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Enter Text** | "Enter 'Joe Banana' in the name field" |
| **Clear** | "Clear the text from the email field" |
| **Verify** | "Verify that 'Welcome back!' appears on screen" |
| **Wait** | "Wait for the loading indicator to disappear" |
| **Drag and Drop** | "Drag the yellow card to the 'Drop here' area" |
| **Find on Page** | "Find 'Billing' on the page" *(jumps to the first match — Cmd/Ctrl+F on web, native scroll-into-view on mobile — much faster than swiping/scrolling)* |
| **Run Hook** | "Run `${hooks:Generate Test Order}`. Then search for the returned order number" |
| **Set Variable** | "Save the displayed order number as a variable called order\_id" |
| **Get Variable** | "Get the variable order\_id and enter it in the confirmation field" |
**Mobile-Only Actions**:
| Action | Example Instruction |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tap** | "Tap the login button" |
| **Swipe** | "Swipe right on the slider" |
| **Pinch** | "Pinch to zoom in on the map until San Francisco takes up the entire screen" |
| **Long Press** | "Long press on the 'Share' button" |
| **Hide Keyboard** | "Hide the keyboard" |
| **Open Deeplink** | "Open the deeplink 'myapp\://profile/123'" |
| **Change Location** | "Change location to longitude -122.4194, latitude 37.7749" *(suite-scoped: persists across all flows in the suite* |
| **Set Device Locale** | "Set the device locale to de\_DE, then verify German pricing is shown" *(changes the device's language & region setting; the app restarts to pick it up; persists until changed)* |
| **Set Orientation** | "Flip the device to landscape" or "Rotate back to portrait" |
| **Toggle Airplane Mode** | "Turn airplane mode on" (Android only) |
| **Set Network Condition** | "Simulate a slow 3G network, then restore full speed" — presets: full, offline, gprs, edge, slow\_3g, fast\_3g, lte (Android only) |
| **Run Appium Script** | `run_appium_script {"command": "mobile: enrollBiometric", "args": {"isEnabled": true}}` |
**Web-Only Actions**:
| Action | Example Instruction |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Click** | "Click the login button" |
| **Scroll** | "Scroll down until the settings option appears" |
| **Hover** | "Hover over the dropdown menu" |
| **Right Click** | "Right-click on the image" |
| **Double Click** | "Double-click to edit the text" |
| **Navigate** | "Navigate to [https://example.com/settings](https://example.com/settings)" |
| **Refresh** | "Refresh the page" |
| **Go Back** | "Go back to the previous page" |
| **Go Forward** | "Go forward to the next page" |
| **Hotkey** | "Press Control+c to copy the text" |
| **Run JS** | "Run JS: `document.querySelectorAll('script').length` and verify at least 3 scripts are loaded" |
| **Run Playwright Command** | `run_playwright_command {"target":"page","command":"emulate_media","args":{"color_scheme":"dark"}}` |
| **Read Console Logs** | "Read the browser console logs and verify there are no errors" |
| **Read Network Logs** | "Read the network logs and verify the POST to /api/login returned 200" |
| **Read Cookies** | "Read the browser cookies and verify a session cookie exists" |
| **Set Network Condition** | "Throttle the network to slow 3G, then restore full speed" — presets: full, offline, gprs, edge, slow\_3g, fast\_3g, lte (Chromium-family browsers) |
## Running Flows
### Running a Single Flow
1. Find your flow in the Flows table
2. Click the **Play** button (▶️)
3. Select your app
4. Click **Run Flow**
### Running Multiple Flows
Select multiple flows using checkboxes:
1. Check the boxes next to flows you want to run
2. Click **Run Selected** in the floating action bar
3. Select your app
4. Click **Run Flows**
**Shift-Click Selection**: Hold Shift and click to select a range of flows
quickly
### Auto-Retries
Autosana can automatically re-run a failed flow before reporting it as failed. Configure this in **[Settings → Agent](https://autosana.ai/settings?tab=agent)**.
* **Retries**: Set how many times a failed run is retried (0–5, default 1). A flow is only marked failed after all attempts are exhausted — if any attempt passes, the flow is reported as passed.
* **Intelligent Retries**: On by default. Retries are focused on flows with a track record of passing; flows that are consistently failing aren't retried. Turn it off to retry every failure.
## Managing Flows
### Editing a Flow
1. Click the pencil icon (✏️) next to a flow or click on the flow row
2. Modify the name or instructions
3. Click **Save Changes**
### Viewing Version History
Flows maintain a complete version history:
1. Click **Edit** on a flow
2. Click the **Version History** tab
3. View all previous versions with timestamps
4. Click **Revert** to restore a previous version
### Duplicating a Flow
To create a copy of an existing flow:
1. Click the three dots (**⋯**) next to a flow
2. Select **Duplicate**
3. A copy is created with "(Copy)" appended to the name
4. Edit the duplicate as needed
### Deleting a Flow
1. Click the three dots (**⋯**) next to a flow
2. Select **Delete**
3. Confirm deletion
## Organizing Flows with Suites
Suites help you organize related flows and run them together.
### Adding a Flow to Suites
**Method 1: During Creation**
* When creating a flow, select which suites it should belong to
**Method 2: After Creation**
1. Click the three dots (**⋯**) next to a flow
2. Select **Attach to Suite**
3. Check the suites you want to add the flow to
4. Click **Save**
**Method 3: From Suite View**
1. Expand a suite
2. Click **Add Existing Flows**
3. Select flows to add
4. Click **Add Flows**
### Removing a Flow from a Suite
1. Expand the suite containing the flow
2. Click the three dots (**⋯**) next to the flow
3. Select **Remove from Suite**
4. Confirm removal
## Flow Status and Results
### Status Types
| Status | Meaning |
| ----------- | --------------------------- |
| **Pending** | Flow hasn't been run yet |
| **Running** | Flow is currently executing |
| **Passed** | Flow completed successfully |
| **Failed** | Flow encountered an error |
### Viewing Results
Click on any status badge to view detailed results:
* **Screenshots**: Visual snapshots at each step
* **Action Log**: Every action performed by the agent
* **Errors**: Any issues encountered
* **Timeline**: Duration of each step
* **Device Info**: Device type and OS version used
## Advanced Features
### Attaching Files
Attach reference images to your flow instructions:
1. Click the paperclip icon (📎) when creating/editing a flow
2. Select files to attach
3. Reference the files in your instructions: "Open the gallery and tap on `${file:smiley_face.jpg}`"
### Using Hooks
Hooks are reusable scripts that run before or after your flow:
**Setup Hooks**: Run before the flow (e.g., "Clear app data and restart")
**Teardown Hooks**: Run after the flow (e.g., "Logout and clear cache")
1. Click **Edit** on a flow
2. Click **Add Hook**
3. Select **Setup** or **Teardown**
4. Write the hook instructions
5. Save the flow
You can read more about hooks [here](/hooks).
### Run Caching
When enabled, flows that have previously passed will use cached action sequences for faster execution (5-8x speedup). Run caching is best-effort and enabled by default.
**How it works:**
* After a flow passes successfully, the action sequence is cached
* Subsequent runs replay the cached actions with a smaller, faster model
* If the replay fails (e.g., due to UI changes), the full agent takes over
Manage it in **[Settings → Agent Features](https://autosana.ai/settings)**.
## Troubleshooting
### Flow Fails Immediately
**Possible Causes:**
* App build is missing or corrupted
* Bundle ID mismatch
* App crashes on launch
**Solutions:**
* Check that your app has an active build
* Verify the bundle ID is correct
* Test the app build manually first
### Agent Can't Find Elements
**Possible Causes:**
* UI element description is ambiguous
* Element isn't visible on screen
* Element loads after a delay
**Solutions:**
* Disambiguate by purpose or nearby label rather than visual attributes. Prefer "Tap the 'Submit' button under the password field" over "Tap the blue submit button in the bottom right" — describing pixel position or color locks the test to today's UI.
* Add a wait when the element loads asynchronously: "Wait for the order summary to appear, then continue."
## Next Steps
* [Organize flows with Suites →](/suites)
* [Automate flows with Schedules →](/automations)
* [Integrate with our CI/CD →](/ci-cd-integration)
* [Manage flows in your repo →](/code-managed-flows)