# Manual Testing Guide: Asynchronous Series Data Loading

This guide provides step-by-step instructions for manually testing the asynchronous series data loading feature.

## Prerequisites

1. **Server Running**: Make sure the FastAPI server is running:
   ```bash
   conda run -n AniWorld python -m uvicorn src.server.fastapi_app:app --host 127.0.0.1 --port 8000 --reload
   ```

2. **Browser**: Use a modern browser with developer tools (Chrome/Firefox recommended)

3. **Authentication**: You'll need to be logged in
   - Username: `admin`
   - Password: `Hallo123!`

## Test Scenarios

### Test 1: Immediate Series Visibility

**Objective**: Verify that series appear immediately in the UI when added, even while data loads in background.

**Steps**:
1. Open browser to `http://127.0.0.1:8000`
2. Log in with admin credentials
3. Open browser DevTools (F12) → Network tab
4. Add a new series via search or URL
5. **Expected Results**:
   - API response returns quickly (< 500ms)
   - Response status code is `202 Accepted`
   - Series appears immediately in the series grid
   - Series card shows loading indicator

**Pass Criteria**:
- ✅ Series visible within 1 second of submitting
- ✅ Loading indicator present on series card
- ✅ UI remains responsive

### Test 2: Loading Status Indicators

**Objective**: Verify that loading progress indicators display correctly.

**Steps**:
1. After adding a series (from Test 1), observe the series card
2. Look for the loading indicator section
3. Check the progress items display

**Expected Results**:
- Loading indicator appears below series stats
- Shows spinning icon with status message (e.g., "Loading episodes...")
- Progress items show checkmarks (✓) for completed tasks
- Progress items show dots (⋯) for pending tasks
- Four progress items visible: Episodes, NFO, Logo, Images

**Pass Criteria**:
- ✅ Loading indicator visible
- ✅ Status message updates as loading progresses
- ✅ Progress items accurately reflect completion state
- ✅ Visual distinction between completed and pending items

### Test 3: Real-Time WebSocket Updates

**Objective**: Verify that loading status updates in real-time via WebSocket.

**Steps**:
1. Open browser DevTools → Network tab → WS (WebSocket filter)
2. Ensure WebSocket connection is established
3. Add a new series
4. Monitor WebSocket messages

**Expected Results**:
- WebSocket messages with type `series_loading_update` appear
- Messages contain:
  - `series_id` or `series_key`
  - `status` (loading_episodes, loading_nfo, etc.)
  - `progress` object with boolean flags
  - `message` describing current operation
- Series card updates automatically without page refresh

**Pass Criteria**:
- ✅ WebSocket messages received during loading
- ✅ UI updates in real-time
- ✅ No need to refresh page to see updates
- ✅ Messages contain all required fields

### Test 4: Loading Completion

**Objective**: Verify that loading completes successfully and UI updates accordingly.

**Steps**:
1. Add a series and wait for loading to complete (may take 10-30 seconds)
2. Observe the series card when loading finishes

**Expected Results**:
- Loading indicator disappears when complete
- All progress items show checkmarks
- Series card no longer has "loading" class
- Series data is fully populated (episodes, NFO, etc.)

**Pass Criteria**:
- ✅ Loading indicator removed upon completion
- ✅ Series card shows complete data
- ✅ No errors in browser console
- ✅ Database reflects completed status

### Test 5: Startup Incomplete Series Check

**Objective**: Verify that application checks for incomplete series on startup.

**Steps**:
1. Add a series (let it start loading)
2. **Stop the server** while loading is in progress:
   ```bash
   pkill -f "uvicorn.*fastapi_app"
   ```
3. Check the database to see incomplete series:
   ```bash
   conda run -n AniWorld python -c "
   from src.server.database.service import get_db
   from src.server.database.models import AnimeSeries
   from sqlalchemy import select
   
   db = next(get_db())
   series = db.execute(
       select(AnimeSeries).where(AnimeSeries.loading_status != 'completed')
   ).scalars().all()
   
   for s in series:
       print(f'{s.key}: {s.loading_status}')
   "
   ```
4. **Restart the server**
5. Check server logs for startup messages

**Expected Results**:
- Server logs show: "Found X series with missing data. Starting background loading..."
- Incomplete series are automatically queued for loading
- Loading resumes for incomplete series

**Pass Criteria**:
- ✅ Startup logs mention incomplete series
- ✅ Loading resumes automatically
- ✅ Incomplete series complete successfully

### Test 6: Multiple Concurrent Series

**Objective**: Verify that multiple series can load concurrently without blocking.

**Steps**:
1. Rapidly add 3-5 series (within a few seconds)
2. Observe all series cards

**Expected Results**:
- All series appear immediately in UI
- All series show loading indicators
- Loading progresses for multiple series simultaneously
- UI remains responsive during loading
- No series blocks others from loading

**Pass Criteria**:
- ✅ All series visible immediately
- ✅ All series show loading indicators
- ✅ No UI freezing or blocking
- ✅ All series complete loading successfully

### Test 7: Error Handling

**Objective**: Verify that errors are handled gracefully.

**Steps**:
1. **Simulate an error scenario**:
   - Add a series with invalid URL
   - Or disconnect from internet during loading
2. Observe the series card

**Expected Results**:
- Series card updates to show error state
- Loading status changes to "failed"
- Error message is displayed
- Other series continue loading normally

