272 lines
6.3 KiB
Org Mode
272 lines
6.3 KiB
Org Mode
#+TITLE: Asteroid Radio Testing Guide
|
|
#+AUTHOR: Asteroid Radio Development Team
|
|
#+DATE: 2025-10-26
|
|
|
|
* 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
|