testarena/doc/api.md

TestArena API Reference

TestArena provides a RESTful API for programmatic job submission and status monitoring.

Base URL

All API endpoints are prefixed with /api.

http://<your-server>/api

Authentication

The API uses Basic Authentication. You must provide your username and password in the request body for job submission.

Endpoints

1. Submit Job

Submit a new test job to the queue.

• URL: /submit_job
• Method: POST
• Content-Type: application/json

Request Body

Field	Type	Required	Description
username	string	Yes	Your TestArena username
password	string	Yes	Your TestArena password
branch_name	string	Yes	Git branch name to test
scenarios	array	Yes	List of scenario names to execute

Example Request

curl -X POST http://localhost:5000/api/submit_job \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "your_password",
    "branch_name": "feature/new-driver",
    "scenarios": ["adc_init_test", "gpio_init_test"]
  }'

Success Response

Code: 200 OK

{
  "success": true,
  "job_id": 123,
  "status": "waiting",
  "remote_triggered": true,
  "message": "Job submitted successfully"
}

Error Response

Code: 401 Unauthorized

{
  "error": "Invalid credentials"
}

Code: 400 Bad Request

{
  "error": "Missing required fields: username, password, branch_name, scenarios"
}

---

2. Get Job Status

Retrieve the status and details of a specific job.

• URL: /job/<job_id>
• Method: GET

URL Parameters

Parameter	Type	Required	Description
job_id	integer	Yes	The ID of the job to retrieve

Example Request

curl http://localhost:5000/api/job/123

Success Response

Code: 200 OK

{
  "job_id": 123,
  "status": "in_progress",
  "branch_name": "feature/new-driver",
  "scenarios": ["adc_init_test", "gpio_init_test"],
  "remote_results": {
    "adc_init_test": ["PASS", "http://.../report.html"],
    "gpio_init_test": ["FAIL", "http://.../report.html"]
  },
  "created_at": "2023-10-27T10:00:00",
  "completed_at": null,
  "remote_queue_id": "123"
}

Error Response

Code: 404 Not Found

{
  "error": "Job not found"
}