---
title: Tests API
description: Complete API reference for managing test cases, test runs, and test results in TraceRTM
---

# Tests API

Test cases verify that requirements are correctly implemented. This API manages test definitions, test executions, and result tracking with full traceability to requirements.

## Endpoints Overview

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/projects/{project_id}/items?type=test_case` | List test cases |
| `POST` | `/v1/projects/{project_id}/items` | Create test case |
| `GET` | `/v1/projects/{project_id}/test-runs` | List test runs |
| `POST` | `/v1/projects/{project_id}/test-runs` | Create test run |
| `GET` | `/v1/projects/{project_id}/test-runs/{run_id}` | Get test run |
| `POST` | `/v1/projects/{project_id}/test-runs/{run_id}/results` | Submit results |
| `GET` | `/v1/projects/{project_id}/test-coverage` | Coverage report |

---

## The Test Case Object

Test cases are items with `type: "test_case"` and additional test-specific fields.

```json
{
  "id": "item_tc_001abc",
  "project_id": "proj_abc123",
  "type": "test_case",
  "item_number": "VCS-TC-001",
  "title": "Verify sensor data processing timing",
  "description": "Verify that sensor data is processed within 10ms under normal load conditions",
  "status": "approved",
  "priority": "critical",
  "test_type": "automated",
  "test_level": "integration",
  "preconditions": "System initialized and sensors connected",
  "steps": [
    {
      "step_number": 1,
      "action": "Send 100 sensor readings at 100Hz",
      "expected_result": "All readings queued for processing"
    },
    {
      "step_number": 2,
      "action": "Measure processing time for each reading",
      "expected_result": "All processing times < 10ms"
    },
    {
      "step_number": 3,
      "action": "Verify output values are correct",
      "expected_result": "Output matches expected calculations"
    }
  ],
  "postconditions": "System returns to idle state",
  "test_data": {
    "input_file": "sensor_test_data.csv",
    "expected_output": "expected_results.json"
  },
  "estimated_duration_minutes": 15,
  "automation_id": "test_timing_001",
  "tags": ["performance", "timing", "automated"],
  "custom_fields": {
    "test_environment": "HIL",
    "safety_level": "ASIL-D"
  },
  "version": 2,
  "created_at": "2024-02-01T10:00:00Z",
  "updated_at": "2024-10-15T14:22:00Z"
}
```

### Test Case Fields

| Field | Type | Description |
|-------|------|-------------|
| `test_type` | string | `manual`, `automated`, `hybrid` |
| `test_level` | string | `unit`, `integration`, `system`, `acceptance` |
| `preconditions` | string | Setup requirements |
| `steps` | array | Test procedure steps |
| `postconditions` | string | Cleanup requirements |
| `test_data` | object | Test data references |
| `estimated_duration_minutes` | integer | Expected execution time |
| `automation_id` | string | External automation system reference |

---

## The Test Run Object

A test run is an execution of one or more test cases.

```json
{
  "id": "run_abc123xyz",
  "project_id": "proj_abc123",
  "name": "Sprint 24 Regression",
  "description": "Full regression test for sprint 24 release",
  "status": "in_progress",
  "environment": {
    "name": "staging",
    "version": "2.4.0-rc1",
    "build_number": "4521",
    "config": {
      "os": "Linux 5.15",
      "hardware": "HIL Rack 3"
    }
  },
  "test_cases": [
    "item_tc_001",
    "item_tc_002",
    "item_tc_003"
  ],
  "statistics": {
    "total": 150,
    "passed": 120,
    "failed": 8,
    "blocked": 5,
    "skipped": 2,
    "not_run": 15,
    "pass_rate": 80.0
  },
  "started_at": "2024-12-01T09:00:00Z",
  "completed_at": null,
  "created_by": "user_qa_lead",
  "created_at": "2024-12-01T08:30:00Z"
}
```

### Test Run Status

| Status | Description |
|--------|-------------|
| `planned` | Run created, not started |
| `in_progress` | Execution in progress |
| `completed` | All tests executed |
| `aborted` | Run stopped early |

---

## The Test Result Object

Individual test execution results.

```json
{
  "id": "result_xyz789",
  "run_id": "run_abc123xyz",
  "test_case_id": "item_tc_001",
  "status": "passed",
  "executed_by": "user_tester123",
  "executed_at": "2024-12-01T10:15:00Z",
  "duration_seconds": 847,
  "step_results": [
    {
      "step_number": 1,
      "status": "passed",
      "actual_result": "All 100 readings queued successfully",
      "notes": null
    },
    {
      "step_number": 2,
      "status": "passed",
      "actual_result": "Max processing time: 8.2ms, Avg: 4.5ms",
      "notes": "Well within tolerance"
    },
    {
      "step_number": 3,
      "status": "passed",
      "actual_result": "All outputs matched expected values",
      "notes": null
    }
  ],
  "defects": [],
  "attachments": [
    {
      "id": "attach_001",
      "name": "timing_log.txt",
      "size_bytes": 15234,
      "url": "https://..."
    }
  ],
  "notes": "Executed on HIL Rack 3, firmware v2.4.0-rc1"
}
```

### Result Status Values

| Status | Description |
|--------|-------------|
| `passed` | Test executed successfully |
| `failed` | Test failed verification |
| `blocked` | Cannot execute (dependency issue) |
| `skipped` | Intentionally not executed |
| `not_run` | Not yet executed |

---

## List Test Cases

Retrieve test cases from a project.

```http
GET /v1/projects/{project_id}/items?type=test_case
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `type` | string | — | Must be `test_case` |
| `test_type` | string | — | Filter: `manual`, `automated`, `hybrid` |
| `test_level` | string | — | Filter: `unit`, `integration`, `system`, `acceptance` |
| `status` | string | — | Filter by workflow status |
| `verifies` | string | — | Filter by linked requirement ID |
| `sort` | string | `updated_at` | Sort field |
| `limit` | integer | 20 | Results per page |

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/items?type=test_case&test_type=automated&limit=20" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

