Skip to main content

Tests API

Manage automated test suites and track test runs across your fleet.

List Test Suites

GET /organizations/{org_slug}/projects/{project_slug}/test-suites
Returns all test suites in a project.

Response

{
  "items": [
    {
      "id": 1,
      "name": "Integration Tests",
      "description": "End-to-end integration test suite",
      "composition_id": 5,
      "created_at": "2025-01-10T10:00:00Z",
      "updated_at": "2025-01-10T10:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20
}

Get Test Suite

GET /organizations/{org_slug}/projects/{project_slug}/test-suites/{suite_id}
Returns details of a specific test suite.

Create Test Suite

POST /organizations/{org_slug}/projects/{project_slug}/test-suites

Request Body

{
  "name": "Smoke Tests",
  "description": "Quick validation tests",
  "composition_id": 5,
  "timeout_seconds": 300,
  "retry_count": 2
}

Response

{
  "id": 2,
  "name": "Smoke Tests",
  "description": "Quick validation tests",
  "composition_id": 5,
  "timeout_seconds": 300,
  "retry_count": 2,
  "created_at": "2025-01-10T11:00:00Z"
}

Update Test Suite

PATCH /organizations/{org_slug}/projects/{project_slug}/test-suites/{suite_id}

Request Body

{
  "name": "Updated Name",
  "timeout_seconds": 600
}

Delete Test Suite

DELETE /organizations/{org_slug}/projects/{project_slug}/test-suites/{suite_id}
Returns 204 No Content on success.

List Test Runs

GET /organizations/{org_slug}/projects/{project_slug}/test-runs
Returns all test runs, optionally filtered.

Query Parameters

ParameterTypeDescription
suite_idintegerFilter by test suite
device_idintegerFilter by device
statusstringFilter by status: pending, running, passed, failed, error
pageintegerPage number (default: 1)
page_sizeintegerItems per page (default: 20)

Response

{
  "items": [
    {
      "id": 101,
      "test_suite_id": 1,
      "device_id": 42,
      "session_id": 500,
      "status": "passed",
      "started_at": "2025-01-10T12:00:00Z",
      "completed_at": "2025-01-10T12:05:00Z",
      "duration_seconds": 300,
      "results": {
        "total": 10,
        "passed": 10,
        "failed": 0,
        "skipped": 0
      }
    }
  ],
  "total": 50,
  "page": 1,
  "page_size": 20
}

Get Test Run

GET /organizations/{org_slug}/projects/{project_slug}/test-runs/{run_id}
Returns detailed information about a test run, including individual test results.

Response

{
  "id": 101,
  "test_suite_id": 1,
  "device_id": 42,
  "session_id": 500,
  "status": "passed",
  "started_at": "2025-01-10T12:00:00Z",
  "completed_at": "2025-01-10T12:05:00Z",
  "duration_seconds": 300,
  "results": {
    "total": 10,
    "passed": 10,
    "failed": 0,
    "skipped": 0
  },
  "test_cases": [
    {
      "name": "test_connectivity",
      "status": "passed",
      "duration_ms": 150,
      "message": null
    },
    {
      "name": "test_sensor_data",
      "status": "passed",
      "duration_ms": 2500,
      "message": null
    }
  ],
  "logs_url": "/sessions/500/logs",
  "artifacts_url": "/sessions/500/artifacts"
}

Start Test Run

POST /organizations/{org_slug}/projects/{project_slug}/test-runs
Starts a new test run on a device.

Request Body

{
  "test_suite_id": 1,
  "device_id": 42,
  "parameters": {
    "verbose": true,
    "timeout_override": 600
  }
}

Response

{
  "id": 102,
  "test_suite_id": 1,
  "device_id": 42,
  "status": "pending",
  "created_at": "2025-01-10T13:00:00Z"
}

Cancel Test Run

POST /organizations/{org_slug}/projects/{project_slug}/test-runs/{run_id}/cancel
Cancels a running or pending test run.

Response

{
  "id": 102,
  "status": "cancelled",
  "cancelled_at": "2025-01-10T13:01:00Z"
}

Test Run Status Values

StatusDescription
pendingTest run queued, waiting for device
runningTests actively executing
passedAll tests passed
failedOne or more tests failed
errorTest run encountered an error
cancelledTest run was cancelled
timeoutTest run exceeded timeout

Examples

Run tests on a specific device

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"test_suite_id": 1, "device_id": 42}' \
  https://api.roboticks.io/api/v1/organizations/acme/projects/robots/test-runs

Get recent test results

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.roboticks.io/api/v1/organizations/acme/projects/robots/test-runs?status=failed&page_size=10"

Check test run status

curl -H "Authorization: Bearer $TOKEN" \
  https://api.roboticks.io/api/v1/organizations/acme/projects/robots/test-runs/102