# 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.

```bash
# 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](https://developer.spotify.com/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:**
    ```bash
    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:

```bash
pip install pytest
```

Then run:

```bash
pytest backend/tests
```

## 4. Manual Verification

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

1.  Start the backend:
    ```bash
    python backend/run_worker.py
    ```
2.  Wait for a few minutes for data to ingest (check logs).
3.  Run the analysis manually:
    ```bash
    python backend/run_analysis.py
    ```
4.  Check the database or logs for the generated `AnalysisSnapshot`.