### SDK Examples

#### Python

```python
# List automated test cases
test_cases = client.items.list(
    project_id="proj_abc123",
    type="test_case",
    test_type="automated"
)

for tc in test_cases.data:
    print(f"{tc.item_number}: {tc.title}")

# Find tests for a requirement
tests_for_req = client.items.list(
    project_id="proj_abc123",
    type="test_case",
    verifies="item_req_001"
)
```

#### TypeScript

```typescript
// List automated test cases
const testCases = await client.items.list({
  projectId: 'proj_abc123',
  type: 'test_case',
  testType: 'automated'
});

testCases.data.forEach(tc => {
  console.log(`${tc.itemNumber}: ${tc.title}`);
});
```

---

## Create Test Case

Create a new test case.

```http
POST /v1/projects/{project_id}/items
```

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/items" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "test_case",
    "title": "Verify emergency stop response time",
    "description": "Verify system responds to emergency stop within 50ms",
    "priority": "critical",
    "test_type": "automated",
    "test_level": "system",
    "preconditions": "System in operational mode, motor running",
    "steps": [
      {
        "step_number": 1,
        "action": "Trigger emergency stop signal",
        "expected_result": "E-stop signal registered"
      },
      {
        "step_number": 2,
        "action": "Measure time to motor stop command",
        "expected_result": "Command issued within 50ms"
      },
      {
        "step_number": 3,
        "action": "Verify motor state",
        "expected_result": "Motor stopped, brake engaged"
      }
    ],
    "postconditions": "Reset emergency stop, verify system recoverable",
    "estimated_duration_minutes": 10,
    "tags": ["safety", "timing", "emergency"],
    "custom_fields": {
      "safety_level": "ASIL-D",
      "test_environment": "HIL"
    }
  }'
```

### SDK Examples

#### Python

```python
test_case = client.items.create(
    project_id="proj_abc123",
    type="test_case",
    title="Verify emergency stop response time",
    test_type="automated",
    test_level="system",
    preconditions="System in operational mode",
    steps=[
        {
            "step_number": 1,
            "action": "Trigger emergency stop signal",
            "expected_result": "E-stop signal registered"
        },
        {
            "step_number": 2,
            "action": "Measure response time",
            "expected_result": "Response within 50ms"
        }
    ],
    postconditions="Reset and verify recovery",
    priority="critical",
    tags=["safety", "timing"]
)

print(f"Created test case: {test_case.item_number}")
```

---

## List Test Runs

Retrieve test runs for a project.

```http
GET /v1/projects/{project_id}/test-runs
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `status` | string | — | Filter by run status |
| `environment` | string | — | Filter by environment name |
| `created_after` | string | — | Created after ISO date |
| `created_before` | string | — | Created before ISO date |
| `sort` | string | `created_at` | Sort field |
| `order` | string | `desc` | Sort order |
| `limit` | integer | 20 | Results per page |

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/test-runs?status=completed&limit=10" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

