ATS Tracker / Installation & Usage Guide

Overview

ATS Tracker is a lightweight server that collects and displays real-time test execution data from Agilitest agents. It provides a web dashboard accessible from any browser and a WebSocket API for live updates.

Requirements

Installation

curl -fSL https://actiontestscript.org/tools/ats-tracker/linux/ats-tracker -o ats-tracker
chmod +x ats-tracker

sudo ./ats-tracker install token=your_secret_token

sudo ./ats-tracker install port=3000 token=your_secret_token retention=10 refresh=5

./ats-tracker status

./ats-tracker port=3000 token=your_secret_token retention=10 refresh=5

Invoke-WebRequest -Uri "https://actiontestscript.org/tools/ats-tracker/windows/ats-tracker.exe" -OutFile ats-tracker.exe

.\ats-tracker.exe install token=your_secret_token

.\ats-tracker.exe install port=3000 token=your_secret_token retention=10 refresh=5

.\ats-tracker.exe status

.\ats-tracker.exe port=3000 token=your_secret_token retention=10 refresh=5

Once installed, open your browser at http://localhost:3000 (or your chosen port) to access the dashboard.

Configuration

ATS Tracker can be configured via command-line arguments, environment variables, or the configuration file.

Configuration file format

The configuration file (ats-tracker.env) uses a simple key-value format:

PORT=3000
TOKEN=7b2e8411-9293-4e4b-84a5-3d5f346e91f1
RETENTION=10
REFRESH=5

Service Management

sudo systemctl status ats-tracker

sudo systemctl start ats-tracker
sudo systemctl stop ats-tracker
sudo systemctl restart ats-tracker

# Last 100 lines
sudo journalctl -u ats-tracker -n 100

# Follow logs in real time
sudo journalctl -u ats-tracker -f

sudo systemctl stop ats-tracker
sudo systemctl disable ats-tracker
sudo rm /etc/systemd/system/ats-tracker.service
sudo systemctl daemon-reload

Get-Service ats-tracker

Start-Service ats-tracker
Stop-Service ats-tracker
Restart-Service ats-tracker

Stop-Service ats-tracker
sc.exe delete ats-tracker

File Locations

Linux

Windows

API Reference

Authentication

Health check

The /status endpoint always responds (no auth required). If a Bearer token is provided, the response indicates whether it is valid:

# Without token
curl -s http://localhost:3000/status
# {"online":true,"authenticated":false}

# With valid token
curl -s -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/status
# {"online":true,"authenticated":true}

Protected endpoints

Endpoints like /data, /api/stats, and /query require a valid Bearer token. Requests without a valid token receive a 401 Unauthorized response:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:3000/data

WebSocket

After connecting to /ws, the client must send an authentication message within 10 seconds:

// Client sends:
{"type": "auth", "token": "YOUR_TOKEN"}

// Server responds:
{"type": "auth_response", "success": true, "refresh": 5}

Troubleshooting

Port already in use

If port 3000 is taken, change it in the configuration or use the port= argument:

./ats-tracker port=8080 token=your_token

Service fails to start (Linux)

# Check logs for errors
sudo journalctl -u ats-tracker -n 50

# Verify config file is readable
sudo cat /etc/ats-tracker/ats-tracker.env

# Verify permissions
ls -la /var/lib/ats-tracker/

Service fails to start (Windows)

# Check service status
Get-Service ats-tracker | Format-List *

# Verify config file
Get-Content "$env:ProgramData\ats-tracker\ats-tracker.env"

Cannot connect to dashboard

• Verify the service is running
• Check your firewall allows the configured port
• Try accessing http://localhost:PORT locally first

401 Unauthorized on API calls

• Ensure you are sending the Authorization: Bearer TOKEN header
• Verify the token matches the one in the configuration file

Reinstall / Upgrade

Download the latest binary and run the install command again. It will stop the existing service, preserve your configuration, and restart with the new version.