**Pass Criteria**:
- ✅ Error state visible in UI
- ✅ Error doesn't crash application
- ✅ Other series unaffected
- ✅ Error message is informative

### Test 8: Database Persistence

**Objective**: Verify that loading status is properly persisted to database.

**Steps**:
1. Add a series
2. While loading, check database directly:
   ```bash
   conda run -n AniWorld python -c "
   from src.server.database.service import get_db
   from src.server.database.models import AnimeSeries
   from sqlalchemy import select
   
   db = next(get_db())
   series = db.execute(select(AnimeSeries)).scalars().all()
   
   for s in series:
       print(f'{s.name}:')
       print(f'  Status: {s.loading_status}')
       print(f'  Episodes: {s.episodes_loaded}')
       print(f'  NFO: {s.nfo_loaded}')
       print(f'  Logo: {s.logo_loaded}')
       print(f'  Images: {s.images_loaded}')
       print(f'  Started: {s.loading_started_at}')
       print()
   "
   ```

**Expected Results**:
- Database shows loading_status field
- Boolean flags (episodes_loaded, nfo_loaded, etc.) update as loading progresses
- loading_started_at timestamp is set
- loading_completed_at is set when done

**Pass Criteria**:
- ✅ All new fields present in database
- ✅ Values update during loading
- ✅ Timestamps accurately reflect start/completion

### Test 9: API Endpoints

**Objective**: Verify that new API endpoints work correctly.

**Steps**:
1. Use curl or Postman to test endpoints directly:

   **Add Series (returns 202)**:
   ```bash
   curl -X POST "http://127.0.0.1:8000/api/anime/add" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -d '{"url": "https://aniworld.to/anime/stream/test-series"}'
   ```

   **Get Loading Status**:
   ```bash
   curl "http://127.0.0.1:8000/api/anime/SERIES_KEY/loading-status" \
     -H "Authorization: Bearer YOUR_TOKEN"
   ```

**Expected Results**:
- POST returns 202 Accepted
- Response includes loading_status field
- GET loading-status returns detailed status object
- Status object includes progress breakdown

**Pass Criteria**:
- ✅ POST returns 202 status code
- ✅ Response format matches documentation
- ✅ GET endpoint returns current status
- ✅ All required fields present

### Test 10: CSS Styling

**Objective**: Verify that loading indicators are properly styled.

**Steps**:
1. Add a series with loading indicator visible
2. Inspect the series card with browser DevTools
3. Check CSS classes applied

**Expected Results**:
- `.loading-indicator` class present
- `.loading-status` shows flex layout
- `.progress-items` displays horizontally with gap
- `.progress-item.completed` has success color
- `.progress-item.pending` has tertiary color
- Spinner icon animates

**Pass Criteria**:
- ✅ Loading indicator styled correctly
- ✅ Colors match theme
- ✅ Layout is responsive
- ✅ Icons visible and appropriate size

## Common Issues and Troubleshooting

### Issue: Loading indicator doesn't appear

**Possible Causes**:
- JavaScript error in console
- WebSocket not connected
- CSS not loaded

**Solution**:
1. Check browser console for errors
2. Verify WebSocket connection in Network tab
3. Hard refresh page (Ctrl+Shift+R)

### Issue: Loading never completes

**Possible Causes**:
- Backend service error
- External API unavailable (TMDB, Aniworld)
- Network timeout

**Solution**:
1. Check server logs for errors
2. Verify external services are accessible
3. Check database for error in loading_error field

### Issue: WebSocket updates not working

**Possible Causes**:
- WebSocket connection failed
- Event handler not registered
- Browser console shows errors

**Solution**:
1. Check WebSocket connection status in DevTools
2. Verify `series_loading_update` event handler exists
3. Check for JavaScript errors

## Verification Checklist

After completing all tests, verify:

- [ ] Series appear immediately when added
- [ ] Loading indicators display correctly
- [ ] Real-time updates work via WebSocket
- [ ] Loading completes successfully
- [ ] Startup check finds incomplete series
- [ ] Multiple series load concurrently
- [ ] Errors handled gracefully
- [ ] Database persistence works
- [ ] API endpoints return correct responses
- [ ] CSS styling is correct
- [ ] No errors in browser console
- [ ] No errors in server logs
- [ ] Performance is acceptable (< 1s for add, < 30s for complete load)

## Performance Metrics

Record these metrics during testing:

| Metric | Target | Actual | Pass/Fail |
|--------|--------|--------|-----------|
| Series add response time | < 500ms | | |
| UI update latency | < 100ms | | |
| WebSocket message latency | < 100ms | | |
| Complete loading time | < 30s | | |
| Concurrent series handling | 5+ | | |
| Memory usage increase | < 100MB | | |
| No UI blocking | Yes | | |

## Test Results Summary

**Date**: _________________

**Tester**: _________________

**Pass/Fail**: _________________

**Notes**:
```
(Add any observations, issues found, or additional notes here)
```

## Next Steps

After completing manual testing:

1. ✅ Mark task as complete in instructions.md
2. ✅ Commit test results documentation
3. ✅ Update CHANGELOG.md with new feature
4. ✅ Create user documentation for the feature
5. ✅ Consider performance optimizations if needed
6. ✅ Plan for monitoring in production

## Conclusion

This comprehensive testing ensures the asynchronous series data loading feature works correctly across all scenarios. Report any issues found to the development team with detailed reproduction steps.