### Response

```json
{
  "data": [
    {
      "id": "run_abc123xyz",
      "name": "Sprint 24 Regression",
      "status": "completed",
      "environment": {"name": "staging", "version": "2.4.0"},
      "statistics": {
        "total": 150,
        "passed": 142,
        "failed": 5,
        "blocked": 2,
        "skipped": 1,
        "pass_rate": 94.7
      },
      "started_at": "2024-12-01T09:00:00Z",
      "completed_at": "2024-12-01T17:30:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 10,
    "has_next": true
  }
}
```

### SDK Examples

#### Python

```python
runs = client.test_runs.list(
    project_id="proj_abc123",
    status="completed"
)

for run in runs.data:
    print(f"{run.name}: {run.statistics.pass_rate}% pass rate")
```

---

## Create Test Run

Create a new test run.

```http
POST /v1/projects/{project_id}/test-runs
```

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Run name |
| `description` | string | No | Run description |
| `test_cases` | array | No | Specific test case IDs (default: all) |
| `environment` | object | No | Environment configuration |
| `filter` | object | No | Filter to select test cases |

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/test-runs" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Release 2.5.0 Certification",
    "description": "Full certification test suite for release 2.5.0",
    "environment": {
      "name": "certification",
      "version": "2.5.0",
      "build_number": "4789",
      "config": {
        "os": "Linux 5.15",
        "hardware": "Production ECU"
      }
    },
    "filter": {
      "type": "test_case",
      "status": "approved",
      "tags": ["certification"]
    }
  }'
```

### Response

```json
{
  "data": {
    "id": "run_cert250",
    "project_id": "proj_abc123",
    "name": "Release 2.5.0 Certification",
    "status": "planned",
    "environment": {
      "name": "certification",
      "version": "2.5.0",
      "build_number": "4789"
    },
    "test_cases": ["item_tc_001", "item_tc_002", "..."],
    "statistics": {
      "total": 200,
      "passed": 0,
      "failed": 0,
      "blocked": 0,
      "skipped": 0,
      "not_run": 200,
      "pass_rate": 0
    },
    "created_by": "user_qa_lead",
    "created_at": "2024-12-08T10:00:00Z"
  }
}
```

### SDK Examples

#### Python

```python
run = client.test_runs.create(
    project_id="proj_abc123",
    name="Release 2.5.0 Certification",
    description="Full certification test suite",
    environment={
        "name": "certification",
        "version": "2.5.0",
        "build_number": "4789"
    },
    filter={
        "status": "approved",
        "tags": ["certification"]
    }
)

print(f"Created run {run.id} with {run.statistics.total} tests")
```

#### TypeScript

```typescript
const run = await client.testRuns.create({
  projectId: 'proj_abc123',
  name: 'Release 2.5.0 Certification',
  environment: {
    name: 'certification',
    version: '2.5.0'
  },
  filter: {
    status: 'approved',
    tags: ['certification']
  }
});

console.log(`Created run ${run.id} with ${run.statistics.total} tests`);
```

---

## Get Test Run

Retrieve a test run with detailed results.

```http
GET /v1/projects/{project_id}/test-runs/{run_id}
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `include` | string | — | Include: `results`, `defects` |

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/test-runs/run_abc123?include=results" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

---

## Submit Test Results

Submit execution results for a test run.

```http
POST /v1/projects/{project_id}/test-runs/{run_id}/results
```

### Request Body

```json
{
  "results": [
    {
      "test_case_id": "item_tc_001",
      "status": "passed",
      "duration_seconds": 847,
      "step_results": [
        {"step_number": 1, "status": "passed", "actual_result": "OK"},
        {"step_number": 2, "status": "passed", "actual_result": "8.2ms max"},
        {"step_number": 3, "status": "passed", "actual_result": "Values match"}
      ],
      "notes": "Executed successfully"
    },
    {
      "test_case_id": "item_tc_002",
      "status": "failed",
      "duration_seconds": 123,
      "step_results": [
        {"step_number": 1, "status": "passed"},
        {"step_number": 2, "status": "failed", "actual_result": "Response: 65ms", "notes": "Exceeded 50ms limit"}
      ],
      "defects": ["item_issue_001"],
      "notes": "Timing exceeded threshold"
    }
  ]
}
```

