1  #+TITLE: Asteroid Radio Testing Guide
  2  #+AUTHOR: Asteroid Radio Development Team
  3  #+DATE: 2025-10-26
  4  
  5  * Overview
  6  
  7  This document describes the automated testing system for Asteroid Radio.
  8  
  9  #+BEGIN_QUOTE
 10  *Note on Package Managers*: Examples use =apt= (Debian/Ubuntu). Replace with your distribution's package manager (=dnf=, =pacman=, =zypper=, =apk=, etc.).
 11  #+END_QUOTE
 12  
 13  * Test Script
 14  
 15  The =test-server.sh= script provides comprehensive testing of all server endpoints and functionality.
 16  
 17  ** Features
 18  
 19  - Tests all API endpoints (15 endpoints)
 20  - Tests HTML page rendering (5 pages)
 21  - Tests static file serving
 22  - Validates JSON response format
 23  - Color-coded output for easy reading
 24  - Detailed pass/fail reporting
 25  - Verbose mode for debugging
 26  
 27  ** Usage
 28  
 29  *** Basic Usage
 30  #+BEGIN_SRC bash
 31  # Test local server (default: http://localhost:8080)
 32  ./test-server.sh
 33  
 34  # Verbose mode (shows response details)
 35  ./test-server.sh -v
 36  
 37  # Test remote server
 38  ./test-server.sh -u http://example.com
 39  
 40  # Show help
 41  ./test-server.sh -h
 42  #+END_SRC
 43  
 44  *** Environment Variables
 45  #+BEGIN_SRC bash
 46  # Set base URL via environment
 47  ASTEROID_URL=http://example.com ./test-server.sh
 48  
 49  # Enable verbose mode
 50  VERBOSE=1 ./test-server.sh
 51  #+END_SRC
 52  
 53  ** Test Categories
 54  
 55  *** 1. Server Status
 56  - Server accessibility check
 57  - API response format validation
 58  
 59  *** 2. Status Endpoints
 60  - =/api/asteroid/status= - Server status
 61  - =/api/asteroid/auth-status= - Authentication status
 62  - =/api/asteroid/icecast-status= - Icecast streaming status
 63  
 64  *** 3. Track Endpoints
 65  - =/api/asteroid/tracks= - Track listing
 66  - =/api/asteroid/admin/tracks= - Admin track listing
 67  
 68  *** 4. Player Control Endpoints
 69  - =/api/asteroid/player/status= - Player status
 70  - =/api/asteroid/player/play= - Play track
 71  - =/api/asteroid/player/pause= - Pause playback
 72  - =/api/asteroid/player/stop= - Stop playback
 73  - =/api/asteroid/player/resume= - Resume playback
 74  
 75  *** 5. Playlist Endpoints
 76  - =/api/asteroid/playlists= - Playlist listing
 77  - =/api/asteroid/playlists/create= - Create playlist
 78  - =/api/asteroid/playlists/add-track= - Add track to playlist
 79  - =/api/asteroid/playlists/get= - Get playlist details
 80  
 81  *** 6. Admin Endpoints
 82  - =/api/asteroid/admin/tracks= - Admin track listing
 83  - =/api/asteroid/admin/scan-library= - Library scan
 84  
 85  *** 7. HTML Pages
 86  - =/asteroid/= - Front page
 87  - =/asteroid/admin= - Admin dashboard
 88  - =/asteroid/player= - Web player
 89  - =/asteroid/profile= - User profile
 90  - =/asteroid/register= - Registration page
 91  
 92  *** 8. Static Files
 93  - CSS files (=/asteroid/static/*.css=)
 94  - JavaScript files (=/asteroid/static/js/*.js=)
 95  
 96  ** Example Output
 97  
 98  #+BEGIN_EXAMPLE
 99  ╔═══════════════════════════════════════╗
100  ║  Asteroid Radio Server Test Suite    ║
101  ╔═══════════════════════════════════════╗
102  
103  INFO: Testing server at: http://localhost:8080
104  INFO: Verbose mode: 0
105  
106  ========================================
107  Checking Server Status
108  ========================================
109  
110  TEST: Server is accessible
111  ✓ PASS: Server is running at http://localhost:8080
112  
113  ========================================
114  Testing API Response Format
115  ========================================
116  
117  TEST: API returns JSON format
118  ✓ PASS: API returns JSON (not S-expressions)
119  
120  ========================================
121  Testing Status Endpoints
122  ========================================
123  
124  TEST: Server status endpoint
125  ✓ PASS: Server status endpoint - Response contains 'asteroid-radio'
126  
127  TEST: Authentication status endpoint
128  ✓ PASS: Authentication status endpoint - Response contains 'loggedIn'
129  
130  ...
131  
132  ========================================
133  Test Summary
134  ========================================
135  
136  Tests Run:    25
137  Tests Passed: 25
138  Tests Failed: 0
139  
140  ✓ All tests passed!
141  #+END_EXAMPLE
142  
143  ** Exit Codes
144  
145  - =0= - All tests passed
146  - =1= - One or more tests failed or server not accessible
147  
148  ** Requirements
149  
150  *** Required
151  - =bash= - Shell script interpreter
152  - =curl= - HTTP client for testing endpoints
153  
154  *** Optional
155  - =jq= - JSON processor for advanced JSON validation (recommended)
156  
157  Install jq:
158  #+BEGIN_SRC bash
159  # Ubuntu/Debian
160  sudo apt install jq
161  
162  # macOS
163  brew install jq
164  #+END_SRC
165  
166  ** Integration with CI/CD
167  
168  The test script can be integrated into continuous integration pipelines:
169  
170  #+BEGIN_SRC yaml
171  # Example GitHub Actions workflow
172  - name: Start Asteroid Server
173    run: ./asteroid &
174    
175  - name: Wait for server
176    run: sleep 5
177  
178  - name: Run tests
179    run: ./test-server.sh
180  #+END_SRC
181  
182  ** Extending the Tests
183  
184  To add new tests, edit =test-server.sh= and add test functions:
185  
186  #+BEGIN_SRC bash
187  test_my_new_feature() {
188      print_header "Testing My New Feature"
189      
190      test_api_endpoint "/my-endpoint" \
191          "My endpoint description" \
192          "expected-field"
193  }
194  
195  # Add to main() function
196  main() {
197      # ... existing tests ...
198      test_my_new_feature
199      # ...
200  }
201  #+END_SRC
202  
203  ** Troubleshooting
204  
205  *** Server not accessible
206  - Ensure server is running: =./asteroid=
207  - Check server is on correct port: =8080=
208  - Verify firewall settings
209  
210  *** Tests failing
211  - Run with verbose mode: =./test-server.sh -v=
212  - Check server logs for errors
213  - Verify database is initialized
214  - Ensure all dependencies are installed
215  
216  *** JSON format issues
217  - Verify JSON API format is configured in =asteroid.lisp=
218  - Check =define-api-format json= is defined
219  - Ensure =*default-api-format*= is set to ="json"=
220  
221  * Manual Testing Checklist
222  
223  For features not covered by automated tests:
224  
225  ** Authentication
226  - [ ] Login with admin/asteroid123
227  - [ ] Logout functionality
228  - [ ] Session persistence
229  - [ ] Protected pages redirect to login
230  
231  ** Music Library
232  - [ ] Scan library adds tracks
233  - [ ] Track metadata displays correctly
234  - [ ] Audio streaming works
235  - [ ] Search and filter tracks
236  
237  ** Playlists
238  - [ ] Create new playlist
239  - [ ] Add tracks to playlist
240  - [ ] Load playlist
241  - [ ] Delete playlist
242  
243  ** Player
244  - [ ] Play/pause/stop controls work
245  - [ ] Track progress updates
246  - [ ] Queue management
247  - [ ] Volume control
248  
249  ** Admin Features
250  - [ ] View all tracks
251  - [ ] Scan library
252  - [ ] User management
253  - [ ] System status monitoring
254  
255  * Performance Testing
256  
257  For load testing and performance validation:
258  
259  #+BEGIN_SRC bash
260  # Simple load test with Apache Bench
261  ab -n 1000 -c 10 http://localhost:8080/api/asteroid/tracks
262  
263  # Or with wrk
264  wrk -t4 -c100 -d30s http://localhost:8080/api/asteroid/tracks
265  #+END_SRC
266  
267  * Security Testing
268  
269  ** API Security Checklist
270  - [ ] Authentication required for protected endpoints
271  - [ ] Authorization checks for admin endpoints
272  - [ ] SQL injection prevention
273  - [ ] XSS protection in templates
274  - [ ] CSRF token validation
275  - [ ] Rate limiting on API endpoints