Skip to main content
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:
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 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 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.

​
Writing Effective Flow Instructions

Use Save all in the flow editor to save your edited flows and suites. Saving also refreshes unchanged flows and suites. Changes you make while a save is in progress remain unsaved until you save again. See Writing Effective Flow Instructions for guidance and examples.

​
Supported Agent Actions

Universal Actions (work on both mobile and web): Mobile-Only Actions: Web-Only Actions:

​
Running Flows

​
Running a Single Flow

  1. Find your flow in the Flows table
  2. Click the Play button (▶️)
  3. Select your app. Type to search by app or environment name. If your apps are in more than one environment, the list groups them by environment and shows the chosen app’s environment
  4. For a mobile app, choose a simulator or emulator model and OS version, or select a real device
  5. Click Run Flow
Virtual-device runs default to the latest supported permutation. Fast launch choices usually start sooner; every listed permutation is supported. To test across two devices, edit the flow, open Advanced, and set Number of devices to 2. Choose both devices when you run it. See Multi-Device Testing for details.

​
Running Multiple Flows

Select multiple flows using checkboxes:
  1. Check the boxes next to flows you want to run
  2. Click Run in the floating action bar
  3. Select your app
  4. Click Run Flows
A bulk run can mix one-device and two-device flows. If any selected flow uses two devices, choose Device 1 and Device 2; one-device flows run on Device 1.
Shift-Click Selection: Hold Shift and click to select a range of flows quickly

​
Running a Folder

Run everything in a folder at once:
  1. Check the box next to the folder and click Run in the floating action bar, or click the three dots (⋯) next to the folder and select Run
  2. Select your app
  3. Click Run
Checking a folder selects it as one unit: you don’t check the tests inside it. You can check other flows and suites alongside it. To run a folder from the API, copy its ID from the folder’s ⋯ menu (Copy folder ID). What runs:
  • Every suite and flow beneath the folder, in its subfolders at any depth.
  • Each suite runs in full, including flows it holds that are filed in other folders.
  • A flow that belongs to a suite runs only as part of that suite. If the suite is outside this folder, running this folder skips the flow.
  • A flow that isn’t in any suite runs on its own.
  • Each flow runs at its active version. In a branch run, tests stored in your repo run as they are on that branch, except inside a suite made in the dashboard, where they run at your default branch’s version.
A notification confirms the run and links to its results. If some tests couldn’t start, it says how many. The results are named after the folder. They show the folder’s subfolders and suites, each with a combined status, and the flows directly in it. The results keep the folder as it was when the run started, even if you move tests or folders later. On the Runs page, a batch with more than one run groups its flows and suites by folder, in the same order as the Flows page. Folders start closed and show how many tests passed, failed, are running, or are queued. Check the box next to a folder to select every run in it.

​
Running a Folder on a Branch

A folder from your repo can run on a branch. Pick the branch in the run dialog. The run takes the folder’s tests from that branch, plus any tests made in the dashboard and placed in the folder.

​
Auto-Retries

Autosana can automatically re-run a failed flow before reporting it as failed. Configure this in Settings → 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

​
Organizing Tests with Folders

Folders sort your flows and suites on the Flows page, for example by feature area, then sub-area, then the variants under test. A folder holds flows, suites, and other folders, nested as deep as you like. Folders change where a test is listed, not how it runs. You can also run a whole folder. Each flow and suite sits in one folder, or at the top level. To put a flow in several groups, add it to several suites. A suite in a folder can include flows from other folders. A flow that a suite includes shows under that suite only, not again in its own folder. The All flows view shows top-level folders and suites first, then your sections, then the Standalone flows and Auth flows sections. Click a folder to expand it. The Suites, Flows, and Labels views stay flat. Within each folder and section, the folders and tests you made come first: folders, then suites, then flows, each by name. Folders and tests from your repo come after them, sorted the same way. Once you drag something within a folder or section, everything in it keeps the order you set, and new tests land at the end. Inside a repo folder, the folders from your repo stay first, by name.

​
Creating a Folder

  • Click New → New folder to create a top-level folder.
  • To create something inside a folder, click the three dots (⋯) next to it and select New folder, New flow, or New suite.
  • The editor’s sidebar lists your folders and suites together, in the same order as on the Flows page. Click New next to Suites & folders to add a folder or suite, or use a folder’s ⋯ menu to add a folder, flow or suite inside it, or to rename it.
