Aniworld/docs/MANUAL_TESTING_ASYNC_LOADING.md

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:

   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:

   pkill -f "uvicorn.*fastapi_app"
   

3. Check the database to see incomplete series:

   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:

   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):

   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:

   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.