Create a test run

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

What it does

Creates a test run: one execution of a chosen set of test cases, where each case gets a result (Pass, Fail or Not Executed). Two ways to use it: (a) you already ran the tests, so pass runTestCaseList with each case's result, then call pdlc.verify; or (b) schedule first with runTestCaseSelection (or runTestCaseList without statuses), run the tests, then call testrun.record_results, then pdlc.verify. Get test case ids from case.list. Run names must be unique in the workspace. If the workspace has regression baselines (runs frozen with regression.freeze_run), include their cases too: pdlc.verify fails a run that is missing them. Pass the git fields (gitSha, branch, workingTreeClean) when grading code for the verifier loop; all three or none. They tie the verdict to the exact code that was tested, so a pass cannot be mistaken for approval of different or uncommitted code; they are stored on the run and returned by testrun.get, testrun.list and pdlc.verify. Returns { success, message, id, uri }; id is the testRunId for the next tool.

Ask your agent

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

  • “Run the checkout tests against my current commit and tell me if it is ready to ship”
  • “Record a test run for release 2.0 with these results”
  • “Set up a test run with all the login test cases”

Inputs

NameTypeDescription
name
required
stringRun name, unique within the workspace, e.g. "Checkout verify 2026-09-15 a1b2c3d". A name that already exists is refused; including the date or short commit SHA avoids clashes.
description
optional
stringOptional note on what this run covers, e.g. "Guest checkout after the payment form refactor".
buildVersion
optional
stringOptional version or build label of the app under test, e.g. "1.4.0" or "build 512".
startDate
optional
stringOptional date/time the run starts, ISO 8601, e.g. "2026-09-15" or "2026-09-15T10:00:00Z".
endDate
optional
stringOptional date/time the run ends, ISO 8601, e.g. "2026-09-15T10:20:00Z".
releaseId
optional
stringOptional id of the release this run belongs to (the id from release.list or release.create).
gitSha
optional
stringFull 40-character commit SHA of the code under test, from git rev-parse HEAD, e.g. "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678". Requires branch and workingTreeClean too.
branch
optional
stringGit branch of the code under test, from git rev-parse --abbrev-ref HEAD, e.g. "feature/guest-checkout". Requires gitSha and workingTreeClean too.
workingTreeClean
optional
booleantrue when there were no uncommitted changes while testing (git status --porcelain prints nothing), false otherwise. false means the tested code may differ from gitSha. Requires gitSha and branch too.
runTestCaseList
optional
object[]The test cases in the run, with optional results. Example: [{ "id": "AAtc-kzqd-…", "status": "Pass" }, { "id": "AAtc-mwpe-…", "status": "Fail", "issues": "Timeout 5000ms exceeded waiting for locator('#pay')" }]. Send this or runTestCaseSelection (one is required; if both are sent, runTestCaseSelection wins and these results are ignored).
runTestCaseSelection
optional
objectSchedule cases without results: { "selectedIds": ["AAtc-kzqd-…", "AAtc-mwpe-…"] }. Every case starts as not executed; record outcomes later with testrun.record_results. Takes precedence over runTestCaseList.

The MCP call

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

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

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.