ASF-Nabd/testarena
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

theme

Browse Source
This commit is contained in:
mahmamdouh
2026-01-05 15:41:31 +01:00
parent 67e51a5348
commit 2d81f78fed
3 changed files with 349 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

142
doc/api.md
View File

@@ -1,48 +1,130 @@
# TestArena API Reference
TestArena provides a RESTful API for programmatic job submission and status monitoring.
## Base URL
`http://<server-ip>:8080/api`
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 a New Queue
`POST /queue`
Submits a new set of tasks to the execution queue.
**Payload:**
### 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
```bash
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`
```json
{
"source": "branch_name",
"job_id": [
"environment",
{
"task_id": "scenario_path"
}
]
"success": true,
"job_id": 123,
"status": "waiting",
"remote_triggered": true,
"message": "Job submitted successfully"
}
```
### 2. Get Status
`GET /status/{id}`
Gets the status of a specific queue or task.
#### Error Response
### 3. Abort Queue or Task
`POST /abort/{id}`
Aborts a waiting or running queue or a single task.
**Code**: `401 Unauthorized`
### 4. Delete Queue
`DELETE /delete/{id}`
Permanently deletes a queue and its associated data.
```json
{
"error": "Invalid credentials"
}
```
## Local API (Web App)
**Code**: `400 Bad Request`
### Get Job Details
`GET /jobs/{job_id}`
```json
{
"error": "Missing required fields: username, password, branch_name, scenarios"
}
```
### Get Job Status (Triggers Update)
`GET /jobs/{job_id}/status`
---
### Abort Job
`POST /jobs/{job_id}/abort`
### 2. Get Job Status
### Delete Job
`POST /jobs/{job_id}/delete`
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
```bash
curl http://localhost:5000/api/job/123
```
#### Success Response
**Code**: `200 OK`
```json
{
"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`
```json
{
"error": "Job not found"
}
```

81
doc/architecture.md
View File

@@ -1,41 +1,60 @@
# TestArena Architecture Documentation
# TestArena Architecture
## Overview
TestArena is a web-based test management and execution platform designed to orchestrate test scenarios across different environments. It consists of a Flask-based frontend/backend that communicates with a remote execution server.
TestArena is a web-based platform for managing and executing automated tests on remote hardware setups. It acts as a central hub for users to submit test jobs, monitor execution, and view results.
## System Components
## System Overview
### 1. Web Application (Flask)
- **Frontend**: Built with HTML, CSS (Vanilla), and JavaScript. Provides a dashboard for monitoring jobs, submitting new tests, and viewing logs.
- **Backend**: Flask server handling authentication, job management, and API requests.
- **Database**: PostgreSQL (in Docker) or SQLite. Managed via SQLAlchemy. Stores users and job history.
The system consists of three main layers:
### 2. Remote Execution Server
- Handles the actual execution of test scenarios.
- Exposes APIs for queueing, status polling, and aborting/deleting jobs.
- Provides access to execution logs and results.
1. **Web Frontend (Flask)**:
- Provides the user interface for job submission, dashboard monitoring, and administration.
- Handles user authentication and input validation.
- Exposes REST APIs for programmatic access.
## Key Workflows
2. **Backend Logic (Python/Flask)**:
- **Job Management**: Manages the lifecycle of test jobs (Waiting -> In Progress -> Passed/Failed).
- **Remote Execution**: Communicates with the remote test server via HTTP APIs to trigger queues and poll status.
- **Database**: Uses SQLite (via SQLAlchemy) to store user data, job history, and results.
### Job Submission
1. User selects a branch and validates it via SSH on the remote server.
2. User selects test scenarios to run.
3. User reviews and submits the job.
4. The web app creates a local `Job` record and sends a POST request to the remote `/api/queue` endpoint using the local Job ID as the `remote_queue_id`.
3. **Remote Test Server (External)**:
- Executes the actual test scenarios on hardware/simulators.
- Exposes APIs for queue management (`/api/queue`, `/api/status`, `/api/abort`).
- Hosts the test results and logs.
### Status Polling
1. A background thread in the Flask app polls the remote server every 20 seconds for all `waiting` or `in_progress` jobs.
2. The dashboard also polls the local API every 5 seconds when a job is being viewed to provide real-time updates.
3. Tab persistence is handled in the frontend to ensure the user's view (Scenarios vs Logs) is maintained during polling.
## Key Components
### Job Search (Global)
- Users can search for jobs by **Job ID** or **Username** globally.
- By default, non-admin users only see their own jobs. Searching allows them to see others' jobs if they have the ID or username.
### 1. Job Processing Flow
### Job Abort/Delete
- Users can abort running jobs or delete them entirely. These actions are synchronized with the remote server using the `POST /abort/{id}` and `DELETE /delete/{id}` APIs.
1. **Submission**: User submits a job via UI or API (`POST /api/submit_job`).
2. **Validation**: System validates credentials and branch existence (via SSH).
3. **Queueing**: A local `Job` record is created. The system sends a payload to the Remote Server's `/api/queue` endpoint.
4. **Monitoring**: A background thread in the Flask app polls the Remote Server every 20 seconds.
- Checks Queue Status (`/api/status/<queue_id>`).
- Checks Task Status (`/api/status/<task_id>`).
- Updates local DB with progress and results.
5. **Completion**:
- When all tasks finish, the job is marked as `passed` or `failed`.
- **Cleanup**: An SSH command is automatically executed to clean up the remote workspace.
- **Timeout**: If a job runs > 1 hour, it is auto-aborted.
## Technology Stack
- **Backend**: Python, Flask, Flask-SQLAlchemy, Flask-Login, Requests.
- **Frontend**: HTML5, CSS3, JavaScript (ES6).
- **Remote Communication**: REST API, SSH (for branch validation and scenario scanning).
### 2. Database Schema
- **Users**: `id`, `username`, `password_hash`, `is_admin`
- **Jobs**: `id`, `user_id`, `branch_name`, `scenarios`, `status`, `remote_queue_id`, `remote_results`, `queue_log`
### 3. API Layer
- **`POST /api/submit_job`**: Programmatic job submission.
- **`GET /api/job/<id>`**: Status retrieval.
## Deployment
- **Containerization**: Docker & Docker Compose.
- **Web Server**: Gunicorn (WSGI) behind Caddy (Reverse Proxy/SSL).
- **Database**: SQLite (Persistent volume).
## Security
- **Authentication**: Flask-Login for UI, Basic Auth for API.
- **SSH**: Uses `sshpass` with strict host checking disabled (internal network) for remote operations.
- **Environment**: Secrets managed via `.env` file.