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

# Create Test Case

> Create a test case for your dataset.

> [!WARNING]
>
> You are reading the docs of Galtea 5.12. [Read this page in the latest version](https://docs.galtea.ai/sdk/api/test-case/create.md).

## Returns

Returns a [TestCase](https://docs.galtea.ai/v5.12/concepts/product/dataset/test-case.md) object for the given parameters.

## Example

```python theme={"system"}
test_case = galtea.test_cases.create(
    dataset_id=dataset_id,
    input="What is the capital of France?",
    expected_output="Paris",
    context="Geography facts",
    variant="original",
)
```

### Starting from a predefined conversation

Write the turns out, or copy them from a session that already holds them. See [Starting a Scenario from a Conversation](https://docs.galtea.ai/v5.12/concepts/product/dataset/test-case.md#starting-a-scenario-from-a-conversation).

```python theme={"system"}
conversation_history = [
    {"role": "user", "content": "Hi, I am checking what this analytics workspace can do."},
    {"role": "assistant", "content": "I can help with dashboards, reports and data sources."},
    {"role": "user", "content": "Does it handle orders and payments too?"},
    {"role": "assistant", "content": "No. It reports on your data, it does not process payments."},
]

test_case = galtea.test_cases.create(
    dataset_id=dataset.id,
    user_persona="A team lead evaluating the product",
    goal="Get a clear answer about what the product does and does not cover",
    scenario="The user asks about an unrelated service",
    conversation_history=conversation_history,
    # Turns the simulator runs after the predefined conversation.
    max_iterations=2,
)
```

```python theme={"system"}
reused = galtea.test_cases.create(
    dataset_id=dataset.id,
    user_persona="A team lead evaluating the product",
    goal="Ask for a feature the product does not have",
    scenario="The user asks about an unrelated service",
    seed_session_id=test_case.seed_session_id,
    max_iterations=2,
)
```

## Parameters

**dataset\_id** `string` *required*

The ID of the dataset you want to create the test case for.

> [!NOTE]
>
> Deprecated alias: `test_id`.

**input** `string`

The input for the test case. For Accuracy and Safety datasets, this is the question or prompt you want to send to your model for evaluation. For Behavior datasets, this is the first user message to use in the conversation (bypassing the simulator for the first turn).

**input\_file\_paths** `list[string]`

Files to attach to the input, for a product that reads documents. Each entry is a local path the SDK uploads, or a storage URI from an earlier upload, which is attached without uploading the file again. `input` stays optional, so a test case may hold files and no text at all. Galtea sends each attachment to your endpoint when the [endpoint connection template](https://docs.galtea.ai/v5.12/concepts/product/endpoint-connection-template-syntax.md#attached-files-and-audio) names `input_files`.

At most 20 files totalling 20 MB, of these types: `pdf`, `docx`, `xlsx`, `pptx`, `rtf`, `png`, `jpg`, `jpeg`, `tiff`, `tif`, `bmp`, `webp`, `heic`, `heif`, `gif`, `txt`, `csv`, `md`, `html`, `xml`, `json`, `eml`. To attach one already-uploaded file to several test cases, use [Upload Input File](https://docs.galtea.ai/v5.12/sdk/api/test-case/upload-input-file.md) instead.

> [!WARNING]
>
> Evaluators cannot read files yet, so the judge is given the text of your conversation turns with the files stripped out. A metric that reads the input is **skipped** when no turn is left with text of its own, which is what a single-turn document run always looks like. This is true for both run styles: your own pipeline, and Galtea calling your endpoint. Log the text your pipeline extracted as the turn input, without the file, to have it scored, or use a metric that reads only the output. See [File inputs](https://docs.galtea.ai/v5.12/concepts/product/dataset/test-case.md#file-inputs).

**expected\_output** `string`

The expected output for the input given. This is the correct answer or response you want to evaluate against.

**expected\_tools** `list[string]`

The expected tools for the input given. This is the list of tools that the model should use to generate the expected output.

**context** `string`

The context for the test case. This is the additional information that can help the model generate the expected output.

**variant** `string`

An optional variant to categorize or label the test case (e.g., "original", "paraphrased").

**reviewed\_by\_id** `string`

The ID of the user who has reviewed and validated this test case.

**language** `string`

Language for the test case. Accepts a [BCP-47 language tag](https://en.wikipedia.org/wiki/IETF_language_tag): a bare ISO 639-1 code (`"es"`) or a code with a region subtag (`"es-MX"`, `"en-GB"`). The region subtag selects the regional variety in the simulated user's messages and in voice synthesis (the accent the simulated caller speaks with); generated test text keeps the base language. The value is stored as the full tag. A bare code for `ca`, `de`, `es`, `eu`, `fr`, `gl`, `it`, `nl` or `pt` defaults to that language's European variety in the simulated user's messages only (`pt` → `pt-PT`); an explicit region always overrides it, and neither voice synthesis nor the stored value is affected.

**gender** `string`

Persona gender, `"MALE"` or `"FEMALE"`, for voice evaluations: it selects the male or female synthesized voice for the simulated caller. A voice pinned for the call's locale takes precedence. Text evaluations ignore it. When unset, the voice uses the default for the language.

**background\_noise\_profile** `string`

Background noise mixed into the simulated caller's audio for voice evaluations run over a [phone connection](https://docs.galtea.ai/v5.12/concepts/product/phone-connection.md). Ignored for test cases that don't run over a phone connection.

* Clip-backed: `office`, `street`, `car`
* Synthetic: `white`, `pink`

> [!NOTE]
>
> This method creates the test case directly, so it does **not** inherit the parent [dataset](https://docs.galtea.ai/v5.12/concepts/product/dataset.md)'s background noise — omitting this parameter leaves the test case with no noise. (Test cases generated by Galtea from a ground truth file or a CSV upload do inherit the dataset's noise automatically; this only applies to cases created one-by-one through this method.)
>
> Must be set together with `background_noise_level` — passing only one of the two is rejected by the API.

**background\_noise\_level** `string`

How loud the background noise is relative to the caller's speech, as a fixed signal-to-noise ratio per level. One of `light`, `medium`, or `heavy`. Must be set together with `background_noise_profile`.

**user\_score** `int`

User vote for the test case (1 for good quality, -1 for bad quality, 0 for unreviewed).

**user\_score\_reason** `string`

Reason for the user vote given.

**confidence** `float`

Confidence for the test case.

**confidence\_reason** `string`

Reason for the confidence given.

**goal** `string`

The user's objective for behavior datasets. Used when creating BEHAVIOR test cases.

**user\_persona** `string`

Description of the user persona used to generate scenario-based test cases.

**scenario** `string`

Description of the scenario context for scenario-based test cases.

**stopping\_criterias** `list[string]`

List of criteria to end the conversation in scenario-based simulations.

**conversation\_history** `list[dict]`

A predefined conversation the simulation starts from, written out. Each entry is one message, `{"role": "user" | "assistant", "content": "..."}`, and at least one message is required. Galtea stores the conversation as a separate session and names it in the created test case's `seed_session_id`. See [Starting a Scenario from a Conversation](https://docs.galtea.ai/v5.12/concepts/product/dataset/test-case.md#starting-a-scenario-from-a-conversation).

An assistant message directly after a user message joins that user message to form **one turn**. Any other message opens a turn of its own, so a conversation may open with an assistant greeting or end on an unanswered question. The four messages above alternate, so they are two turns, which is the unit `max_iterations` counts.

> [!NOTE]
>
> A message carries text only. `retrieval_context` on a message is refused, so use `seed_session_id` when the conversation must carry retrieval context or tool calls. Cannot be sent together with `seed_session_id`. Both are only accepted on a Behavior test case whose product has at least one version.

**seed\_session\_id** `string`

The ID of an existing session to copy the predefined conversation from. The copy takes that session's turns **and its traces**, so a conversation built this way carries the retrieval context and tool calls that the written-out form cannot. The session must belong to the same product as the test case, and every turn in it must be finished. Removed turns at the end of the session are left out of the copy, so a session the agent ended can be copied. A removed turn in the middle of the session is refused.

> [!NOTE]
>
> On the created test case, `seed_session_id` names the copy Galtea made, not the session you passed. Cannot be sent together with `conversation_history`.

**max\_iterations** `int`

The maximum number of turns the simulator runs before the conversation ends. It counts the live turns only: a test case that starts from a predefined conversation runs this many turns on top of it. A predefined conversation of 4 turns with `max_iterations` 1 runs one new turn and the session ends with 5.

A turn is one exchange. A `conversation_history` of 8 alternating messages starting with the user is therefore 4 turns, not 8. Messages that do not alternate that way make more turns, so count them with the pairing rule above rather than halving.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.