Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
DESTRUCTIVE

update_test_case

Changes a test case's fields or steps, or moves it where the lifecycle allows by hand; every change writes a version.

Change a test case by test_case_id: any of title, suite_id, objective, preconditions (HTML), type, priority, automation_status, automation_ref, estimated_minutes, owner_id, test_data, environment_requirements, steps (replaces the list in order; a row with an id keeps and changes that step) and status. A field left out keeps its value; a field sent as null is cleared. The fields and the steps go through the same update the Test Cases page runs and write a version; test_case.updated goes out with the columns that changed.

status takes a move the lifecycle allows by hand: deprecated, or back to draft. in_review and active are reached through submit_for_review and the approvers, and a move is refused while a request is open; a move announces test_case.status_changed. A staff token with test-case:update on the project is needed.

Requires ability

test-case:update

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Annotations

Destructive

A client that honours annotations asks a person before running it.

Arguments

test_case_id*string

UUID of the test case.

titlestringoptional

What the case is called, 3 to 200 characters.

suite_idstringoptional

UUID of the suite to file the case in.

objectivestringoptional

What the case proves, as HTML.

preconditionsstringoptional

What must be true before it starts, as HTML.

typestringoptional

What kind of check it is; functional by default.

functionalregressionsmokesanityintegrationend_to_endapiperformancesecurityusabilityaccessibilityexploratory
prioritystringoptional

How much it matters when time is short; medium by default.

criticalhighmediumlow
automation_statusstringoptional

Whether a person or a script runs it; manual by default, and automated needs automation_ref.

manualcandidateautomateddeprecated
automation_refstringoptional

The test in the automation suite that runs it.

estimated_minutesintegeroptional

How long a tester needs for it, in minutes.

min1max9999
owner_idstringoptional

UUID of the person who owns the case, a member of the team.

test_datastringoptional

The data the case needs, as HTML.

environment_requirementsstringoptional

What the environment must offer, in a line.

stepsarrayoptional

The steps replacing the list, in order: objects with action (required), expected and test_data; a row with an id keeps that step.

statusstringoptional

A move the lifecycle allows by hand; the review states go through submit_for_review.

draftin_reviewactivedeprecated

What it returns

{  "data": {    "id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "suite_id": "a9b8c7d6-e5f4-4a3b-9c2d-1e0f9a8b7c6d",    "suite_name": "Vouchers",    "number": 46,    "reference": "CRM-TC-46",    "title": "Redeem a valid voucher at checkout",    "objective": "<p>A voucher in date takes its value off the basket.</p>",    "preconditions": "<p>A member is signed in with a valid voucher in the wallet.</p>",    "type": "smoke",    "priority": "critical",    "automation_status": "automated",    "automation_ref": "tests/Feature/CheckoutTest::test_valid_voucher_is_applied",    "estimated_minutes": 3,    "owner_id": null,    "owner_name": null,    "status": "draft",    "test_data": null,    "environment_requirements": null,    "last_result": null,    "last_executed_at": null,    "steps": [      {        "id": "f3a4b5c6-d7e8-4f9a-8b0c-1d2e3f4a5b6c",        "test_case_id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",        "position": 0,        "action": "Open the checkout with an item in the basket",        "expected": "The basket and the vouchers in the wallet are shown",        "test_data": null      }    ],    "position": 45,    "version": 2,    "approved_at": null,    "approved_revision_id": null,    "created_at": "2026-11-04T10:50:00+00:00",    "updated_at": "2026-11-04T11:30:00+00:00"  }}

How it fails

VALIDATION_FAILED

a field outside its limits, a suite that is not the project's, an owner outside the team, an automated case with no automation_ref, a step without an action, or a move the lifecycle refuses, into a review state, or while a request is open.

RESOURCE_NOT_FOUND

unknown test_case_id, or a case outside the token's scope or the person's visibility.

FORBIDDEN

the token is a client guest's, or the holder's role on the project does not carry test-case:update.

TOKEN_MISSING_ABILITY

token lacks test-case:update.

Related

get_test_casethe case as it stands before you change it.submit_for_reviewthe review states.restore_revisionput an earlier version back, steps included.Test cases APIthe same door over REST.

How is this guide?

Last updated on