testarena/doc/architecture.md

TestArena Architecture Documentation

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.

System Components

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.

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.

Key Workflows

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.

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.

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.

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.

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).