API & Integration Tests
Relevant source files
The following files were used as context for generating this wiki page:
API and Integration testing in the MoodTune Backend ensures the reliability of the FastAPI endpoints, the correctness of the mood analysis logic, and the seamless integration with external providers like Spotify and Supabase. The testing scope encompasses automated unit/integration tests using pytest, manual endpoint verification via shell scripts, and comprehensive frontend integration strategies.
Sources: TEST_PLAN.md:3-8, CLAUDE.md:14-23
Testing Architecture & Strategy
The project utilizes a multi-layered testing approach to validate the backend's functionality. This includes automated Python tests for core services and manual verification for external OAuth flows.
Automated Testing (Pytest)
The tests/ directory contains Python-based tests designed to be run via pytest. These tests focus on service logic, such as validating Spotify token refreshes and profile retrieval. Mocking is extensively used to simulate external dependencies like the Supabase client and HTTP responses from Spotify.
The diagram shows how pytest uses mocks to isolate backend logic from live external services during automated runs.
Sources: CLAUDE.md:19-23, tests/test_spotify.py:32-132
Manual API Testing (Shell Scripts)
A specialized shell script, test_api.sh, is provided to perform manual integration tests against a running local server. This script uses curl and jq to verify endpoint status, data formats, and error handling for the following modules:
- Health Checks:
/health - Spotify Connectivity:
/spotify/status,/spotify/authorize, and/spotify/playlists - Analysis History:
/analysis/history
Sources: test_api.sh:7-80
External Integrations
Spotify OAuth & Token Management
Integration tests verify the complex OAuth flow, including authorization URL generation, callback handling, and automatic token refreshes.
| Test Case | Purpose | Source File |
|---|---|---|
| Token Refresh | Verify expired access tokens are refreshed using the refresh_token | tests/test_spotify.py:32 |
| Auth URL | Ensure client IDs, scopes, and states are correctly injected into Spotify URLs | tests/test_spotify.py:10 |
| Profile Sync | Validate that Spotify user profiles are correctly mapped to internal models | tests/test_spotify.py:114 |
Sources: tests/test_spotify.py:10-132, app/services/spotify_api.py:11-80
Database Integration (Supabase)
Integration tests for the database layer ensure that analysis results and Spotify connection data are persisted correctly. The system uses a service role client to bypass RLS during specific operations while ensuring standard requests adhere to user-based isolation.
This sequence demonstrates the data flow during a playlist analysis integration test.
Sources: app/api/v1/analysis.py:65-125, app/services/spotify_api.py:11-40
Endpoint Verification
Analysis Endpoints
Testing for analysis endpoints focuses on both playlist-level and individual song-level processing.
- Playlist Analysis: Tests ensure the system fetches up to 100 tracks, applies mood thresholds (e.g., valence ≥ 0.6 for "Happy"), and calculates confidence scores based on distance from the neutral center (0.5, 0.5).
- Song Analysis: Validates file upload constraints (max size, allowed formats) and the
librosaanalysis pipeline for single tracks.
Sources: app/api/v1/analysis.py:65-103, app/api/v1/song_analysis.py:113-172
Error Handling & Security
Test cases are explicitly defined to handle failure modes:
- Authentication: Verification that missing or invalid JWT tokens result in
403 Forbiddenor401 Unauthorizedstatuses. - User Isolation: Security tests confirm that User A cannot access User B's analysis history (
403 Forbidden). - Rate Limiting: Strategies to handle Spotify's
429 Too Many Requestsresponses.
Sources: TEST_PLAN.md:73-89, TEST_PLAN.md:310-325
Execution Environment
To run the integration tests, specific environment variables must be configured to mirror the production (Railway) setup.
| Variable | Description | Source |
|---|---|---|
SUPABASE_URL | Endpoint for the Supabase project | TEST_PLAN.md:12 |
SPOTIFY_CLIENT_ID | OAuth application identifier | TEST_PLAN.md:15 |
BACKEND_CORS_ORIGINS | Allowed frontend origins | CLAUDE.md:11 |
Sources: TEST_PLAN.md:11-20, CLAUDE.md:7-12
Running Tests Locally
# Automated tests
pytest tests/ -v
# Manual API script
./test_api.sh YOUR_SUPABASE_JWT_TOKEN
Sources: CLAUDE.md:20, test_api.sh:2
The API and integration testing suite provides a robust framework for maintaining the MoodTune Backend, ensuring that changes to the librosa analysis or Spotify API integration do not regress core functionality.