# Unit Tests

Manage individual simulation test cases. A unit test combines a persona, a scenario, a target service (with version set), and success criteria to form a single, repeatable test of agent behavior.

{% hint style="info" %}
**Composition**

A unit test references:

* A **persona** (simulated user profile)
* A **scenario** (conversation objectives and instructions)
* A **service** and **version set** (the agent configuration to test)
* One or more **success criteria** (metrics with pass/fail thresholds)

The persona and scenario are referenced by ID; their latest versions are used at run time.
{% endhint %}

## Create a Unit Test

Create a new simulation unit test.

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "Onboarding - Confused New User",
       "description": "Tests that the agent successfully guides a confused new user through account setup.",
       "service_id": "6618791275130b73714e8d1c",
       "service_version_set_name": "release",
       "persona_id": "6618791275130b73714e8d2a",
       "scenario_id": "6618791275130b73714e8d3b",
       "max_interactions": 20,
       "success_criterions": [
         {
           "name": "Completion Rate",
           "metric_id": "6618791275130b73714e8d4c",
           "criterion": {
             "type": "boolean",
             "expected_value": true
           }
         }
       ],
       "tags": {"suite": "onboarding", "priority": "high"}
     }'
```

{% endtab %}
{% endtabs %}

**Response (201):**

```json
{
  "simulation_unit_test_id": "6618791275130b73714e8d5d"
}
```

### Success Criteria

Each success criterion links a metric to a pass/fail threshold. The `criterion` object defines the expected outcome based on the metric type (boolean, numeric, etc.). The `metric_id` must reference an existing conversation metric, and the criterion type must match the metric type.

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/unit\_test/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## List Unit Tests

Retrieve simulation unit tests that match the given filters. Only unit tests the authenticated user has `Simulation:GetSimulationUnitTest` permission for are returned.

Common filters:

* `id=<id>` (repeatable): filter by specific unit test IDs
* `is_deleted=true|false`: filter by deletion status
* `service_id=<id>` (repeatable): filter by service
* `persona_id=<id>` (repeatable): filter by persona
* `scenario_id=<id>` (repeatable): filter by scenario
* `creator=<org_id,user_id>` (repeatable): filter by creator
* `tag=key:value` (repeatable; `value` may be `*` for any value, or empty for null)
* `sort_by=+created_at|-created_at|+name|-name` (repeatable)
* `limit` (0-500, default 50), `continuation_token` (int, default 0)

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test/?limit=20&tag=suite:onboarding' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/unit\_test/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Search Unit Tests

Search for simulation unit tests by text query. Matches against the unit test name and description. Returns the top 50 results sorted by relevance.

* `query` (required): the search text
* `creator=<org_id,user_id>` (repeatable): filter by creator
* `tag=key:value` (repeatable)

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request GET \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test/search/?query=onboarding' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Accept: application/json'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/unit\_test/search/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Update a Unit Test

Modify an existing simulation unit test. All fields are optional. Only the fields you include are updated.

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test/<UNIT-TEST-ID>/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "description": "Updated description for the onboarding test.",
       "max_interactions": 30
     }'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/unit\_test/{simulation\_unit\_test\_id}/" method="post" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Delete a Unit Test

Soft-delete a simulation unit test. Existing references and any scheduled runs remain valid, but no new runs can be created. This endpoint returns an error if the unit test is currently used in any unit test set.

{% tabs %}
{% tab title="cURL" %}

```bash
curl --request DELETE \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test/<UNIT-TEST-ID>/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>'
```

{% endtab %}
{% endtabs %}

{% openapi src="<https://api.amigo.ai/v1/openapi.json>" path="/v1/{organization}/simulation/unit\_test/{simulation\_unit\_test\_id}/" method="delete" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Related

* [Simulation Overview](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations)
* [Simulation Personas](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-personas)
* [Simulation Scenarios](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-scenarios)
* [Simulation Unit Test Sets](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-test-sets)