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

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.