> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://poly-ai.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://poly-ai.ferndocs.com/_mcp/server.

# Simulation tests

> Author scenario-based tests with assertions, tags, and system actions.

Simulation tests run automated conversations against your agent. You describe what a simulated caller will do, assert how the agent should respond, and optionally verify that specific system actions are triggered.

## Create a test

On the **Tests** tab, select **+ Test** to open the **Add tests** panel.

![Add tests panel](/_fern-files/_img/dcf212b64fe1a5048ae4e71dbf881c88ef7473657f3e103854ac358833880ed3.webp)

#### Name the test

Give the test a descriptive name that summarizes the scenario (for example, "Language test" or "After-hours booking").

#### Choose a channel

Select **Voice** or **Chat** from the **Channel** dropdown. The channel determines how the conversation is simulated.

#### Write a test scenario

Describe the caller's behavior in plain language. The simulator uses this to generate realistic caller turns.

**Example:** *A customer calls and requests to speak in French during the call.*

#### Add prompt assertions

Assertions describe what the agent **should** do during the conversation. After the test runs, each assertion is evaluated and marked as passed or failed.

Select **+ Assertion** to add more.

**Example:** *The agent immediately switches to French and repeats the initial greeting.*

> **Tip**
>
> Write assertions that focus on observable agent behavior — language choice, information provided, actions taken — rather than internal implementation details.

#### \[Optional] Add tags

Add **tags** to organize and filter tests. Type a tag name and press Enter. A test can have multiple tags (for example, `language` and `french`).

Use tags with the **Filter tests** control on the Tests tab to find related tests quickly.

#### \[Optional] Configure advanced settings

Expand **Advanced configuration** to access optional settings:

* **Simulated variant** — select a specific [variant](/agent-studio/knowledge/variants/overview) to run the test against. Leave blank to use the default.
* **System actions** — define actions the agent is expected to take during the conversation. See [System actions](#system-actions) below.

![Advanced configuration](/_fern-files/_img/f8362c60785ab4e1e25979658ed1896fbf0e10377469308243f21002942af36f.webp)

#### Save the test

Select **Add 1 test** to save. The test appears in the Tests tab ready to run.

### System actions

System actions verify that the agent triggers the right backend operations — not just that it says the right things. Each action has:

| Field           | Description                                                                 |
| --------------- | --------------------------------------------------------------------------- |
| **Action name** | The system action the agent should invoke (for example, `switch_language`). |
| **Name**        | The parameter name (for example, `language`).                               |
| **Value**       | The expected parameter value (for example, `french`).                       |
| **Type**        | The parameter data type — **String**, **Number**, or **Boolean**.           |

Select **+ Action** to add more system actions to the test.

## Best practices

* **Name tests descriptively** – use names that describe the scenario, not the expected outcome (for example, "Caller cancels booking" rather than "Test 1").
* **Cover happy paths and edge cases** – include both successful flows and failure scenarios (invalid input, missing data, handoff triggers).
* **Use system actions for backend verification** – don't just test what the agent says; verify it triggers the right actions with the right parameters.
* **Use real conversations as a starting point** – save cases from [Conversation Review](/agent-studio/conversations/review) to test against real-world scenarios.