> ## Documentation Index
> Fetch the complete documentation index at: https://documents.tmsone.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Flow Library

The **Flow Library** lets you define reusable sequences of test steps — called **flows** — that can be inserted into any Test Builder script. Instead of re-typing the same login, navigation, or setup steps in every test, you define them once in the Flow Library and reference them anywhere.

***

## How it works

A flow is a named sequence of steps with optional **parameters** — placeholders that get filled in with real values at the point of use. When a flow is inserted into a Test Builder script, the parameters are resolved before the script is generated.

```text theme={null}
Flow Library
  ↓  define once: steps + named parameters
Test Builder — Insert Flow
  ↓  supply parameter values at point of use
AI generates script
  ↓  flow steps expanded with resolved values
Playwright script ready to execute
```

***

## Creating a flow

From the left sidebar, click **Flow Library** under your project.

### 1. Click "New Flow"

This opens the Create Flow form.

### 2. Fill in the form

<ParamField path="Flow Name" type="text" required>
  A short, descriptive name. Aim for something that explains the flow's purpose at a glance.\
  Example: *"Login — valid credentials"*, *"Add item to cart"*
</ParamField>

<ParamField path="Description" type="text">
  Optional. A longer explanation of what this flow does and when to use it.
</ParamField>

<ParamField path="Parameters" type="list">
  Optional. Named inputs that callers must supply when inserting this flow. Use them in step selectors and values with the `{{paramName}}` syntax.

  Parameter names must use letters, numbers, or underscores only — no spaces.

  Example parameters: `username`, `password`, `product_id`
</ParamField>

<ParamField path="Steps" type="table" required>
  The sequence of actions this flow performs. Each step has:

  | Field         | Description                                                                 | Example                                             |
  | ------------- | --------------------------------------------------------------------------- | --------------------------------------------------- |
  | Action        | What to do                                                                  | `click`, `type`, `navigate`, `verify`               |
  | Selector      | The element to target (CSS selector or XPath). Supports `{{paramName}}`.    | `#email`, `//*[@id='submit']`, `{{login_selector}}` |
  | Value / Token | A fixed value or a `{{paramName}}` token that will be filled in at runtime. | `admin@example.com`, `{{username}}`                 |

  At least one step is required.
</ParamField>

### 3. Save the flow

Click **Save Flow**. The flow is saved with **Draft** status. Flows in Draft status are visible to you but not yet treated as ready for team-wide use.

***

## Parameters and tokens

Parameters are what make flows reusable. Instead of hardcoding a username or URL, you define a parameter (e.g. `username`) and reference it in step values as `{{username}}`.

When someone inserts the flow into a Test Builder script, they are asked to supply a value for each parameter — either a fixed string or another token if they have scenario data.

### Defining a parameter

In the Parameters section of the form, click **Add Parameter** and type the parameter name.

Once defined, the available parameters are shown as clickable tags below the list. Click any tag to copy the `{{paramName}}` token to your clipboard.

### Using a token in a step

In the **Value / Token** column, type `{{paramName}}` to reference the parameter at runtime. You can also type a plain value to hardcode it — not every field needs to be dynamic.

The **Selector** column also supports `{{paramName}}` tokens for cases where the element target itself varies at runtime.

<Tip>
  Only use parameters for values that genuinely change between uses. Hardcode anything that is always the same — it keeps the flow easier to understand and avoids unnecessary prompts at insert time.
</Tip>

***

## Managing flows

### Flow status

Each flow has a status:

| Status     | Meaning                                                                          |
| ---------- | -------------------------------------------------------------------------------- |
| **Draft**  | Work in progress. Visible in the library but signals it may not be stable.       |
| **Active** | Ready for team use. Shown prominently in the Insert Flow picker in Test Builder. |

To change the status, open a flow for editing and update the **Status** field.

### Editing a flow

Click a flow's name in the list to open it for editing.

When you save changes to a flow's **steps or parameters**, every saved script that references this flow is automatically flagged as **Stale**. A warning badge appears next to those scripts in the Test Builder history so they are easy to spot. Changes to the flow's **name, description, or status** do not trigger stale marking, as they do not affect generated code.

From the Test Builder history, click **Regenerate** on any stale script to re-expand the updated flow and produce a fresh Playwright script.

<Note>
  Stale marking is best-effort — it tracks scripts saved after the flow reference system was introduced. Older scripts saved before this feature was enabled will not show a stale badge. If you are unsure, regenerate manually.
</Note>

### Deleting a flow

A flow **cannot be deleted** while any saved script still references it. Attempting to delete such a flow will show an error listing how many scripts depend on it.

To delete a flow:

1. Go to **Test Builder → History**
2. Find and delete (or regenerate without the flow) any scripts that reference it
3. Return to the Flow Library and delete the flow

This prevents silent breakage — scripts that referenced a deleted flow would fail at execution time with no indication of what went wrong.

***

## Inserting a flow into Test Builder

Once flows are set up, they appear in the **Insert Flow** picker inside the Test Builder form.

1. Open Test Builder and start building a script
2. Click **+ Insert Flow** above the Steps table
3. Select the flow you want to insert
4. If the flow has parameters, a form appears asking you to supply a value for each one
5. Click **Insert** — the flow appears as a step block in your test steps list

The inserted flow runs as a cohesive unit when the script is generated. Parameter values you supplied are substituted into the flow's steps before code generation.

<Note>
  If no active flows appear in the picker, you may need to create and activate a flow first. A prompt in Test Builder will link you to the Flow Library if no flows are found.
</Note>

***

## Example: Login flow

**Parameters:** `username`, `password`

| Action   | Selector                | Value / Token                   |
| -------- | ----------------------- | ------------------------------- |
| navigate |                         | `https://app.example.com/login` |
| type     | `#email`                | `{{username}}`                  |
| type     | `#password`             | `{{password}}`                  |
| click    | `button[type='submit']` |                                 |

When inserted into a test, you supply:

* `username` → `admin@example.com`
* `password` → `Admin123!`

The generated script types those values into the correct fields and submits the form — no hardcoded credentials in any individual test.

***

## What's next?

<CardGroup cols={2}>
  <Card title="Test Builder" icon="wand-magic-sparkles" href="/qa/test-builder">
    Use flows inside the Test Builder to generate Playwright scripts
  </Card>

  <Card title="Execution History" icon="chart-bar" href="/qa/execution-history">
    View the results of executed automation scripts
  </Card>
</CardGroup>