### Request

```bash
curl -X POST "https://api.tracertm.dev/v1/projects/proj_abc123/test-runs/run_abc123/results" \
  -H "Authorization: Bearer rtm_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "results": [
      {
        "test_case_id": "item_tc_001",
        "status": "passed",
        "duration_seconds": 847,
        "notes": "All steps passed"
      }
    ]
  }'
```

### SDK Examples

#### Python

```python
# Submit single result
result = client.test_runs.submit_result(
    project_id="proj_abc123",
    run_id="run_abc123",
    test_case_id="item_tc_001",
    status="passed",
    duration_seconds=847,
    step_results=[
        {"step_number": 1, "status": "passed", "actual_result": "OK"},
        {"step_number": 2, "status": "passed", "actual_result": "8.2ms"}
    ],
    notes="All steps passed"
)

# Submit batch results
results = client.test_runs.submit_results(
    project_id="proj_abc123",
    run_id="run_abc123",
    results=[
        {"test_case_id": "item_tc_001", "status": "passed"},
        {"test_case_id": "item_tc_002", "status": "passed"},
        {"test_case_id": "item_tc_003", "status": "failed", "defects": ["item_issue_001"]}
    ]
)
```

#### TypeScript

```typescript
// Submit result
await client.testRuns.submitResult({
  projectId: 'proj_abc123',
  runId: 'run_abc123',
  testCaseId: 'item_tc_001',
  status: 'passed',
  durationSeconds: 847,
  notes: 'All steps passed'
});
```

---

## Test Coverage Report

Get test coverage analysis for requirements.

```http
GET /v1/projects/{project_id}/test-coverage
```

### Query Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `requirement_type` | string | — | Filter requirements by type |
| `test_run_id` | string | — | Coverage based on specific run |
| `include_details` | boolean | false | Include per-item details |

### Request

```bash
curl "https://api.tracertm.dev/v1/projects/proj_abc123/test-coverage?include_details=true" \
  -H "Authorization: Bearer rtm_live_sk_..."
```

### Response

```json
{
  "data": {
    "project_id": "proj_abc123",
    "summary": {
      "total_requirements": 450,
      "requirements_with_tests": 415,
      "requirements_without_tests": 35,
      "coverage_percent": 92.2,
      "total_tests": 380,
      "tests_executed": 320,
      "execution_percent": 84.2,
      "pass_rate": 95.0
    },
    "by_priority": {
      "critical": {"total": 50, "covered": 50, "coverage": 100.0},
      "high": {"total": 150, "covered": 145, "coverage": 96.7},
      "medium": {"total": 200, "covered": 180, "coverage": 90.0},
      "low": {"total": 50, "covered": 40, "coverage": 80.0}
    },
    "uncovered_requirements": [
      {
        "id": "item_req_445",
        "item_number": "VCS-REQ-445",
        "title": "Performance logging",
        "priority": "low"
      }
    ]
  }
}
```

### SDK Examples

#### Python

```python
coverage = client.test_coverage.get(
    project_id="proj_abc123",
    include_details=True
)

print(f"Coverage: {coverage.summary.coverage_percent}%")
print(f"Uncovered: {len(coverage.uncovered_requirements)} requirements")

for req in coverage.uncovered_requirements:
    print(f"  - {req.item_number}: {req.title}")
```

---

## Error Responses

### Test Run Not Found

```json
{
  "error": {
    "code": "TEST_RUN_NOT_FOUND",
    "message": "Test run 'run_invalid' not found",
    "status": 404
  }
}
```

### Invalid Test Result

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid test result",
    "status": 422,
    "details": {
      "errors": [
        {"field": "status", "message": "Invalid status 'maybe'"},
        {"field": "test_case_id", "message": "Test case not in this run"}
      ]
    }
  }
}
```

---

## Related Documentation

- [Requirements API](/docs/api-reference/rest-api/endpoints/requirements) - Requirement management
- [Links API](/docs/api-reference/rest-api/endpoints/relationships) - Link tests to requirements
- [Reports API](/docs/api-reference/rest-api/endpoints/reports) - Generate test reports
- [Workflows API](/docs/api-reference/rest-api/endpoints/workflows) - Test status transitions
