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

create_test_case_draft

Adds a test case as a draft with its steps, filed in a suite when one is named, so a QA agent writes the cases a story's criteria call for and a tester reviews them.

Add a test case: project_id and title are required; suite_id files it in a suite, objective and preconditions (HTML) say what it proves and what must be true first, type (functional by default), priority (medium by default), automation_status (manual by default; automated needs automation_ref), automation_ref, estimated_minutes, owner_id (a member of the team), test_data (HTML) and environment_requirements fill in the record, and steps lays down the script in one go, each row with action (required), expected and test_data. The case takes the next number of its sequence, starts as a draft, writes its first version and is announced as test_case.created.

A case reaches in review and active through submit_for_review and the approvers, never by hand. A staff token with test-case:create on the project is needed.

Requires ability

test-case:create

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

project_id*string

UUID of the project.

title*string

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.

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": "high",    "automation_status": "candidate",    "automation_ref": null,    "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      },      {        "id": "a4b5c6d7-e8f9-4a0b-9c1d-2e3f4a5b6c7d",        "test_case_id": "b7c8d9e0-f1a2-4b3c-8d4e-5f6a7b8c9d0e",        "position": 1,        "action": "Pick the valid voucher",        "expected": "The discount is applied and the new total is shown",        "test_data": "SPRING25"      }    ],    "position": 45,    "version": 1,    "approved_at": null,    "approved_revision_id": null,    "created_at": "2026-11-04T10:50:00+00:00",    "updated_at": "2026-11-04T10:50:00+00:00"  }}

How it fails

VALIDATION_FAILED

title missing or outside 3 to 200 characters, a kind, priority or automation state outside its values, a suite that is not the project's, an owner outside the team, an automated case with no automation_ref, more steps than allowed, or a step without an action.

RESOURCE_NOT_FOUND

unknown project_id, or a project 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:create.

TOKEN_MISSING_ABILITY

token lacks test-case:create.

Related

list_test_suitesthe suite to file the case in.update_test_casechange the fields or the steps later.submit_for_reviewput the draft to the approvers.Test cases APIthe same door over REST.

How is this guide?

Last updated on