Testing Strategy

Relevant source files

The following files were used as context for generating this wiki page:

• TEST_PLAN.md
• test_api.sh
• CLAUDE.md
• tests/test_spotify.py
• app/services/audio_analysis_service.py
• IMPROVEMENTS.md

The testing strategy for the MoodTune Backend is designed to ensure the reliability and accuracy of its core functionalities, which include Spotify OAuth integration, playlist mood analysis using librosa, and user data management via Supabase. The strategy encompasses multiple testing tiers: automated unit/integration tests using pytest, manual API verification via curl scripts, and comprehensive frontend integration validation.

This multi-layered approach focuses on verifying that the FastAPI backend correctly handles Supabase JWT authentication, communicates securely with the Spotify Web API, and accurately processes audio features to derive mood classifications like "Happy & Energetic" or "Calm & Melancholic."

Sources: TEST_PLAN.md:3-15, CLAUDE.md:14-25, app/services/audio_analysis_service.py:16-25

Core Testing Tiers

Automated Testing (Pytest)

The primary automated testing framework is pytest. It is used for unit and integration tests, particularly for complex logic like Spotify token refreshing and API response parsing.

• Mocking: Tests utilize monkeypatch to simulate Supabase client responses and Spotify API payloads, ensuring tests remain isolated from external network dependencies.
• Async Support: Tests use @pytest.mark.asyncio to handle the asynchronous nature of the FastAPI service layer.

Sources: CLAUDE.md:19-25, tests/test_spotify.py:12-117

Manual API Testing

For rapid verification of endpoints, the project includes a dedicated shell script test_api.sh. This script automates curl commands to test:

• Health checks (/health)
• Spotify connection status (/spotify/status)
• Playlist retrieval and analysis history

Sources: test_api.sh:1-68

Integration & Security Testing

Integration testing focuses on the end-to-end flow between the frontend, the FastAPI backend, and Supabase Auth. Security testing specifically targets user isolation and CSRF protection via the Spotify OAuth state parameter.

Sources: TEST_PLAN.md:275-300, TEST_PLAN.md:328-348

Test Flow Architectures

Spotify OAuth & Token Flow

The following sequence diagram illustrates the validation of the Spotify OAuth flow, including the critical state verification and token storage process described in the testing documentation.

Audio Analysis Processing

Testing the analysis service involves verifying the data flow from raw audio bytes to mood classification. The process utilizes a librosa-based pipeline.

Key Test Categories & Parameters

Category	Component	Validation Focus
Authentication	Supabase JWT	Verify Authorization: Bearer headers; 401 on invalid, 403 on missing.
Spotify Integration	Token Refresh	Manual update of expires_at in DB to ensure auto-refresh triggers.
Analysis	Playlist Scope	Success for >100 tracks; graceful failure for empty playlists.
Security	User Isolation	User B must receive 403 when accessing User A's analysis ID.
Performance	Concurrent Requests	10+ simultaneous requests to /spotify/status via xargs.

Sources: TEST_PLAN.md:40-60, TEST_PLAN.md:175-182, TEST_PLAN.md:215-230, TEST_PLAN.md:315-325, TEST_PLAN.md:337-348

Analysis Logic Verification

The testing strategy includes specific thresholds to validate the analysis_service.py mood classification logic. Testing must ensure that the results returned by the API align with these internal constants.

# Values defined in app/services/analysis_service.py
THRESHOLDS = {
    "valence": {
        "happy": 0.6,    # >= 0.6 considered happy
        "sad": 0.4,      # < 0.4 considered sad
    },
    "energy": {
        "energetic": 0.6,  # >= 0.6 considered energetic
        "calm": 0.4,       # < 0.4 considered calm
    }
}

Sources: app/services/analysis_service.py:15-28

Planned Improvements to Testing & Quality

Documentation indicates several areas for expanding the testing strategy beyond the current implementation:

• Accuracy Validation: Comparison of results against Spotify's official audio features API.
• Adaptive Normalization: Testing how the service handles varied dynamic ranges using rms.min() and rms.max() instead of fixed values.
• Granular Error Handling: Differentiating between network timeouts and audio processing failures during analysis.

Sources: IMPROVEMENTS.md:7-25, IMPROVEMENTS.md:85-100

The MoodTune Backend Testing Strategy provides a robust framework for ensuring that the intersection of external API integrations (Spotify), authentication providers (Supabase), and internal signal processing (librosa) functions correctly. By combining automated Python tests with manual shell scripting and detailed integration plans, the project maintains high standards for both developer productivity and end-user reliability.