> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-tests.md). # 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. ```bash curl --request POST \ --url 'https://api.amigo.ai/v1//simulation/unit_test/' \ --header 'Authorization: Bearer ' \ --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"} }' ``` **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` (with `expected_value`), `numerical` (with `verb` and `threshold`), or `categorical` (with `expected_values`). The `metric_id` must reference an existing conversation metric, and the criterion type must match the metric type. {% openapi src="" path="/v1/{organization}/simulation/unit\_test/" method="post" %} {% 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=` (repeatable): filter by specific unit test IDs * `is_deleted=true|false`: filter by deletion status * `service_id=` (repeatable): filter by service * `persona_id=` (repeatable): filter by persona * `scenario_id=` (repeatable): filter by scenario * `creator=` (repeatable): filter by creator * `tag=key:value` (repeatable; `value` may be `*` for any value, or empty for null) * `sort_by=+updated_at|-updated_at` (repeatable; only `updated_at` is a supported sort field - prefix `+` for ascending, `-` for descending; other fields fail validation with 422) * `limit` (0-500, default 50), `continuation_token` (int, default 0) ```bash curl --request GET \ --url 'https://api.amigo.ai/v1//simulation/unit_test/?limit=20&tag=suite:onboarding' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` {% openapi src="" path="/v1/{organization}/simulation/unit\_test/" method="get" %} {% 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=` (repeatable): filter by creator * `tag=key:value` (repeatable) ```bash curl --request GET \ --url 'https://api.amigo.ai/v1//simulation/unit_test/search/?query=onboarding' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' ``` {% openapi src="" path="/v1/{organization}/simulation/unit\_test/search/" method="get" %} {% endopenapi %} ## Update a Unit Test Modify an existing simulation unit test. All fields are optional. Only the fields you include are updated. ```bash curl --request POST \ --url 'https://api.amigo.ai/v1//simulation/unit_test//' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "description": "Updated description for the onboarding test.", "max_interactions": 30 }' ``` {% openapi src="" path="/v1/{organization}/simulation/unit\_test/{simulation\_unit\_test\_id}/" method="post" %} {% 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. ```bash curl --request DELETE \ --url 'https://api.amigo.ai/v1//simulation/unit_test//' \ --header 'Authorization: Bearer ' ``` {% openapi src="" path="/v1/{organization}/simulation/unit\_test/{simulation\_unit\_test\_id}/" method="delete" %} {% endopenapi %} ## Related * [Simulation Overview](/developer-guide/classic-api/core-api/simulations.md) * [Simulation Personas](/developer-guide/classic-api/core-api/simulations/simulation-personas.md) * [Simulation Scenarios](/developer-guide/classic-api/core-api/simulations/simulation-scenarios.md) * [Simulation Unit Test Sets](/developer-guide/classic-api/core-api/simulations/simulation-unit-test-sets.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/classic-api/core-api/simulations/simulation-unit-tests.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.