Add comprehensive API endpoint tests

tests/api/README.md

@@ -0,0 +1,246 @@
+# API Endpoint Tests
+
+This directory contains comprehensive integration tests for all FastAPI REST API endpoints in the Aniworld web application.
+
+## Test Files
+
+### 1. test_auth_endpoints.py
+
+Tests for authentication API endpoints (`/api/auth/*`):
+
+-   ✅ Master password setup flow
+-   ✅ Login with valid/invalid credentials
+-   ✅ Authentication status checking
+-   ✅ Token-based authentication
+-   ✅ Logout functionality
+-   ⚠️ Rate limiting behavior (some race conditions with trio backend)
+
+**Status**: 1/2 tests passing (asyncio: ✅, trio: ⚠️ rate limiting)
+
+### 2. test_anime_endpoints.py
+
+Tests for anime management API endpoints (`/api/v1/anime/*`):
+
+-   ✅ List anime series with missing episodes
+-   ✅ Get anime series details
+-   ✅ Trigger rescan of local anime library
+-   ✅ Search for anime series
+-   ✅ Unauthorized access handling
+-   ✅ Direct function call tests
+-   ✅ HTTP endpoint integration tests
+
+**Status**: 11/11 tests passing ✅
+
+### 3. test_config_endpoints.py
+
+Tests for configuration API endpoints (`/api/config/*`):
+
+-   ⚠️ Get current configuration
+-   ⚠️ Validate configuration
+-   ⚠️ Update configuration (authenticated)
+-   ⚠️ List configuration backups
+-   ⚠️ Create configuration backup
+-   ⚠️ Restore from backup
+-   ⚠️ Delete backup
+-   ⚠️ Configuration persistence
+
+**Status**: 0/18 tests passing - needs authentication fixes
+
+**Issues**:
+
+-   Config endpoints require authentication but tests need proper auth client fixture
+-   Mock config service may need better integration
+
+### 4. test_download_endpoints.py
+
+Tests for download queue API endpoints (`/api/queue/*`):
+
+-   ⚠️ Get queue status and statistics
+-   ⚠️ Add episodes to download queue
+-   ⚠️ Remove items from queue (single/multiple)
+-   ⚠️ Start/stop/pause/resume queue
+-   ⚠️ Reorder queue items
+-   ⚠️ Clear completed downloads
+-   ⚠️ Retry failed downloads
+-   ✅ Unauthorized access handling (2/2 tests passing)
+
+**Status**: 2/36 tests passing - fixture dependency issues
+
+**Issues**:
+
+-   `authenticated_client` fixture dependency on `mock_download_service` causing setup errors
+-   Authentication rate limiting across test runs
+-   Need proper mocking of download service dependencies
+
+## Test Infrastructure
+
+### Fixtures
+
+#### Common Fixtures
+
+-   `reset_auth_state`: Auto-use fixture that clears rate limiting state between tests
+-   `authenticated_client`: Creates async client with valid JWT token
+-   `client`: Creates unauthenticated async client
+
+#### Service-Specific Fixtures
+
+-   `mock_download_service`: Mocks DownloadService for testing download endpoints
+-   `mock_config_service`: Mocks ConfigService with temporary config files
+-   `temp_config_dir`: Provides temporary directory for config test isolation
+
+### Testing Patterns
+
+#### Async/Await Pattern
+
+All tests use `pytest.mark.anyio` decorator for async test support:
+
+```python
+@pytest.mark.anyio
+async def test_example(authenticated_client):
+    response = await authenticated_client.get("/api/endpoint")
+    assert response.status_code == 200
+```
+
+#### Authentication Testing
+
+Tests use fixture-based authentication:
+
+```python
+@pytest.fixture
+async def authenticated_client():
+    """Create authenticated async client."""
+    if not auth_service.is_configured():
+        auth_service.setup_master_password("TestPass123!")
+
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        r = await client.post("/api/auth/login", json={"password": "TestPass123!"})
+        token = r.json()["access_token"]
+        client.headers["Authorization"] = f"Bearer {token}"
+        yield client
+```
+
+#### Service Mocking
+
+External dependencies are mocked using `unittest.mock`:
+
+```python
+@pytest.fixture
+def mock_download_service():
+    """Mock DownloadService for testing."""
+    with patch("src.server.utils.dependencies.get_download_service") as mock:
+        service = MagicMock()
+        service.get_queue_status = AsyncMock(return_value=QueueStatus(...))
+        mock.return_value = service
+        yield service
+```
+
+## Running Tests
+
+### Run All API Tests
+
+```bash
+conda run -n AniWorld python -m pytest tests/api/ -v
+```
+
+### Run Specific Test File
+
+```bash
+conda run -n AniWorld python -m pytest tests/api/test_auth_endpoints.py -v
+```
+
+### Run Specific Test
+
+```bash
+conda run -n AniWorld python -m pytest tests/api/test_auth_endpoints.py::test_auth_flow_setup_login_status_logout -v
+```
+
+### Run Only Asyncio Tests (Skip Trio)
+
+```bash
+conda run -n AniWorld python -m pytest tests/api/ -v -k "asyncio or not anyio"
+```
+
+### Run with Detailed Output
+
+```bash
+conda run -n AniWorld python -m pytest tests/api/ -v --tb=short
+```
+
+## Current Test Status
+
+### Summary
+
+-   **Total Tests**: 71
+-   **Passing**: 16 (22.5%)
+-   **Failing**: 19 (26.8%)
+-   **Errors**: 36 (50.7%)
+
+### By Category
+
+1. **Anime Endpoints**: 11/11 ✅ (100%)
+2. **Auth Endpoints**: 1/2 ✅ (50%) - trio race condition
+3. **Config Endpoints**: 0/18 ❌ (0%) - authentication issues
+4. **Download Endpoints**: 2/36 ⚠️ (5.6%) - fixture dependency issues
+
+## Known Issues
+
+### 1. Rate Limiting Race Conditions
+
+**Symptom**: Tests fail with 429 (Too Many Requests) when run with trio backend
+**Solution**:
+
+-   Fixed for asyncio by adding `reset_auth_state` fixture
+-   Trio still has timing issues with shared state
+-   Recommend running tests with asyncio only: `-k "asyncio or not anyio"`
+
+### 2. Download Service Fixture Dependencies
+
+**Symptom**: `authenticated_client` fixture fails when it depends on `mock_download_service`
+**Error**: `assert 429 == 200` during login
+**Solution**: Need to refactor fixture dependencies to avoid circular authentication issues
+
+### 3. Config Endpoint Authentication
+
+**Symptom**: Config endpoints return 404 or authentication errors
+**Solution**:
+
+-   ✅ Added config router to fastapi_app.py
+-   ⚠️ Still need to verify authentication requirements and update test fixtures
+
+## Improvements Needed
+
+### High Priority
+
+1. **Fix Download Endpoint Tests**: Resolve fixture dependency issues
+2. **Fix Config Endpoint Tests**: Ensure proper authentication in tests
+3. **Resolve Trio Rate Limiting**: Investigate shared state issues
+
+### Medium Priority
+
+1. **Add More Edge Cases**: Test boundary conditions and error scenarios
+2. **Improve Test Coverage**: Add tests for WebSocket endpoints
+3. **Performance Tests**: Add tests for high-load scenarios
+
+### Low Priority
+
+1. **Test Documentation**: Add more inline documentation
+2. **Test Utilities**: Create helper functions for common test patterns
+3. **CI/CD Integration**: Set up automated test runs
+
+## Contributing
+
+When adding new API endpoint tests:
+
+1. **Follow Existing Patterns**: Use the same fixture and assertion patterns
+2. **Test Both Success and Failure**: Include positive and negative test cases
+3. **Use Proper Fixtures**: Leverage existing fixtures for authentication and mocking
+4. **Document Test Purpose**: Add clear docstrings explaining what each test validates
+5. **Clean Up State**: Use fixtures to ensure tests are isolated and don't affect each other
+
+## References
+
+-   [FastAPI Testing Documentation](https://fastapi.tiangolo.com/tutorial/testing/)
+-   [Pytest Documentation](https://docs.pytest.org/)
+-   [HTTPX AsyncClient Documentation](https://www.python-httpx.org/advanced/)
+-   [Project Coding Guidelines](../../.github/copilot-instructions.md)