---
title: "Update a test case"
method: PATCH
path: "/v1/test-cases/{test_case_id}"
tags: ["test-cases"]
---

# Update a test case

`PATCH /v1/test-cases/{test_case_id}`

Partially update a test case. Automatically creates a new version snapshot.

## Path parameters

- `test_case_id` string, required

## Headers

- `x-api-key` string

## Request body

- UpdateTestCaseRequest — Partial update for a test case
  - `name` string, nullable — Test case name
  - `steps` TestStepInput[], nullable — Ordered list of test steps
    - `description` string, required — Single atomic action
    - `credential_id` string, nullable — Credential UUID if step needs auth
    - `kind` 'setup' | 'act' | 'verify', nullable — Phase of the test the step belongs to: 'setup' (preconditions, navigation to the screen under test), 'act' (the action being tested), or 'verify' (post-action assertion). Untagged steps are stored without a kind and are treated as untagged downstream.
  - `expected_result` string, nullable — Expected result
  - `priority` string, nullable — Priority level
  - `description` string, nullable — Description
  - `change_source` string, nullable — Origin of the change (e.g. 'api', 'mcp')
  - `variables` TestCaseVariableInput[], nullable — Replace the declared variable schema for this test case. Pass [] to clear all. Omit the field entirely to leave the existing schema unchanged.
    - `name` string, required — Identifier matching /^[a-z][a-z0-9_]*$/, up to 40 chars; unique within the test case
    - `type` string, required — One of "string" or "number"
    - `required` boolean — When true, callers must supply a value at run creation (unless a default is set). The frontend also prompts for this variable in the run form.
    - `default` unknown
    - `description` string, nullable — Optional human-readable description shown in tooltips and the run form.
  - `file_attachments` TestCaseFileAttachmentInput[], nullable — Replace attached test files with UI-compatible associations. Pass [] to clear. Omit the field to leave attachments unchanged.
    - `file_id` string, required — ID of a test_files row with file_kind = 'test'
    - `description` string, nullable — Optional per-test-case description for this attachment.
  - `file_ids` string[], nullable — Legacy replacement list of test-file IDs. Pass [] to clear; omit to leave unchanged.

## Response `200`

Test case updated

- UpdateTestCaseResponse — Response after updating a test case
  - `id` string, required — Test case ID
  - `version_number` integer, required — New version number
  - `version_id` string, required — New version ID
  - `files` TestCaseFileAttachmentOutput[] — Attached test files persisted for this test case.
    - `file_id` string, required — Attached test_files.id
    - `description` string, nullable — Per-association attachment description
    - `file_path` string, nullable — Storage path for the attached test file
    - `original_name` string, nullable — Original uploaded filename
    - `file_type` string, nullable — MIME type
    - `file_size` integer, nullable — File size in bytes
  - `warnings` VariableWarning[], nullable — Non-fatal signals about variables; absent when nothing to warn about.
    - `code` string, required — One of: 'undeclared_reference' (step references a name not declared), 'literal_collision' (declaring a new variable turns existing literal `{{x}}` text into a substitution), 'unknown_variable' (run supplied a variable not declared on the test case; dropped silently).
    - `message` string, required — Human-readable explanation

## Other responses

- `401` — Invalid or missing API key
- `404` — Test case not found
- `422` — Validation Error
- `500` — Internal server error

---

[API](https://skmtc.dev/qualgent/apis/qualgent-api-service.md) · [All operations](https://skmtc.dev/qualgent/apis/qualgent-api-service/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/qualgent/qualgent-api-service/revisions/2372ed4904a6/schema)