#+TITLE: Asteroid Radio Testing Guide
#+AUTHOR: Cascade AI Assistant
#+DATE: 2025-10-08

* Overview

This document describes the automated testing system for Asteroid Radio.

* Test Script

The =test-server.sh= script provides comprehensive testing of all server endpoints and functionality.

** Features

- Tests all API endpoints (15 endpoints)
- Tests HTML page rendering (5 pages)
- Tests static file serving
- Validates JSON response format
- Color-coded output for easy reading
- Detailed pass/fail reporting
- Verbose mode for debugging

** Usage

*** Basic Usage
#+BEGIN_SRC bash
# Test local server (default: http://localhost:8080)
./test-server.sh

# Verbose mode (shows response details)
./test-server.sh -v

# Test remote server
./test-server.sh -u http://example.com

# Show help
./test-server.sh -h
#+END_SRC

*** Environment Variables
#+BEGIN_SRC bash
# Set base URL via environment
ASTEROID_URL=http://example.com ./test-server.sh

# Enable verbose mode
VERBOSE=1 ./test-server.sh
#+END_SRC

** Test Categories

*** 1. Server Status
- Server accessibility check
- API response format validation

*** 2. Status Endpoints
- =/api/asteroid/status= - Server status
- =/api/asteroid/auth-status= - Authentication status
- =/api/asteroid/icecast-status= - Icecast streaming status

*** 3. Track Endpoints
- =/api/asteroid/tracks= - Track listing
- =/api/asteroid/admin/tracks= - Admin track listing

*** 4. Player Control Endpoints
- =/api/asteroid/player/status= - Player status
- =/api/asteroid/player/play= - Play track
- =/api/asteroid/player/pause= - Pause playback
- =/api/asteroid/player/stop= - Stop playback
- =/api/asteroid/player/resume= - Resume playback

*** 5. Playlist Endpoints
- =/api/asteroid/playlists= - Playlist listing
- =/api/asteroid/playlists/create= - Create playlist
- =/api/asteroid/playlists/add-track= - Add track to playlist
- =/api/asteroid/playlists/get= - Get playlist details

*** 6. Admin Endpoints
- =/api/asteroid/admin/tracks= - Admin track listing
- =/api/asteroid/admin/scan-library= - Library scan

*** 7. HTML Pages
- =/asteroid/= - Front page
- =/asteroid/admin= - Admin dashboard
- =/asteroid/player= - Web player
- =/asteroid/profile= - User profile
- =/asteroid/register= - Registration page

*** 8. Static Files
- CSS files (=/asteroid/static/*.css=)
- JavaScript files (=/asteroid/static/js/*.js=)

** Example Output

#+BEGIN_EXAMPLE
╔═══════════════════════════════════════╗
║  Asteroid Radio Server Test Suite    ║
╔═══════════════════════════════════════╗

INFO: Testing server at: http://localhost:8080
INFO: Verbose mode: 0

========================================
Checking Server Status
========================================

TEST: Server is accessible
✓ PASS: Server is running at http://localhost:8080

========================================
Testing API Response Format
========================================

TEST: API returns JSON format
✓ PASS: API returns JSON (not S-expressions)

========================================
Testing Status Endpoints
========================================

TEST: Server status endpoint
✓ PASS: Server status endpoint - Response contains 'asteroid-radio'

TEST: Authentication status endpoint
✓ PASS: Authentication status endpoint - Response contains 'loggedIn'

...

========================================
Test Summary
========================================

Tests Run:    25
Tests Passed: 25
Tests Failed: 0

✓ All tests passed!
#+END_EXAMPLE

** Exit Codes

- =0= - All tests passed
- =1= - One or more tests failed or server not accessible

** Requirements

*** Required
- =bash= - Shell script interpreter
- =curl= - HTTP client for testing endpoints

*** Optional
- =jq= - JSON processor for advanced JSON validation (recommended)

Install jq:
#+BEGIN_SRC bash
# Ubuntu/Debian
sudo apt install jq

# macOS
brew install jq
#+END_SRC

** Integration with CI/CD

The test script can be integrated into continuous integration pipelines:

#+BEGIN_SRC yaml
# Example GitHub Actions workflow
- name: Start Asteroid Server
  run: ./asteroid &
  
- name: Wait for server
  run: sleep 5

- name: Run tests
  run: ./test-server.sh
#+END_SRC

** Extending the Tests

To add new tests, edit =test-server.sh= and add test functions:

#+BEGIN_SRC bash
test_my_new_feature() {
    print_header "Testing My New Feature"
    
    test_api_endpoint "/my-endpoint" \
        "My endpoint description" \
        "expected-field"
}

# Add to main() function
main() {
    # ... existing tests ...
    test_my_new_feature
    # ...
}
#+END_SRC

** Troubleshooting

*** Server not accessible
- Ensure server is running: =./asteroid=
- Check server is on correct port: =8080=
- Verify firewall settings

*** Tests failing
- Run with verbose mode: =./test-server.sh -v=
- Check server logs for errors
- Verify database is initialized
- Ensure all dependencies are installed

*** JSON format issues
- Verify JSON API format is configured in =asteroid.lisp=
- Check =define-api-format json= is defined
- Ensure =*default-api-format*= is set to ="json"=

* Manual Testing Checklist

For features not covered by automated tests:

** Authentication
- [ ] Login with admin/asteroid123
- [ ] Logout functionality
- [ ] Session persistence
- [ ] Protected pages redirect to login

** Music Library
- [ ] Scan library adds tracks
- [ ] Track metadata displays correctly
- [ ] Audio streaming works
- [ ] Search and filter tracks

** Playlists
- [ ] Create new playlist
- [ ] Add tracks to playlist
- [ ] Load playlist
- [ ] Delete playlist

** Player
- [ ] Play/pause/stop controls work
- [ ] Track progress updates
- [ ] Queue management
- [ ] Volume control

** Admin Features
- [ ] View all tracks
- [ ] Scan library
- [ ] User management
- [ ] System status monitoring

* Performance Testing

For load testing and performance validation:

#+BEGIN_SRC bash
# Simple load test with Apache Bench
ab -n 1000 -c 10 http://localhost:8080/api/asteroid/tracks

# Or with wrk
wrk -t4 -c100 -d30s http://localhost:8080/api/asteroid/tracks
#+END_SRC

* Security Testing

** API Security Checklist
- [ ] Authentication required for protected endpoints
- [ ] Authorization checks for admin endpoints
- [ ] SQL injection prevention
- [ ] XSS protection in templates
- [ ] CSRF token validation
- [ ] Rate limiting on API endpoints