MusicAnalyser/backend/TESTING.md

Testing Guide

This project includes a comprehensive test suite to verify the calculation engine (StatsService) and the AI narrative generation (NarrativeService).

1. Quick Start (Standalone Test)

You can run the full stats verification script without installing pytest. This script uses an in-memory SQLite database, seeds it with synthetic listening history (including skips, sessions, and specific genres), and prints the computed analysis JSON.

# Ensure you are in the root directory
# If you are using the virtual environment:
source backend/venv/bin/activate

# Run the test
python backend/tests/test_stats_full.py

What does this verify?

• Volume Metrics: Total plays, unique tracks/artists.
• Session Logic: Correctly groups plays into sessions based on 20-minute gaps.
• Skip Detection: Identifies "boredom skips" based on timestamp deltas.
• Vibe Analysis: Verifies K-Means clustering, tempo zones, and harmonic profiles.
• Context Analysis: Checks if plays are correctly attributed to Playlists/Albums.

2. Generating a Spotify Refresh Token

To run the actual application, you need a Spotify Refresh Token. We provide a script to automate the OAuth flow.

1. Prerequisites:

   • Go to Spotify Developer Dashboard.
   • Create an App.
   • In settings, add http://localhost:8888/callback to "Redirect URIs".
   • Get your Client ID and Client Secret.

2. Run the Script:

   python backend/scripts/get_refresh_token.py
   

3. Follow Instructions:

   • Enter your Client ID/Secret when prompted.
   • The script will open your browser.
   • Log in to Spotify and authorize the app.
   • The script will print your SPOTIFY_REFRESH_TOKEN in the terminal.

4. Save to .env: Copy the output into your .env file.

3. Full Test Suite (Pytest)

If you wish to run the full suite using pytest (recommended for CI/CD), install the dev dependencies:

pip install pytest

Then run:

pytest backend/tests

4. Manual Verification

To verify the system end-to-end with real data:

1. Start the backend:

   python backend/run_worker.py
   

2. Wait for a few minutes for data to ingest (check logs).
3. Run the analysis manually:

   python backend/run_analysis.py
   

4. Check the database or logs for the generated AnalysisSnapshot.