Create a test case

case.createChanges dataCreates, updates or deletes something in your workspace.

What it does

Creates one test case in the connected workspace: a written check of the app with steps to follow and the result to expect, for example "Guest can check out without an account". Call case.list first to avoid duplicates; to create several cases, or to file them under a feature, use case.create_batch instead (this tool does not attach the case to any feature). At least one step is required (via steps or stepPosition), otherwise the call fails with "Missing Steps". A human-readable caseId such as "GenTC-0007" is assigned for you. Returns { success, message, data: { id }, uri }; keep data.id, the internal id every other tool takes. Next, include it in a run with testrun.create or in a plan with testplan.create.

Ask your agent

You don’t call case.create yourself. Say something like this to Claude Code, Cursor or another MCP-connected agent:

  • “Write a test case for signing up with an email address”
  • “Add a test that checks a guest can check out without an account”
  • “Create a test for the password reset email”

Inputs

NameTypeDescription
title
required
stringShort name of what is being checked, e.g. "Guest can check out without an account".
description
optional
stringOptional longer explanation of the scenario and why it matters, in plain language.
priority
optional
enumHow important the case is. P0 = must never break (core flow), P1 = high, P2 = normal, P3 = trivial.
Allowed: P0P1P2P3
preCondition
optional
stringSystem state required BEFORE the test runs (auth, seed data, feature flags). Concrete enough that a reader can reproduce the starting state, e.g. "Logged out; cart contains 1 item".
expectedResult
optional
stringThe observable result a tester checks at the end of the steps — final URL, success/error message, key field on the entity. One concise sentence, e.g. "Order confirmation page shows an order number".
postCondition
optional
stringSystem state AFTER the test completes — what persisted, what side-effects fired (emails, queue messages, webhooks), what needs cleanup. Distinct from expectedResult: this is the system snapshot, not the UI assertion. Set to "No persistent state change." when the test is read-only.
steps
optional
string[]The steps in order, one plain instruction per string, e.g. ["Open /cart", "Click Checkout", "Choose Continue as guest", "Submit the payment form"]. Positions are numbered from 0 for you. Ignored when stepPosition is given. Send steps or stepPosition: a case with no steps is refused.
stepPosition
optional
object[]Alternative to steps when you want to set positions yourself: [{ "stepText": "Open /cart", "position": 0 }, { "stepText": "Click Checkout", "position": 1 }]. Takes precedence over steps. Most callers should just use steps.
tagData
optional
any[]Optional custom tags to attach. Each item is { "tagId": "<custom tag id>", "id": "<tag value id>" }, e.g. [{ "tagId": "AAct-…", "id": "AActv-…" }] for Module = Checkout. Items without tagId are skipped. The ids come from the custom tags set up in the Test Maze app; no MCP tool lists them today, so omit this unless the user gives you the ids.
status
optional
enumTestCase lifecycle status. ACTIVE is the default and means the case is part of the library and can be added to suites/runs. INACTIVE soft-archives the case — listings and joins skip it but data isn't deleted. Anything else gets rejected; the listing queries only filter on these two values.
Allowed: ACTIVEINACTIVE
acceptanceCriterionLabel
optional
stringSet when this case proves one acceptance criterion (AC) of a feature — one testable promise the feature makes, like "a guest can check out without an account". Use the AC's label, e.g. "AC1" or "AC3.2". Only cases with a label can be waived with case.waive_ac.
severity
optional
enumHow bad it is for users if this check fails: blocker (app unusable / release must stop), critical (core feature broken), major (important but has a workaround), minor, trivial (cosmetic). Defaults to "major". Stored for people reading the case; pdlc.verify does not weight failures by severity today.
Allowed: blockercriticalmajorminortrivial
automationStatus
optional
enumWhether the case has an automated (Playwright) script. manual = checked by hand, no script (default); planned = script not written yet; automated = has a runnable script; flaky = script sometimes fails for reasons unrelated to the app and needs fixing; deprecated = script no longer maintained. A label only.
Allowed: manualplannedautomatedflakydeprecated

The MCP call

What the agent’s MCP client sends (placeholders in angle brackets):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "case.create",
    "arguments": {
      "title": "<title>"
    }
  }
}

Connect your agent

npx -y @testmaze/mcp init tmt_xxx
claude mcp add tm --scope project -- npx -y @testmaze/mcp

Create the token in your Test Maze workspace under Settings → MCP. Setup for Cursor, Cline, Gemini CLI and Codex CLI is shown there too.