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

# 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](https://mintcdn.com/polyai/zdYy6ORmlm_2Hesc/images/analytics/sim-test-add-test.png?fit=max\&auto=format\&n=zdYy6ORmlm_2Hesc\&q=85\&s=492b17bd14fe74d965f1d00aeb9c4457)

**1. Name the test**

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

**2. Choose a channel**

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

**3. 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.*

**4. 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.

**5. \[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.

**6. \[Optional] Configure advanced settings**

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

* **Simulated variant** — select a specific [variant](https://docs.poly.ai/knowledge/variants/introduction.md) 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](https://mintcdn.com/polyai/zdYy6ORmlm_2Hesc/images/analytics/sim-test-advanced-config.png?fit=max\&auto=format\&n=zdYy6ORmlm_2Hesc\&q=85\&s=81148a03facc9b429dc33f4e376e2cdb)

**7. 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](https://docs.poly.ai/analytics/conversations/review.md) to test against real-world scenarios.