> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tests

> Run conversations against your agent and check that it behaves the way you expect.

![Tests Cover](https://mintcdn.com/voiceflow-009a8802/s3P1FU2SwfLb9qjL/images/tests-cover.png?fit=max\&auto=format\&n=s3P1FU2SwfLb9qjL\&q=85\&s=345d8660cde80f98423aae7c6a85641a)

Tests let you verify your agent's behaviour before real users see it. Each test simulates a conversation between a user and your agent, then checks that things like the agent's responses, where it routed, and which tools it called match what you expected.

## Key concepts

| Concept | What it is |
| - | - |
| **Test** | A simulated conversation between a user and your agent, with checks that confirm specific behaviour like "the agent escalates angry customers" or "the refund flow ends with a confirmation email." |
| **Turn** | A single message in the conversation. A turn is either a **User turn** (a message you wrote), an **Agent turn** (your agent's actual response), or a **Simulation** (an AI-generated section of the conversation). |
| **Check** | A condition that runs on one of your agent's turns. Checks look at the agent's response, where it routed, or what tools it called. |
| **Persona** | A saved set of starting variable values. Use personas to start a test as a specific kind of user. |
| **Past run** | The saved results from a previous time you ran a test. Useful for seeing how your agent's behaviour has changed over time. |

## Best practices

Follow this workflow for any meaningful change to your agent.

**1. Clone Main**

Create a new [environment](/docs/documentation/deploy/environments/overview.md) cloned from `Main` and name it after the change you're making.

**2. Make your change**

Update playbooks, workflows, tools, or anything else in the new environment.

**3. Add tests if needed**

Write new tests for any behaviour you've introduced or changed. If your existing tests already cover what you're working on, you can skip this step.

**4. Run your tests**

Click **Run all tests** in the **Tests** tab to run both your new tests and any tests that were already on the environment. Existing tests catch behaviour you didn't mean to change.

**5. Iterate**

If anything failed, dig into the result, adjust your changes, and re-run the tests. Repeat until everything passes.

**6. Ship the change**

Once your tests are green, [merge](/docs/documentation/deploy/environments/merging.md) the environment back to `Main`. Or, [route some traffic](/docs/documentation/deploy/environments/traffic-split.md) to the new environment first to A/B test it with humans before merging it to `Main`.

## Creating a test

To create a test, open **Tests** in the sidebar and click **New test**.

![Tests Create](https://mintcdn.com/voiceflow-009a8802/NHpRp09zo70gXfwC/images/Tests---create.png?fit=max\&auto=format\&n=NHpRp09zo70gXfwC\&q=85\&s=8bc72a4727c0411b8c54624dc21ea82f)

A test conversation is built from turns. Use the buttons at the bottom of the editor to add turns:

* **User turn** is an exact user message you script.
* **Agent turn** waits for your agent's real response. Your agent's messages are generated using your playbooks and workflows each time a test is run.
* **Simulation** lets an AI play the user across a section of the conversation. You describe a scenario and success criteria, and the simulation passes if the AI reaches the criteria within a turn cap you set.

Click **Add persona** at the top of the editor to start the test with a saved [persona](/docs/documentation/build/data/personas.md) (a set of starting variable values).

If your agent uses [events](/docs/documentation/build/behaviour.md), the **Launch** dropdown lets you start the test from a specific event instead of the default launch state.

![Tests Event And Persona (1)](https://mintcdn.com/voiceflow-009a8802/NHpRp09zo70gXfwC/images/Tests---event-and-persona-\(1\).png?fit=max\&auto=format\&n=NHpRp09zo70gXfwC\&q=85\&s=cc0bc21e97830c1b4689bd6905b09140)

### Adding checks to an agent turn

Checks allow you to verify that certain criteria are met during a turn. Click **Add check** on an agent turn and pick a type. Multiple checks can run on the same turn.

![Tests Add Check](https://mintcdn.com/voiceflow-009a8802/NHpRp09zo70gXfwC/images/Tests-add-check.png?fit=max\&auto=format\&n=NHpRp09zo70gXfwC\&q=85\&s=ba7ae9f4d6660ce9586b05066a4ac4a4)

| Check type | What it checks |
| - | - |
| **Response** | What your agent said. Choose **Exact response** to match a specific string, or **LLM as judge** to describe what you expect and let an AI grade the reply. |
| **Routing** | Whether your agent routed to a specific playbook or workflow. |
| **Tool call** | Whether a specific [API](/docs/documentation/build/tools/api-tool.md), [Function](/docs/documentation/build/tools/function-tool.md), [Integration](/docs/documentation/build/steps/integration.md), [MCP](/docs/documentation/build/tools/mcp-tool.md) or [System tool](/docs/documentation/build/tools/system-tools.md) was called. |

You can choose whether to run checks independently or sequentially on each turn by clicking the **...** button on a turn:

* **Independently**: each check runs on its own with no shared context. Use when order doesn't matter.
* **Sequentially**: checks run in order, each picking up where the last left off. Use when checks depend on each other.

![Tests Checks Run](https://mintcdn.com/voiceflow-009a8802/NHpRp09zo70gXfwC/images/Tests---checks-run.png?fit=max\&auto=format\&n=NHpRp09zo70gXfwC\&q=85\&s=c77db92e17a6512f631897922fb7da6b)

## Running tests

Tests never run automatically. You always start them yourself, either as a single test or as a batch. For each test you run, you can see the conversation as it plays out, whether each check passed or failed along with the reasoning, and the full conversation logs.

### Running a single test

While editing a test, click **Run** in the top right to start it.

![Tests Run Single](https://mintcdn.com/voiceflow-009a8802/NHpRp09zo70gXfwC/images/Tests---run-single.png?fit=max\&auto=format\&n=NHpRp09zo70gXfwC\&q=85\&s=69a563667c0a44397e649aee9b50e25d)

### Running multiple tests

From the **Tests** tab, click **Run all tests** to run every test, or select specific tests and click **Run \[number] tests**.

![Tests Run Multiple](https://mintcdn.com/voiceflow-009a8802/NHpRp09zo70gXfwC/images/Tests---run-multiple.png?fit=max\&auto=format\&n=NHpRp09zo70gXfwC\&q=85\&s=37f04e1080ed5a71370607e22eee6c38)

Tests run in parallel, and the runner shows each one passing or failing as it finishes. Click a test to see its full results. Use **Retry failed** to re-run just the failures, or **Retry all** to start over.

## Reviewing past runs

The **Past runs** tab lists every test and test batch that's been run on this environment. Open a past run to see exactly what failed, then go fix the issue in your agent.

![Test Past Runs (1)](https://mintcdn.com/voiceflow-009a8802/NHpRp09zo70gXfwC/images/Test---past-runs-\(1\).png?fit=max\&auto=format\&n=NHpRp09zo70gXfwC\&q=85\&s=d22613cf52ba318296b4bbe9d786dc46)

Once you've made a change, use **Retry failed** to re-run only the tests that didn't pass, or hit the retry icon next to a single test to re-run just that one and verify your fix.

## Test costs

Tests consume credits when LLM-powered features are used, the same as in a real conversation. See the [credits pricing table](/docs/documentation/account-management/billing/credits-pricing-table.md) for what consumes credits.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.