# Unit Test Sets

Manage grouped collections of unit tests that form a test suite. A unit test set bundles multiple unit tests together, each with a configurable run count, so you can execute an entire suite in a single operation.

{% hint style="info" %}
**Run Counts**

Each unit test in a set has a `run_count` that determines how many times it will be executed during a run. Running tests multiple times gives you statistical significance. For example, running each test 5 times helps distinguish consistent failures from flaky behavior.
{% endhint %}

## Create a Unit Test Set

Create a new simulation unit test set.

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

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test_set/' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "name": "Onboarding Suite - Release Validation",
       "description": "Full onboarding test suite for release candidate validation.",
       "unit_test_runs": [
         {"unit_test_id": "6618791275130b73714e8d5d", "run_count": 5},
         {"unit_test_id": "6618791275130b73714e8d6e", "run_count": 3}
       ],
       "tags": {"suite": "onboarding", "stage": "release"}
     }'
```

{% endtab %}
{% endtabs %}

**Response (201):**

```json
{
  "simulation_unit_test_set_id": "6618791275130b73714e8d7f"
}
```

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

## List Unit Test Sets

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

Common filters:

* `id=<id>` (repeatable): filter by specific set IDs
* `is_deleted=true|false`: filter by deletion status
* `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-20, default 20), `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_set/?limit=10&tag=stage:release' \
     --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\_set/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Search Unit Test Sets

Search for simulation unit test sets by text query. Matches against the set 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_set/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\_set/search/" method="get" %}
<https://api.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Update a Unit Test Set

Update a simulation unit test set. All fields are optional. Only the fields you include are updated. You can modify the name, description, unit test run list, and tags.

{% hint style="info" %}
For the `description` field, pass the new description string to update it, or pass `null` to clear it. Omitting the field (or passing an empty object `{}`) leaves the existing description unchanged.
{% endhint %}

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

```bash
curl --request POST \
     --url 'https://api.amigo.ai/v1/<YOUR-ORG-ID>/simulation/unit_test_set/<UNIT-TEST-SET-ID>' \
     --header 'Authorization: Bearer <AUTH-TOKEN>' \
     --header 'Content-Type: application/json' \
     --data '{
       "description": "Updated suite description.",
       "unit_test_runs": [
         {"unit_test_id": "6618791275130b73714e8d5d", "run_count": 10},
         {"unit_test_id": "6618791275130b73714e8d6e", "run_count": 5},
         {"unit_test_id": "6618791275130b73714e8d8g", "run_count": 3}
       ]
     }'
```

{% endtab %}
{% endtabs %}

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

## Delete a Unit Test Set

Soft-delete a simulation unit test set.

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

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

{% endtab %}
{% endtabs %}

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

## Related

* [Simulation Overview](/developer-guide/classic-api/core-api/simulations.md)
* [Simulation Unit Tests](/developer-guide/classic-api/core-api/simulations/simulation-unit-tests.md)
* [Simulation Unit Test Set Runs](/developer-guide/classic-api/core-api/simulations/simulation-unit-test-set-runs.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-test-sets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.