Type the folder’s name, then press Enter or click away to save. Press Esc to cancel. Folder names must be unique within their parent folder.

​
Renaming a Folder

  1. Click the three dots (⋯) next to the folder
  2. Select Rename
  3. Edit the name, then press Enter

​
Moving Tests and Folders

  • Drag a flow, suite, or folder to where you want it. A blue line shows where it will land: between two rows, or inside a folder. Hold it over a closed folder to open it. At the top level, flows reorder within their own section and can’t move above folders and suites; drop a flow inside a folder to file it there.
  • Or click the three dots (⋯) next to it, select Move to…, and choose a folder or Top level. Click New folder in that dialog to move into a folder you create on the spot.
To move several at once, check them and click Move to… in the selection bar. A folder can’t move into itself or into a folder inside it. Flows and suites from your repo move the same way, into any folder or section. Folders from your repo can only go into a section.

​
Deleting a Folder

  1. Click the three dots (⋯) next to the folder
  2. Select Delete
  3. Confirm deletion
Deleting a folder also deletes everything in it: its subfolders and every flow and suite inside them. Flows and suites from your repo aren’t deleted: they move to the top level. The confirmation says how many tests will be deleted, and names any suites in other folders that will lose flows. If a flow in the folder is the login step of a suite outside it, change that suite’s login step first. To bring a deleted folder back, click Undo in the message that appears after deleting. Everything returns where it was. Undo isn’t available once that message closes, and it fails if a folder with the same name now sits in the same place.

​
Grouping Tests into Sections

A section is a heading on the All flows view, such as Release or One-off, that groups top-level folders, suites, and flows. Sections are always open. They change where a test is listed, not how it runs. To run a group of tests from CI or the API, use labels.
  • Add a section: click + Add section above Standalone flows (hidden while a search or filter is on), or click New section in the Move to… dialog to create one and pick it.
  • Fill a section: drag a folder, suite, or flow onto the section’s heading or between its rows. Or select Move to… and choose the section. Moving an item into a folder takes it out of its section.
  • Run a section: open the ⋯ menu on its heading and select Select all, then click Run in the floating action bar.
  • Rename or delete a section: click the three dots (⋯) next to its heading. Deleting a section moves its items back to the top; click Undo in the message that appears to bring it back. Undo fails if another section now has the same name.
The editor’s sidebar shows the same sections and can do all of this except Select all. In the details panel, click Change next to Folder to move a flow or suite into a section. Folders, suites, and flows from your repo can go in sections too. A test stays in its section when you move it in the repo, as long as a flow keeps its file name, a suite keeps its folder name, and it stays at the top level. A renamed repo folder, flow file, or suite folder comes back outside its section. Auth flows always stay under Auth flows and can’t go into a section.

​
Code-Managed Tests

The top folder from a code-managed repo shows the repo’s name; the folders inside it don’t repeat it. Repo folders can’t be renamed, deleted, or moved into folders from the dashboard, but a top-level repo folder can go into a section. You can put flows, suites, and folders made in the dashboard inside repo folders. Code-managed flows and suites start in their directory’s folder (see Folders). Drag them or use Move to… to reorder them or put them in any folder or section. A push moves a test only when its file moves in the repo. To see each test where its file is, open Filters and check Arrange as in repo. Dragging is off in that view.

​
Flow Status and Results

​
Status Types

​
Viewing Results

Cache attempts that stop before sending an action to the device are hidden from the normal step list. They remain available in debug mode. Actual execution failures remain visible. Click on any status badge to view detailed results:
  • Screenshots: Visual snapshots at each step
  • Action Log: Every action performed by the agent
  • Console and Hook Output: Long output starts as a truncated preview. Select Show more to expand it, Show less to return to the preview, or the output heading to collapse or reopen it.
  • Errors: Any issues encountered
  • Timeline: Duration of each step
  • Device Info: Device type and OS version used

​
Sharing a Run Batch

On the Runs page, select the link icon beside a batch’s eye icon or inside its results to share the entire batch.

​
Advanced Features

​
Attaching Files

