Runs & executions
A Run is one execution of a Test Plan. Each run owns a set of Executions — one row per test case in the plan.
Lifecycle
A QA lead creates a Run from a Test Plan in the web UI. At creation, TCM materialises an Execution row for every test case in the plan, all with result = "" (pending). The run’s counters look like { total_count: N, passed_count: 0, failed_count: 0, ... }.
As your CI job patches each execution’s result, the run’s counters update atomically. The run is in a terminal state once every execution has a non-empty result (or has been explicitly skipped).
Result values
passed— the test case ran and asserted the expected outcome.failed— the test case ran but the assertion did not hold.skipped— the case was deliberately not run (filter, tag, dependency).blocked— the case could not run because of a setup/environment issue.partial— the case ran but only some of its steps/assertions passed.
All five are terminal results. In the run summary, blocked and partial both count toward the failed tally — anything that isn’t a clean passed or an intentional skipped counts against the run.
Recording a single blocked result also latches the whole run’s status to blocked — one blocked test case marks the run as blocked at a glance. It is sticky: recording other results afterwards does not clear it.
Error & remark
When you record a result you can attach an error (alias error_message) and a free-text remark (alias remarks). Both are optional and surface on the test case’s row in the run — expand it to see the error and remark — and in the downloadable run report.
Idempotency
PATCH /executions/{id} is idempotent — calling it twice with the same body produces the same result. If your job retries on transient failures, you don’t need to dedupe in the runner.
Listing the executions of a run
curl -H "Authorization: Bearer $TCM_TOKEN" \
$TCM_BASE_URL/api/v1/runs/$RUN_ID/executionsReturns { items: [...] }. Each execution carries the test case’s human ID (TC_0042) and title, so the runner can map them to its own test definitions without a second round-trip.