Skip to content
developers
Open TestCollab

Build traceability

GET/builds/{id}/traceability

Aggregated traceability for a build (): execution results summed across every test plan linked to the build, per-plan result distribution, build-scoped risk coverage (risks exercised by test cases executed against the build), and the defects raised against those plans. Powers the Build detail traceability view. The response is provider-neutral — the client chooses the manual vs. Azure DevOps presentation from project settings.

Example

Section titled “Example”

Use resource IDs from your own project. Keep the API token in your server or CI environment.

example.ts
import { createConfiguration, BuildsApi } from '@testcollab/sdk';


const config = createConfiguration(process.env.TESTCOLLAB_TOKEN!);
const api = new BuildsApi(config);


const result = await api.getBuildTraceability({
  "id": 123,
  "project": 123
});
console.log(result);

Parameters

Section titled “Parameters”
Name Location Type Required Description
id path number Yes Build ID
project query number Yes Project ID the build belongs to

Response

Section titled “Response”

200 — Build traceability aggregation

Field Type Required Description
results object Yes Execution results summed across every test plan linked to this build.
results.total number No Total cases across the build’s plans (executed + unexecuted).
results.passed number No —
results.failed number No —
results.blocked number No —
results.skipped number No —
results.unexecuted number No —
results.executed number No Cases with any real (non-unexecuted) status.
results.by_status object No Count keyed by status system_name, including custom project statuses.
results.by_source object No Executed cases keyed by how the result was produced (manual, ci, api, agent, import), plus not_recorded for results predating this being tracked. Answers how much of the build was verified automatically. Only executed cases are counted — an unexecuted case has no producer.
test_plans Array of Build Test Plan Result Yes Test plans that ran against this build, each with its result distribution, followed by plans that are linked to the build but have no run against it (, flagged with linked_only). Only the former contribute to results and to the defect / risk / work-item sections.
risk_coverage Build Risk Coverage Yes —
risk_coverage.total_risks number Yes —
risk_coverage.covered_risks number Yes Risks with at least one linked test case executed against this build.
risk_coverage.uncovered_high_count number Yes High or critical risks with no executed test in this build. Drives the “high risk has no executed test” warning banner.
risk_coverage.risks Array of Build Risk Coverage Item Yes —
defects Array of Build Defect Yes Defects raised against the build’s test plans (built-in issue tracker or connected manager).
defect_summary object Yes Roll-up of the defects raised against the build’s plans.
defect_summary.total number No —
defect_summary.open number No —
defect_summary.closed number No —
work_items Array of Build Work Item Yes Requirements captured by the executed test-case revisions in this build. Metadata is batch-resolved from the local requirements table; no external manager call is made while loading Build traceability.
Illustrative response
{
  "results": {
    "total": 123,
    "passed": 123,
    "failed": 123,
    "blocked": 123,
    "skipped": 123,
    "unexecuted": 123,
    "executed": 123,
    "by_status": {},
    "by_source": {}
  },
  "test_plans": [],
  "risk_coverage": {
    "total_risks": 123,
    "covered_risks": 123,
    "uncovered_high_count": 123,
    "risks": []
  },
  "defects": [],
  "defect_summary": {
    "total": 123,
    "open": 123,
    "closed": 123
  },
  "work_items": []
}

Errors

Section titled “Errors”
Status Meaning
400 Bad request
401 Unauthorized
403 Forbidden
404 Not found
500 Internal server error

Next steps

Section titled “Next steps”