Add reusable files to your flow instructions:
  1. Open a flow’s Advanced options and add a file in the Files section.
  2. Click the + beside a file to insert its ${file:filename.xyz} reference in the instructions. You can also type the reference yourself.
  3. Files marked Used in this flow are prepared when that flow runs. Dimmed Available files are saved for reuse but are not prepared for that flow. Open a file’s three-dot menu to delete it from the shared library.
Sequential suite flows share a device session, so a file prepared by an earlier flow may still be present for a later flow. Reference the file in each flow that needs it so that flow prepares it explicitly. Parallel suite flows use separate sessions.

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

​
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. Cached actions cost 90% less than uncached actions (10% of the cost). On a run’s Details tab, Action breakdown shows the recorded cache setting and action counts in the order Main agent · State cache · Semantic cache. Hover over or select the counts for labels; keyboard users can focus the counts and press Enter. Other action sources appear as an additional count. If the run did not record its setting, it shows Not recorded. The Cache rate tile on Overview shows cached actions as a percentage of all actions. It follows the selected date range, app, and workspace scope. Partially cached runs contribute their cached and uncached actions separately. The percentage uses action counts, not billing; periods with no actions show an empty value. 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 a step cannot be replayed safely (e.g., because of a UI change or a setup-hook value Autosana cannot substitute), the agent handles that step live. Independent earlier steps can still use the cache.
  • Replay can resume after live execution when Autosana can verify the required action completed and the app matches a later checkpoint; otherwise the remaining steps run live. Runs that include live steps receive a fresh review.
Using hooks? How a hook passes a value to the flow affects whether the flow can be cached. See Hooks and Run Caching. Preview deployments: Web runs can reuse cached navigation across deployments when BASE_URL or API_BASE_URL is supplied as a build variable, suite/flow variable, or setup-hook export. Setting only the registered web url or a variable in Settings → Environments does not opt into this origin reuse. For CI previews, pass the deployment origin as BASE_URL through the Action’s variables input as well as setting url; see Web Setup. The variable must be an HTTP(S) origin, such as https://preview.example.com, with an optional trailing / and no other path, query string, fragment, or credentials. For supported cached navigation whose destination matches the recorded BASE_URL or API_BASE_URL origin, Autosana replaces that leading origin with the current value of the same variable while preserving the path and query. Other destination origins are not rewritten by this mechanism. These named origins qualify without the changing-value learning period required for custom hook exports. Ambiguous values and embedded redirect URLs still require live execution. Reuse stays within the same app and environment and remains subject to UI checkpoint checks. Keep production and preview targets in separate Autosana environments. Other changing variables still follow their existing caching rules. Manage it in Settings → Agent Features.

​
Run caching modes

Workspace owners and admins choose Off, Standard, or Semantic cache under Settings → Agent → Run caching.
  • Off runs every step with the live agent.
  • Standard reuses successful steps when the screen closely matches. Workspaces already using run caching start in this mode.
  • Semantic cache also finds equivalent controls when the screen changes. It is experimental and requires UI/UX Agent reviews.
Selecting Standard or Semantic cache also enables at least one auto-retry if retries were off. If reviews are later disabled, Semantic cache is paused. You can still select Standard or Off. For dashboard-authored flows, use Advanced options → Run caching. New flows use Use workspace setting. Choose Off to disable caching for a flow, or Standard to keep it on Standard even when the workspace uses Semantic cache. A flow cannot exceed its workspace’s mode: choosing Semantic cache in a Standard workspace still uses Standard. Code-managed flow controls remain read-only; set caching_mode in YAML instead. Semantic cache mode tries Standard caching first. When it cannot reuse a step, it compares a successful, reviewed recording with the current screen and finds the control that does the same thing. If the match is unclear, blocked, or missing, the live agent handles the action. The initial release supports eligible clicks, taps, and text entry on web and iOS. Android, unlabeled image targets, retries, and multi-device runs use the normal agent and Standard cache where supported. Some actions still need the live agent, so Semantic cache does not guarantee a faster run. Hooks execute again with current inputs and fresh results. Caching never reuses an old hook result. Variable extraction also stays live. Runs using Semantic cache get a fresh UI/UX Agent review, including runs that only record actions for future use. They cannot inherit an earlier pass. Run details show the recorded Cache setting and an Action breakdown of Main agent, State cache, and Semantic cache actions. These counts describe the recorded action sources independently of the selected cache setting. Historical runs without a saved setting show Not recorded.

​
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