From cbcc695f7c6c1aa33db78f62a453d1cc68271b3f Mon Sep 17 00:00:00 2001 From: Camilo Lopez Date: Tue, 12 May 2026 20:29:41 -0500 Subject: [PATCH 01/15] chore(dev): add docker dev setup with local music folder --- CLAUDE.md | 77 ++++++++++++++++++++++++++++++++++++++++++ Dockerfile.dev | 7 ++++ README.md | 31 +++++++++++++++++ docker-compose.dev.yml | 41 ++++++++++++++++++++++ 4 files changed, 156 insertions(+) create mode 100644 CLAUDE.md create mode 100644 Dockerfile.dev create mode 100644 docker-compose.dev.yml diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..6ee3258a9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,77 @@ +# Navidrome — Development Notes + +## Running with Docker Compose + +The dev stack splits the backend and frontend into separate services with hot-reload. + +```bash +# First run (builds Go image, downloads all deps — takes a few minutes) +docker compose -f docker-compose.dev.yml up --build + +# Subsequent runs +docker compose -f docker-compose.dev.yml up +``` + +| Service | Port | Description | +|----------|------|--------------------------------------| +| backend | 4633 | Go server with reflex hot-reload | +| frontend | 4533 | Vite dev server — open this in browser | + +The frontend proxies `/auth`, `/api`, `/rest`, and `/backgrounds` requests to the backend automatically. + +```bash +docker compose -f docker-compose.dev.yml logs -f backend # backend logs +docker compose -f docker-compose.dev.yml logs -f frontend # frontend logs +docker compose -f docker-compose.dev.yml down # stop everything +``` + +## Running without Docker + +```bash +make setup # one-time: installs Go and Node dependencies +make dev # starts both services with hot-reload +``` + +## Database + +Navidrome uses **SQLite only** — there is no Postgres or MySQL support. The database file is persisted in `./data/navidrome.db` (bind-mounted into the container at `/data`). + +### Inspecting the database + +From your host (requires `sqlite3`): + +```bash +sqlite3 ./data/navidrome.db +``` + +From inside the running backend container: + +```bash +docker compose -f docker-compose.dev.yml exec backend sqlite3 /data/navidrome.db +``` + +Useful SQLite commands: + +```sql +.tables -- list all tables +.schema media_file -- show a table's schema +SELECT * FROM user; -- query data +.quit -- exit +``` + +## Configuration + +App config lives in `navidrome.toml`. Environment variables (prefixed `ND_`) override it. The Docker Compose file sets: + +| Variable | Value | +|-----------------------------|-------------------| +| `ND_PORT` | `4633` | +| `ND_MUSICFOLDER` | `/music` | +| `ND_DATAFOLDER` | `/data` | +| `ND_LOGLEVEL` | `info` | +| `ND_ENABLEINSIGHTSCOLLECTOR`| `false` | +| `ND_DEVAUTOCREATEADMINPASSWORD` | `admin` | + +The default dev credentials are **`admin` / `admin`** (set via `ND_DEVAUTOCREATEADMINPASSWORD`). + +The music folder maps to `./music` (project root) inside the container. Drop audio files there and the scanner will pick them up. diff --git a/Dockerfile.dev b/Dockerfile.dev new file mode 100644 index 000000000..2aab902b5 --- /dev/null +++ b/Dockerfile.dev @@ -0,0 +1,7 @@ +FROM golang:1.26 + +RUN apt-get update && apt-get install -y --no-install-recommends \ + sqlite3 libsqlite3-dev \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /workspace diff --git a/README.md b/README.md index 0ae5bdfaf..09dae5368 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,37 @@ please file a [GitHub issue](https://github.com/navidrome/navidrome/issues) or j [themes](https://www.navidrome.org/docs/developers/creating-themes)), please join the chat in our [Discord server](https://discord.gg/xh7j7yF). +## Local Development + +The easiest way to run the full stack locally is with Docker Compose. It starts the Go backend and Vite frontend as separate services with hot-reload enabled. + +**Prerequisites:** Docker and Docker Compose. + +```bash +# First run — builds the Go image and downloads all dependencies +docker compose -f docker-compose.dev.yml up --build + +# Subsequent runs +docker compose -f docker-compose.dev.yml up +``` + +Open **http://localhost:4533**. Default credentials are **`admin` / `admin`**. Drop your audio files into the `music/` folder at the project root — the scanner picks them up automatically. + +```bash +# Run in the background +docker compose -f docker-compose.dev.yml up -d + +# Follow logs +docker compose -f docker-compose.dev.yml logs -f + +# Stop +docker compose -f docker-compose.dev.yml down +``` + +Both services support hot-reload: editing `.go` files restarts the backend via `reflex`, and editing frontend source triggers Vite's HMR. + +> See [CLAUDE.md](CLAUDE.md) for additional development notes, including how to inspect the database. + ## Installation See instructions on the [project's website](https://www.navidrome.org/docs/installation/) diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml new file mode 100644 index 000000000..0d9713896 --- /dev/null +++ b/docker-compose.dev.yml @@ -0,0 +1,41 @@ +services: + backend: + build: + context: . + dockerfile: Dockerfile.dev + ports: + - "4633:4633" + volumes: + - .:/workspace + - ./music:/music:ro + - ./data:/data + - go-mod-cache:/go/pkg/mod + - go-build-cache:/root/.cache/go-build + environment: + ND_PORT: "4633" + ND_MUSICFOLDER: /music + ND_DATAFOLDER: /data + ND_LOGLEVEL: info + ND_ENABLEINSIGHTSCOLLECTOR: "false" + ND_DEVAUTOCREATEADMINPASSWORD: "admin" + command: sh -c "mkdir -p ui/build/3rdparty && touch ui/build/3rdparty/placeholder && go mod download && go tool reflex -d none -c reflex.conf" + + frontend: + image: node:24 + working_dir: /app + ports: + - "4533:4533" + volumes: + - ./ui:/app + - node-modules:/app/node_modules + environment: + PORT: "4533" + BACKEND_HOST: backend + command: sh -c "npm ci && npm start" + depends_on: + - backend + +volumes: + go-mod-cache: + go-build-cache: + node-modules: From 308c98b02ab337cd90aa54956ed856ad1b095a1d Mon Sep 17 00:00:00 2001 From: Camilo Lopez Date: Tue, 12 May 2026 20:46:22 -0500 Subject: [PATCH 02/15] fix: frontend failing and go reflex race condition --- reflex.conf | 2 +- ui/dev-dist/registerSW.js | 1 + ui/vite.config.js | 3 ++- 3 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 ui/dev-dist/registerSW.js diff --git a/reflex.conf b/reflex.conf index 47dd775ab..a5f6183e7 100644 --- a/reflex.conf +++ b/reflex.conf @@ -1 +1 @@ --s -r "(\.go$$|\.cpp$$|\.h$$|navidrome.toml|resources|token_received.html)" -R "(^ui|^data|^db/migrations)" -R "_test\.go$$" -- go run -race -tags netgo,sqlite_fts5 . +-s -r "(\.go$$|\.cpp$$|\.h$$|navidrome.toml|resources|token_received.html)" -R "(^ui|^data|^db/migrations)" -R "_test\.go$$" -- go run -tags netgo,sqlite_fts5 . diff --git a/ui/dev-dist/registerSW.js b/ui/dev-dist/registerSW.js new file mode 100644 index 000000000..1d5625f45 --- /dev/null +++ b/ui/dev-dist/registerSW.js @@ -0,0 +1 @@ +if('serviceWorker' in navigator) navigator.serviceWorker.register('/dev-sw.js?dev-sw', { scope: '/', type: 'classic' }) \ No newline at end of file diff --git a/ui/vite.config.js b/ui/vite.config.js index 9d9c845f1..08f849852 100644 --- a/ui/vite.config.js +++ b/ui/vite.config.js @@ -3,6 +3,7 @@ import react from '@vitejs/plugin-react' import { VitePWA } from 'vite-plugin-pwa' const frontendPort = parseInt(process.env.PORT) || 4533 +const backendHost = process.env.BACKEND_HOST || 'localhost' const backendPort = frontendPort + 100 // https://vitejs.dev/config/ @@ -26,7 +27,7 @@ export default defineConfig({ host: true, port: frontendPort, proxy: { - '^/(auth|api|rest|backgrounds)/.*': 'http://localhost:' + backendPort, + '^/(auth|api|rest|backgrounds)/.*': `http://${backendHost}:${backendPort}`, }, }, base: './', From 182bfce9640b37363503316978d78807e74c2976 Mon Sep 17 00:00:00 2001 From: Camilo Lopez Date: Tue, 12 May 2026 20:52:49 -0500 Subject: [PATCH 03/15] chore: updated readme and add testing-flows.md --- README.md | 35 +++++++++++++++++++++++++++++++++-- testing-flows.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+), 2 deletions(-) create mode 100644 testing-flows.md diff --git a/README.md b/README.md index 09dae5368..51d43614a 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,23 @@ docker compose -f docker-compose.dev.yml up --build docker compose -f docker-compose.dev.yml up ``` -Open **http://localhost:4533**. Default credentials are **`admin` / `admin`**. Drop your audio files into the `music/` folder at the project root — the scanner picks them up automatically. +Open **http://localhost:4533**. + +### Default credentials + +| Username | Password | +|----------|----------| +| `admin` | `admin` | + +### Adding music + +Place your audio files in the `music/` folder at the project root. If the folder doesn't exist yet, create it first: + +```bash +mkdir music +``` + +The scanner picks up new files automatically. ```bash # Run in the background @@ -58,7 +74,22 @@ docker compose -f docker-compose.dev.yml down Both services support hot-reload: editing `.go` files restarts the backend via `reflex`, and editing frontend source triggers Vite's HMR. -> See [CLAUDE.md](CLAUDE.md) for additional development notes, including how to inspect the database. +### Inspecting the database + +Open a SQLite shell inside the running backend container: + +```bash +docker compose -f docker-compose.dev.yml exec backend sqlite3 /data/navidrome.db +``` + +Useful commands once inside: + +```sql +.tables -- list all tables +.schema media_file -- show a table's schema +SELECT * FROM user; -- query data +.quit -- exit +``` ## Installation diff --git a/testing-flows.md b/testing-flows.md new file mode 100644 index 000000000..a959319c5 --- /dev/null +++ b/testing-flows.md @@ -0,0 +1,45 @@ +# Testing Flows + +## Add to Favorites + +Stars a song (or album/artist) using the Subsonic `star` endpoint. + +**Request** + +``` +GET /rest/star +``` + +Query parameters: + +| Parameter | Value | Description | +|-----------|-------|-------------| +| `u` | `admin` | Username | +| `t` | `47b1fbf1aaa6b36d0dec0c8ae0b1a6ef` | Auth token (MD5 of password + salt) | +| `s` | `701805` | Salt used to generate the token | +| `f` | `json` | Response format | +| `v` | `1.8.0` | Subsonic API version | +| `c` | `NavidromeUI` | Client name | +| `id` | `qORBlifrm7cjK4yDgfy5Zy` | ID of the song/album/artist to star | + +**Example request (dev)** + +```bash +curl "http://localhost:4533/rest/star?u=admin&t=47b1fbf1aaa6b36d0dec0c8ae0b1a6ef&s=701805&f=json&v=1.8.0&c=NavidromeUI&id=qORBlifrm7cjK4yDgfy5Zy" +``` + +**Response** + +```json +{ + "subsonic-response": { + "status": "ok", + "version": "1.16.1", + "type": "navidrome", + "serverVersion": "dev", + "openSubsonic": true + } +} +``` + +A `status: "ok"` with no error field means the item was successfully starred. From ebc40c32036938ed5f5ecd6ae1ead5756296ae21 Mon Sep 17 00:00:00 2001 From: oyrodriguez Date: Thu, 14 May 2026 21:06:03 -0500 Subject: [PATCH 04/15] Revisar doc/.. documentacion para tests bd --- docs/DIAGRAMA_ER.md | 238 +++++++++++++ docs/NAVIDROME_ER.drawio | 251 +++++++++++++ docs/NAVIDROME_ER_COMPLETE.drawio | 529 ++++++++++++++++++++++++++++ docs/TEST_PLAN_STAR_ENDPOINT.md | 321 +++++++++++++++++ persistence/annotation_star_test.go | 525 +++++++++++++++++++++++++++ 5 files changed, 1864 insertions(+) create mode 100644 docs/DIAGRAMA_ER.md create mode 100644 docs/NAVIDROME_ER.drawio create mode 100644 docs/NAVIDROME_ER_COMPLETE.drawio create mode 100644 docs/TEST_PLAN_STAR_ENDPOINT.md create mode 100644 persistence/annotation_star_test.go diff --git a/docs/DIAGRAMA_ER.md b/docs/DIAGRAMA_ER.md new file mode 100644 index 000000000..fdb56362d --- /dev/null +++ b/docs/DIAGRAMA_ER.md @@ -0,0 +1,238 @@ +# Diagrama Entidad-Relación: Navidrome + +## Descripción General + +Navidrome es un servidor de música personal con soporte para múltiples usuarios, librerías, playlists, ratings y compartición. El esquema SQLite está optimizado para búsqueda full-text, scrobbling a servicios externos y reproducción streaming. + +## Diagrama ER + +```mermaid +erDiagram + USER ||--o{ ANNOTATION : "rating/stars" + USER ||--o{ PLAYER : "owns" + USER ||--o{ PLAYQUEUE : "has" + USER ||--o{ PLAYLIST : "creates" + USER ||--o{ BOOKMARK : "creates" + USER ||--o{ USER_PROPS : "has" + USER ||--o{ SHARE : "creates" + USER ||--o{ USER_LIBRARY : "accesses" + + ARTIST ||--o{ ALBUM : "releases" + ARTIST ||--o{ MEDIA_FILE : "performs" + ARTIST ||--o{ ARTIST_GENRES : "has" + ARTIST ||--o{ LIBRARY_ARTIST : "belongs_to" + + ALBUM ||--o{ MEDIA_FILE : "contains" + ALBUM ||--o{ ANNOTATION : "rates" + ALBUM ||--o{ ALBUM_GENRES : "categorized" + ALBUM ||--o{ ALBUM_ARTISTS : "has_artists" + + MEDIA_FILE ||--o{ ANNOTATION : "plays" + MEDIA_FILE ||--o{ PLAYLIST_TRACKS : "part_of" + MEDIA_FILE ||--o{ BOOKMARK : "bookmarks" + MEDIA_FILE ||--o{ PLAYQUEUE : "queued" + MEDIA_FILE ||--o{ MEDIA_FILE_GENRES : "categorized" + MEDIA_FILE ||--o{ MEDIA_FILE_ARTISTS : "has_artists" + + PLAYLIST ||--o{ PLAYLIST_TRACKS : "contains" + PLAYLIST_TRACKS ||--o{ MEDIA_FILE : "references" + + GENRE ||--o{ ALBUM_GENRES : "labels" + GENRE ||--o{ MEDIA_FILE_GENRES : "labels" + GENRE ||--o{ ARTIST_GENRES : "labels" + + LIBRARY ||--o{ LIBRARY_ARTIST : "contains" + LIBRARY ||--o{ LIBRARY_TAG : "categorizes" + LIBRARY ||--o{ USER_LIBRARY : "accessed_by" + + FOLDER ||--o{ MEDIA_FILE : "contains" + + TAG ||--o{ LIBRARY_TAG : "is_library_tag" + + PLAYQUEUE ||--o{ MEDIA_FILE : "queue_item" + + PLAYER ||--o{ TRANSCODING : "uses" + + SCROBBLE_BUFFER ||--o{ ANNOTATION : "submit_to_service" + + RADIO : radio_id PK + RADIO : name + RADIO : stream_url + RADIO : homepage_url + + USER : user_id PK + USER : user_name UK + USER : password + USER : is_admin + USER : created_at + + ARTIST : artist_id PK + ARTIST : name + ARTIST : album_count + + ALBUM : album_id PK + ALBUM : name + ALBUM : artist_id FK + ALBUM : year + ALBUM : duration + ALBUM : genre + + MEDIA_FILE : media_file_id PK + MEDIA_FILE : path + MEDIA_FILE : title + MEDIA_FILE : album_id FK + MEDIA_FILE : artist_id FK + MEDIA_FILE : duration + MEDIA_FILE : bit_rate + MEDIA_FILE : created_at + + PLAYLIST : playlist_id PK + PLAYLIST : name + PLAYLIST : owner FK "user_id" + PLAYLIST : public + PLAYLIST : created_at + + PLAYLIST_TRACKS : playlist_id FK + PLAYLIST_TRACKS : media_file_id FK + PLAYLIST_TRACKS : track_position + + ANNOTATION : user_id FK + ANNOTATION : item_id + ANNOTATION : item_type + ANNOTATION : play_count + ANNOTATION : rating + ANNOTATION : starred + + PLAYER : player_id PK + PLAYER : user_id FK + PLAYER : name + + PLAYQUEUE : playqueue_id PK + PLAYQUEUE : user_id FK + PLAYQUEUE : media_file_id FK + PLAYQUEUE : current_index + + BOOKMARK : bookmark_id PK + BOOKMARK : user_id FK + BOOKMARK : media_file_id FK + BOOKMARK : position + + TRANSCODING : transcoding_id PK + TRANSCODING : name + TRANSCODING : target_format + + GENRE : genre_id PK + GENRE : name + + ALBUM_GENRES : album_id FK + ALBUM_GENRES : genre_id FK + + MEDIA_FILE_GENRES : media_file_id FK + MEDIA_FILE_GENRES : genre_id FK + + ARTIST_GENRES : artist_id FK + ARTIST_GENRES : genre_id FK + + LIBRARY : library_id PK + LIBRARY : name + LIBRARY : path + + LIBRARY_ARTIST : library_id FK + LIBRARY_ARTIST : artist_id FK + + LIBRARY_TAG : library_id FK + LIBRARY_TAG : tag_id FK + + USER_LIBRARY : user_id FK + USER_LIBRARY : library_id FK + + TAG : tag_id PK + TAG : name + + FOLDER : folder_id PK + FOLDER : path + FOLDER : parent_path + + ALBUM_ARTISTS : album_id FK + ALBUM_ARTISTS : artist_id FK + + MEDIA_FILE_ARTISTS : media_file_id FK + MEDIA_FILE_ARTISTS : artist_id FK + + SHARE : share_id PK + SHARE : name + SHARE : resource_type + SHARE : created_by FK "user_id" + + SCROBBLE_BUFFER : scrobble_id PK + SCROBBLE_BUFFER : user_id FK + SCROBBLE_BUFFER : media_file_id FK + + USER_PROPS : user_id FK + USER_PROPS : property_name +``` + +## Dominios Principales + +### 🔐 Usuarios & Acceso +- **USER**: Información de usuarios del sistema (admin, credenciales, timestamps) +- **USER_PROPS**: Propiedades personalizadas de cada usuario +- **PLAYER**: Reproductores/dispositivos registrados por usuario +- **USER_LIBRARY**: Control de acceso a librerías + +### 🎵 Contenido Musical +- **ARTIST**: Artistas individuales +- **ALBUM**: Álbumes con metadatos (año, duración, género) +- **MEDIA_FILE**: Canciones/archivos de audio (path, bitrate, duration) +- **FOLDER**: Estructura de carpetas del sistema de archivos +- **GENRE**: Géneros musicales + +### 🏷️ Relaciones Múltiples +- **ALBUM_ARTISTS, MEDIA_FILE_ARTISTS**: Soporte para múltiples artistas +- **{ALBUM|MEDIA_FILE|ARTIST}_GENRES**: Géneros en tabla de unión +- **LIBRARY_ARTIST, LIBRARY_TAG**: Agrupaciones por librería + +### ▶️ Reproducción & Escucha +- **PLAYLIST**: Listas de reproducción (públicas o privadas) +- **PLAYLIST_TRACKS**: Tabla de unión que preserva orden +- **PLAYQUEUE**: Cola actual del usuario +- **BOOKMARK**: Posiciones guardadas en canciones +- **ANNOTATION**: Ratings, play_count, starred (polimórfico) + +### 🌐 Distribución & Integración +- **SHARE**: Enlaces compartidos con expiración y contador de visitas +- **TRANSCODING**: Configuraciones de transcodificación (MP3, WEBM, etc.) +- **SCROBBLE_BUFFER**: Buffer para enviar plays a Last.fm, ListenBrainz +- **RADIO**: Radios de internet + +### 📚 Multi-Librería +- **LIBRARY**: Colecciones de música independientes +- **USER_LIBRARY**: Asignación de usuarios a librerías +- **LIBRARY_TAG**: Tags a nivel de librería + +## Características del Diseño + +1. ✅ **Foreign Keys con Integridad Referencial**: Eliminación en cascada configurada +2. ✅ **Tablas de Unión**: Soporta relaciones muchos-a-muchos (`PLAYLIST_TRACKS`, géneros) +3. ✅ **Anotaciones Polimórficas**: Una tabla `ANNOTATION` para múltiples entidades +4. ✅ **Usuario Central**: Presente en `ANNOTATION`, `PLAYQUEUE`, `PLAYLIST`, `BOOKMARK` +5. ✅ **Timestamps de Auditoría**: `created_at`, `updated_at` en tablas principales +6. ✅ **Full-Text Search**: Índices en `NOCASE` para búsquedas rápidas +7. ✅ **WAL Mode**: SQLite en Write-Ahead Logging para mejor concurrencia + +## Para Tests de Base de Datos + +Al probar persistencia, enfócate en: + +- **Foreign Keys**: `PLAYLIST_TRACKS` → `MEDIA_FILE`, `ALBUM`, etc. +- **Constraints Únicos**: `user_name`, `email` en `USER` +- **Triggers** (si existen): Actualizaciones de contadores (`song_count`, `album_count`) +- **Cascadas**: Eliminación de usuario → eliminación de anotaciones, playlists, etc. +- **Orden en Uniones**: `PLAYLIST_TRACKS` preserva posición numérica + +## Referencias + +- Ubicación del DB: `./data/navidrome.db` (SQLite) +- Migraciones: `db/migrations/` +- Repositorios: `persistence/` +- Modelos: `model/` diff --git a/docs/NAVIDROME_ER.drawio b/docs/NAVIDROME_ER.drawio new file mode 100644 index 000000000..876c6326b --- /dev/null +++ b/docs/NAVIDROME_ER.drawio @@ -0,0 +1,251 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/NAVIDROME_ER_COMPLETE.drawio b/docs/NAVIDROME_ER_COMPLETE.drawio new file mode 100644 index 000000000..80c36354a --- /dev/null +++ b/docs/NAVIDROME_ER_COMPLETE.drawio @@ -0,0 +1,529 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/TEST_PLAN_STAR_ENDPOINT.md b/docs/TEST_PLAN_STAR_ENDPOINT.md new file mode 100644 index 000000000..824816987 --- /dev/null +++ b/docs/TEST_PLAN_STAR_ENDPOINT.md @@ -0,0 +1,321 @@ +# Test Plan: Endpoint `/rest/star` - Marcar Canción como Favorita + +## Flujo del Endpoint + +``` +POST /rest/star?u=admin&t=TOKEN&s=SALT&f=json&v=1.8.0&c=NavidromeUI&id=MEDIA_FILE_ID +``` + +**Parámetros:** +- `u`: usuario (admin) +- `t`: token de sesión +- `s`: salt (para checksum) +- `f`: formato (json) +- `v`: versión API Subsonic +- `c`: cliente +- `id`: id del media_file a marcar como favorita + +**Operación en BD:** +1. Verificar que el usuario `admin` existe en tabla `USER` +2. Verificar que el media_file con `id` existe +3. Insertar/actualizar en tabla `ANNOTATION`: + - `user_id` = admin + - `item_id` = MEDIA_FILE_ID + - `item_type` = 'song' + - `starred` = true + - `starred_at` = current_timestamp + +--- + +## Tests Propuestos (EVALUACIÓN) + +### ✅ TEST 1: Verificar Foreign Key de ANNOTATION → USER +```sql +-- BIEN: Comprueba que NO puedes insertar user_id inválido +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('INVALID_USER_ID', 'song123', 'song', true); +-- DEBE FALLAR con constraint error +``` +**Evaluación:** ✅ BUENO - Es fundamental validar integridad referencial. + +**Mejora sugerida:** También incluir ON DELETE CASCADE - prueba que al borrar un usuario, se borren sus anotaciones. + +--- + +### ✅ TEST 2: Verificar Campos NOT NULL +```sql +-- BIEN: Campos obligatorios +INSERT INTO annotation (user_id, item_id, item_type) +VALUES (NULL, 'song123', 'song'); +-- DEBE FALLAR +``` +**Evaluación:** ✅ BUENO - Pero incompleto. Falta probar múltiples campos. + +**Mejora sugerida:** +- Probar todos los campos NOT NULL (`user_id`, `item_id`, `item_type`, `starred`) +- Probar valores vacíos/default + +--- + +### ✅ TEST 3: Insertar Canción + Annotation + SELECT con JOIN +```go +// Insertar media_file +INSERT INTO media_file (id, path, title) VALUES ('song123', '/path/song.mp3', 'My Song'); + +// Insertar annotation +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('admin_id', 'song123', 'song', true); + +// Verificar con JOIN +SELECT mf.title, ann.starred, ann.starred_at +FROM media_file mf +JOIN annotation ann ON mf.id = ann.item_id +WHERE ann.user_id = 'admin_id' AND ann.item_type = 'song'; +``` +**Evaluación:** ✅ EXCELENTE - Valida el flujo completo. + +--- + +### ✅ TEST 4: UPDATE - Marcar Favorita +```sql +UPDATE annotation +SET starred = true, starred_at = CURRENT_TIMESTAMP +WHERE user_id = 'admin_id' AND item_id = 'song123' AND item_type = 'song'; +``` +**Evaluación:** ✅ BUENO - Pero puede mejorase con transacciones y validaciones de timestamps. + +--- + +## Tests Recomendados ADICIONALES + +### 📌 TEST 5: Constraint UNIQUE de ANNOTATION +```sql +-- ANNOTATION tiene UNIQUE (user_id, item_id, item_type) +-- Intentar insertar dos veces el mismo registro debe fallar en la 2ª + +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('admin_id', 'song123', 'song', true); + +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('admin_id', 'song123', 'song', false); +-- DEBE FALLAR con UNIQUE constraint error +``` + +### 📌 TEST 6: Verificar Polimorfismo de ANNOTATION +```sql +-- item_type puede ser 'song', 'album', 'artist', etc. +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('admin_id', 'album456', 'album', true); + +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('admin_id', 'artist789', 'artist', true); + +-- Verificar que item_id NO existe en correspondiente tabla +-- Esto validaría que sin FK explícitas, hay riesgo de datos huérfanos +``` + +### 📌 TEST 7: Timestamp de starred_at +```sql +-- Verificar que starred_at se actualiza al cambiar starred +UPDATE annotation +SET starred = true, starred_at = CURRENT_TIMESTAMP +WHERE user_id = 'admin_id' AND item_id = 'song123'; + +-- Esperar 1 segundo +-- UPDATE nuevamente +UPDATE annotation +SET starred = true, starred_at = CURRENT_TIMESTAMP +WHERE user_id = 'admin_id' AND item_id = 'song123'; + +-- El timestamp debe ser más reciente +SELECT starred_at FROM annotation +WHERE user_id = 'admin_id' AND item_id = 'song123'; +``` + +### 📌 TEST 8: play_count vs starred +```sql +-- Verificar que play_count se incrementa independientemente de starred +INSERT INTO annotation (user_id, item_id, item_type, starred, play_count) +VALUES ('admin_id', 'song123', 'song', false, 0); + +UPDATE annotation SET play_count = play_count + 1 +WHERE user_id = 'admin_id' AND item_id = 'song123'; + +-- Marcar como favorita +UPDATE annotation SET starred = true, starred_at = CURRENT_TIMESTAMP +WHERE user_id = 'admin_id' AND item_id = 'song123'; + +-- Verificar que ambos campos persisten +SELECT play_count, starred FROM annotation +WHERE user_id = 'admin_id' AND item_id = 'song123'; +``` + +### 📌 TEST 9: ON DELETE CASCADE - User Deletion +```sql +-- Insertar usuario con annotations +INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) +VALUES ('test_user', 'testuser', 'hashedpwd', false, NOW(), NOW()); + +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('test_user', 'song123', 'song', true); + +-- Verificar que existe +SELECT COUNT(*) FROM annotation WHERE user_id = 'test_user'; +-- Debe retornar 1 + +-- Borrar usuario +DELETE FROM user WHERE id = 'test_user'; + +-- Verificar que las anotaciones se borraron en cascada +SELECT COUNT(*) FROM annotation WHERE user_id = 'test_user'; +-- Debe retornar 0 (borración en cascada funcionó) +``` + +### 📌 TEST 10: Integridad con Multiple Users +```sql +-- Verificar que cada usuario tiene anotaciones independientes +INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) +VALUES ('admin', 'admin', 'pwd1', true, NOW(), NOW()); + +INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) +VALUES ('user2', 'user2', 'pwd2', false, NOW(), NOW()); + +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('admin', 'song123', 'song', true); + +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('user2', 'song123', 'song', false); + +-- Verificar que cada usuario ve su estado +SELECT starred FROM annotation +WHERE user_id = 'admin' AND item_id = 'song123'; +-- Retorna true + +SELECT starred FROM annotation +WHERE user_id = 'user2' AND item_id = 'song123'; +-- Retorna false +``` + +### 📌 TEST 11: Rating + Starred Independientes +```sql +-- Verificar que puedo calificar y marcar favorita independientemente +UPDATE annotation +SET rating = 5, starred = true, starred_at = CURRENT_TIMESTAMP +WHERE user_id = 'admin_id' AND item_id = 'song123'; + +-- Cambiar solo el rating +UPDATE annotation +SET rating = 3 +WHERE user_id = 'admin_id' AND item_id = 'song123'; + +-- Verificar que starred se mantiene +SELECT rating, starred FROM annotation +WHERE user_id = 'admin_id' AND item_id = 'song123'; +-- Debe retornar: rating=3, starred=true +``` + +### 📌 TEST 12: NULL en Campos Opcionales +```sql +-- Algunos campos pueden ser NULL (play_date, rating, etc.) +INSERT INTO annotation (user_id, item_id, item_type, starred, play_count, rating, play_date) +VALUES ('admin_id', 'song456', 'song', true, NULL, NULL, NULL); + +SELECT * FROM annotation +WHERE user_id = 'admin_id' AND item_id = 'song456'; +-- Debe permitir NULLs en play_count, rating, play_date +``` + +### 📌 TEST 13: Transacción - Rollback si Falla +```sql +BEGIN TRANSACTION; + +INSERT INTO media_file (id, path, title) VALUES ('song_new', '/path/new.mp3', 'New Song'); + +INSERT INTO annotation (user_id, item_id, item_type, starred) +VALUES ('admin_id', 'song_new', 'song', true); + +-- Simular error +-- ROLLBACK; + +-- Verificar que nada se insertó +SELECT COUNT(*) FROM media_file WHERE id = 'song_new'; +SELECT COUNT(*) FROM annotation WHERE item_id = 'song_new'; +-- Ambos deben retornar 0 +``` + +### 📌 TEST 14: Índices - Performance +```sql +-- Verificar que existen índices en: +-- 1. user_id (para búsquedas rápidas) +-- 2. (user_id, item_id, item_type) composite + +EXPLAIN QUERY PLAN +SELECT * FROM annotation +WHERE user_id = 'admin_id' AND item_id = 'song123' AND item_type = 'song'; +-- Debe usar índice (no SCAN) +``` + +### 📌 TEST 15: Idempotencia - Star/Unstar Múltiples Veces +```sql +-- Marcar como favorita +UPDATE annotation +SET starred = true, starred_at = CURRENT_TIMESTAMP +WHERE user_id = 'admin_id' AND item_id = 'song123' AND item_type = 'song'; + +-- Marcar nuevamente (debe ser safe) +UPDATE annotation +SET starred = true, starred_at = CURRENT_TIMESTAMP +WHERE user_id = 'admin_id' AND item_id = 'song123' AND item_type = 'song'; + +-- Si record no existe, hacer INSERT (upsert pattern) +INSERT OR REPLACE INTO annotation (user_id, item_id, item_type, starred, starred_at) +VALUES ('admin_id', 'song123', 'song', true, CURRENT_TIMESTAMP); + +-- Debe ser seguro (no duplicados, no errores) +``` + +--- + +## Matriz de Cobertura + +| Test | Categoría | Importancia | Estado | +|------|-----------|-------------|--------| +| 1 | Foreign Key | ⭐⭐⭐⭐⭐ | ✅ Propuesto | +| 2 | Constraints | ⭐⭐⭐⭐⭐ | ✅ Propuesto | +| 3 | Flujo Completo | ⭐⭐⭐⭐⭐ | ✅ Propuesto | +| 4 | UPDATE | ⭐⭐⭐⭐⭐ | ✅ Propuesto | +| 5 | UNIQUE | ⭐⭐⭐⭐⭐ | 📌 Recomendado | +| 6 | Polimorfismo | ⭐⭐⭐⭐ | 📌 Recomendado | +| 7 | Timestamps | ⭐⭐⭐⭐ | 📌 Recomendado | +| 8 | Independencia datos | ⭐⭐⭐⭐ | 📌 Recomendado | +| 9 | Cascada | ⭐⭐⭐⭐⭐ | 📌 Recomendado | +| 10 | Multi-usuario | ⭐⭐⭐⭐ | 📌 Recomendado | +| 11 | Campos independientes | ⭐⭐⭐⭐ | 📌 Recomendado | +| 12 | NULLs opcionales | ⭐⭐⭐ | 📌 Recomendado | +| 13 | Transacciones | ⭐⭐⭐⭐ | 📌 Recomendado | +| 14 | Performance | ⭐⭐⭐⭐ | 📌 Recomendado | +| 15 | Idempotencia | ⭐⭐⭐⭐⭐ | 📌 Recomendado | + +--- + +## Recomendación Final + +**Tests CRÍTICOS (HACER PRIMERO):** +1. Foreign Key de ANNOTATION → USER (con cascada) +2. NOT NULL constraints +3. Flujo completo (INSERT + JOIN) +4. UPDATE starred flag +5. UNIQUE constraint (user_id, item_id, item_type) +6. Idempotencia (upsert safe) + +**Tests IMPORTANTES (hacer después):** +7. Multi-usuario (aislamiento) +8. Timestamps accuracy +9. ON DELETE CASCADE +10. Performance con índices + +**Tests COMPLEMENTARIOS (nice-to-have):** +11. Polimorfismo (item_type) +12. play_count independiente +13. Transacciones y rollback +14. NULL fields opcionales diff --git a/persistence/annotation_star_test.go b/persistence/annotation_star_test.go new file mode 100644 index 000000000..c3cd8852c --- /dev/null +++ b/persistence/annotation_star_test.go @@ -0,0 +1,525 @@ +package persistence_test + +import ( + "context" + "database/sql" + "testing" + "time" + + "github.com/navidrome/navidrome/db" + "github.com/navidrome/navidrome/log" + "github.com/navidrome/navidrome/tests" + . "github.com/onsi/ginkgo/v2" + . "github.com/onsi/gomega" +) + +// Test suite para el flujo /rest/star - Marcar canción como favorita +// Valida todas las reglas de integridad en la tabla ANNOTATION + +func TestStarEndpoint(t *testing.T) { + tests.Init(t, false) + log.SetLevel(log.LevelFatal) + RegisterFailHandler(Fail) + RunSpecs(t, "Star Endpoint - BD Tests") +} + +var _ = Describe("Star Endpoint DB Tests", func() { + var database *sql.DB + var ctx context.Context + + BeforeEach(func() { + // Usar in-memory SQLite para tests rápidos + path := "file::memory:?cache=shared&_foreign_keys=on" + database, _ = sql.Open(db.Dialect, path) + ctx = context.Background() + + // Crear schema completo (mínimo para los tests) + _, err := database.ExecContext(ctx, ` + CREATE TABLE user ( + id VARCHAR(255) NOT NULL PRIMARY KEY, + user_name VARCHAR(255) NOT NULL UNIQUE, + name VARCHAR(255), + email VARCHAR(255), + password VARCHAR(255), + is_admin BOOLEAN DEFAULT FALSE, + last_login_at DATETIME, + last_access_at DATETIME, + created_at DATETIME NOT NULL, + updated_at DATETIME NOT NULL + ); + + CREATE TABLE media_file ( + id VARCHAR(255) NOT NULL PRIMARY KEY, + path VARCHAR(255) NOT NULL, + title VARCHAR(255), + album_id VARCHAR(255), + artist_id VARCHAR(255), + album_artist VARCHAR(255), + duration REAL DEFAULT 0, + created_at DATETIME, + updated_at DATETIME + ); + + CREATE TABLE annotation ( + user_id VARCHAR(255) NOT NULL REFERENCES user(id) ON DELETE CASCADE, + item_id VARCHAR(255) NOT NULL, + item_type VARCHAR(255) NOT NULL, + play_count INTEGER, + play_date DATETIME, + rating INTEGER, + starred BOOLEAN DEFAULT FALSE NOT NULL, + starred_at DATETIME, + rating_date DATETIME, + UNIQUE (user_id, item_id, item_type) + ); + + CREATE INDEX annotation_user_id ON annotation(user_id); + CREATE INDEX annotation_item ON annotation(item_id, item_type); + `) + Expect(err).NotTo(HaveOccurred()) + }) + + AfterEach(func() { + database.Close() + }) + + // ================== TEST 1: Foreign Key Constraint ================== + Describe("TEST 1: Foreign Key Constraint ANNOTATION -> USER", func() { + It("debe rechazar inserción de annotation con user_id inválido", func() { + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "INVALID_USER_ID", "song123", "song", true) + Expect(err).To(HaveOccurred()) + Expect(err.Error()).To(ContainSubstring("FOREIGN KEY constraint failed")) + }) + + It("debe permitir inserción si user_id existe", func() { + // Setup: crear usuario + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "admin", "admin", "hashedpwd", true, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + + // Act: insertar annotation + _, err = database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "admin", "song123", "song", true) + Expect(err).NotTo(HaveOccurred()) + + // Verify + var starred bool + err = database.QueryRowContext(ctx, + `SELECT starred FROM annotation WHERE user_id = ? AND item_id = ?`, + "admin", "song123").Scan(&starred) + Expect(err).NotTo(HaveOccurred()) + Expect(starred).To(BeTrue()) + }) + }) + + // ================== TEST 2: NOT NULL Constraints ================== + Describe("TEST 2: NOT NULL Constraints", func() { + BeforeEach(func() { + // Setup: crear usuario + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "admin", "admin", "hashedpwd", true, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + }) + + It("debe rechazar si user_id es NULL", func() { + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (NULL, ?, ?, ?)`, + "song123", "song", true) + Expect(err).To(HaveOccurred()) + }) + + It("debe rechazar si item_id es NULL", func() { + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, NULL, ?, ?)`, + "admin", "song", true) + Expect(err).To(HaveOccurred()) + }) + + It("debe rechazar si item_type es NULL", func() { + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, NULL, ?)`, + "admin", "song123", true) + Expect(err).To(HaveOccurred()) + }) + + It("debe rechazar si starred es NULL", func() { + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, NULL)`, + "admin", "song123", "song") + Expect(err).To(HaveOccurred()) + }) + }) + + // ================== TEST 3: Flujo Completo ================== + Describe("TEST 3: Flujo Completo - INSERT Media + Annotation + JOIN", func() { + It("debe permitir insertar canción y marcar como favorita con JOIN", func() { + // Setup + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "admin", "admin", "hashedpwd", true, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + + // Insert media_file + _, err = database.ExecContext(ctx, + `INSERT INTO media_file (id, path, title) VALUES (?, ?, ?)`, + "song123", "/path/to/song.mp3", "My Favorite Song") + Expect(err).NotTo(HaveOccurred()) + + // Insert annotation (star) + _, err = database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred, starred_at) + VALUES (?, ?, ?, ?, ?)`, + "admin", "song123", "song", true, time.Now()) + Expect(err).NotTo(HaveOccurred()) + + // Verify con JOIN + var title string + var starred bool + var starredAt sql.NullTime + + err = database.QueryRowContext(ctx, ` + SELECT mf.title, ann.starred, ann.starred_at + FROM media_file mf + JOIN annotation ann ON mf.id = ann.item_id + WHERE ann.user_id = ? AND ann.item_type = 'song' + `, "admin").Scan(&title, &starred, &starredAt) + + Expect(err).NotTo(HaveOccurred()) + Expect(title).To(Equal("My Favorite Song")) + Expect(starred).To(BeTrue()) + Expect(starredAt.Valid).To(BeTrue()) + }) + }) + + // ================== TEST 4: UPDATE Favorita ================== + Describe("TEST 4: UPDATE - Marcar/Desmarcar Favorita", func() { + BeforeEach(func() { + // Setup + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "admin", "admin", "hashedpwd", true, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + + _, err = database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "admin", "song123", "song", false) + Expect(err).NotTo(HaveOccurred()) + }) + + It("debe marcar como favorita con UPDATE", func() { + starredAt := time.Now() + result, err := database.ExecContext(ctx, ` + UPDATE annotation SET starred = ?, starred_at = ? + WHERE user_id = ? AND item_id = ? AND item_type = ? + `, true, starredAt, "admin", "song123", "song") + Expect(err).NotTo(HaveOccurred()) + + affected, err := result.RowsAffected() + Expect(err).NotTo(HaveOccurred()) + Expect(affected).To(Equal(int64(1))) + + var starred bool + err = database.QueryRowContext(ctx, + `SELECT starred FROM annotation WHERE user_id = ? AND item_id = ?`, + "admin", "song123").Scan(&starred) + Expect(err).NotTo(HaveOccurred()) + Expect(starred).To(BeTrue()) + }) + + It("debe desmarcar favorita", func() { + result, err := database.ExecContext(ctx, ` + UPDATE annotation SET starred = ?, starred_at = NULL + WHERE user_id = ? AND item_id = ? AND item_type = ? + `, false, "admin", "song123", "song") + Expect(err).NotTo(HaveOccurred()) + + affected, err := result.RowsAffected() + Expect(err).NotTo(HaveOccurred()) + Expect(affected).To(Equal(int64(1))) + }) + }) + + // ================== TEST 5: UNIQUE Constraint ================== + Describe("TEST 5: UNIQUE Constraint (user_id, item_id, item_type)", func() { + BeforeEach(func() { + // Setup + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "admin", "admin", "hashedpwd", true, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + + _, err = database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "admin", "song123", "song", true) + Expect(err).NotTo(HaveOccurred()) + }) + + It("debe rechazar inserción duplicada del mismo (user, item, type)", func() { + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "admin", "song123", "song", false) + Expect(err).To(HaveOccurred()) + Expect(err.Error()).To(ContainSubstring("UNIQUE constraint failed")) + }) + + It("debe permitir el mismo item_id pero diferente user", func() { + // Setup: crear otro usuario + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "user2", "user2", "hashedpwd", false, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + + // Insertar annotation para otro usuario sobre el mismo song + _, err = database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "user2", "song123", "song", false) + Expect(err).NotTo(HaveOccurred()) + + // Verify ambos existen + var count int + err = database.QueryRowContext(ctx, + `SELECT COUNT(*) FROM annotation WHERE item_id = ?`, + "song123").Scan(&count) + Expect(err).NotTo(HaveOccurred()) + Expect(count).To(Equal(2)) + }) + + It("debe permitir el mismo item_id pero diferente item_type", func() { + // El mismo ID podría ser album o artist + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "admin", "song123", "album", false) + Expect(err).NotTo(HaveOccurred()) + }) + }) + + // ================== TEST 6: ON DELETE CASCADE ================== + Describe("TEST 6: ON DELETE CASCADE - User Deletion", func() { + BeforeEach(func() { + // Setup + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "test_user", "testuser", "hashedpwd", false, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + + _, err = database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "test_user", "song123", "song", true) + Expect(err).NotTo(HaveOccurred()) + }) + + It("debe borrar annotations quando se borra el usuario (CASCADE)", func() { + // Verify que existen + var count int + err := database.QueryRowContext(ctx, + `SELECT COUNT(*) FROM annotation WHERE user_id = ?`, + "test_user").Scan(&count) + Expect(err).NotTo(HaveOccurred()) + Expect(count).To(Equal(1)) + + // Delete user + _, err = database.ExecContext(ctx, + `DELETE FROM user WHERE id = ?`, "test_user") + Expect(err).NotTo(HaveOccurred()) + + // Verify annotations se borraron en cascada + err = database.QueryRowContext(ctx, + `SELECT COUNT(*) FROM annotation WHERE user_id = ?`, + "test_user").Scan(&count) + Expect(err).NotTo(HaveOccurred()) + Expect(count).To(Equal(0)) + }) + }) + + // ================== TEST 7: Multi-usuario Aislamiento ================== + Describe("TEST 7: Multi-usuario - Aislamiento de Datos", func() { + BeforeEach(func() { + // Setup: crear 2 usuarios + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "admin", "admin", "hashedpwd", true, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + + _, err = database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "user2", "user2", "hashedpwd", false, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + + // Ambos marcan la misma canción pero diferente estado + _, err = database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "admin", "song123", "song", true) + Expect(err).NotTo(HaveOccurred()) + + _, err = database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "user2", "song123", "song", false) + Expect(err).NotTo(HaveOccurred()) + }) + + It("admin debe ver starred=true", func() { + var starred bool + err := database.QueryRowContext(ctx, + `SELECT starred FROM annotation WHERE user_id = ? AND item_id = ?`, + "admin", "song123").Scan(&starred) + Expect(err).NotTo(HaveOccurred()) + Expect(starred).To(BeTrue()) + }) + + It("user2 debe ver starred=false", func() { + var starred bool + err := database.QueryRowContext(ctx, + `SELECT starred FROM annotation WHERE user_id = ? AND item_id = ?`, + "user2", "song123").Scan(&starred) + Expect(err).NotTo(HaveOccurred()) + Expect(starred).To(BeFalse()) + }) + }) + + // ================== TEST 8: Timestamps Accuracy ================== + Describe("TEST 8: Timestamps - starred_at Precision", func() { + BeforeEach(func() { + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "admin", "admin", "hashedpwd", true, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + }) + + It("debe actualizar starred_at al marcar favorita", func() { + t1 := time.Now() + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred, starred_at) + VALUES (?, ?, ?, ?, ?)`, + "admin", "song123", "song", true, t1) + Expect(err).NotTo(HaveOccurred()) + + // Esperar un poco + time.Sleep(100 * time.Millisecond) + + // Update starred nuevamente + t2 := time.Now() + _, err = database.ExecContext(ctx, + `UPDATE annotation SET starred = ?, starred_at = ? + WHERE user_id = ? AND item_id = ?`, + true, t2, "admin", "song123") + Expect(err).NotTo(HaveOccurred()) + + // Verify que el timestamp es más reciente + var starredAt time.Time + err = database.QueryRowContext(ctx, + `SELECT starred_at FROM annotation WHERE user_id = ? AND item_id = ?`, + "admin", "song123").Scan(&starredAt) + Expect(err).NotTo(HaveOccurred()) + Expect(starredAt.After(t1)).To(BeTrue()) + }) + + It("debe permitir NULL en starred_at cuando no está starred", func() { + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred, starred_at) + VALUES (?, ?, ?, ?, ?)`, + "admin", "song123", "song", false, nil) + Expect(err).NotTo(HaveOccurred()) + + var starredAt sql.NullTime + err = database.QueryRowContext(ctx, + `SELECT starred_at FROM annotation WHERE user_id = ? AND item_id = ?`, + "admin", "song123").Scan(&starredAt) + Expect(err).NotTo(HaveOccurred()) + Expect(starredAt.Valid).To(BeFalse()) + }) + }) + + // ================== TEST 9: Idempotencia - Upsert Pattern ================== + Describe("TEST 9: Idempotencia - Star/Unstar Múltiples Veces", func() { + BeforeEach(func() { + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "admin", "admin", "hashedpwd", true, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + }) + + It("debe ser idempotente al marcar favorita múltiples veces", func() { + // First star + _, err := database.ExecContext(ctx, + `INSERT OR REPLACE INTO annotation (user_id, item_id, item_type, starred, starred_at) + VALUES (?, ?, ?, ?, ?)`, + "admin", "song123", "song", true, time.Now()) + Expect(err).NotTo(HaveOccurred()) + + // Star again (should succeed, not duplicate) + _, err = database.ExecContext(ctx, + `INSERT OR REPLACE INTO annotation (user_id, item_id, item_type, starred, starred_at) + VALUES (?, ?, ?, ?, ?)`, + "admin", "song123", "song", true, time.Now()) + Expect(err).NotTo(HaveOccurred()) + + // Verify solo una annotation existe + var count int + err = database.QueryRowContext(ctx, + `SELECT COUNT(*) FROM annotation WHERE user_id = ? AND item_id = ?`, + "admin", "song123").Scan(&count) + Expect(err).NotTo(HaveOccurred()) + Expect(count).To(Equal(1)) + }) + }) + + // ================== TEST 10: Polimorfismo - item_type ================== + Describe("TEST 10: Polimorfismo - Diferentes item_type", func() { + BeforeEach(func() { + _, err := database.ExecContext(ctx, + `INSERT INTO user (id, user_name, password, is_admin, created_at, updated_at) + VALUES (?, ?, ?, ?, ?, ?)`, + "admin", "admin", "hashedpwd", true, time.Now(), time.Now()) + Expect(err).NotTo(HaveOccurred()) + }) + + It("debe permitir marcar como favorita song, album, y artist", func() { + types := []string{"song", "album", "artist", "folder"} + for _, itemType := range types { + _, err := database.ExecContext(ctx, + `INSERT INTO annotation (user_id, item_id, item_type, starred) + VALUES (?, ?, ?, ?)`, + "admin", "item"+itemType, itemType, true) + Expect(err).NotTo(HaveOccurred()) + } + + // Verify cada uno existe + var count int + err := database.QueryRowContext(ctx, + `SELECT COUNT(*) FROM annotation WHERE user_id = ?`, + "admin").Scan(&count) + Expect(err).NotTo(HaveOccurred()) + Expect(count).To(Equal(4)) + }) + }) +}) From 1ed1d0ce799fb1042f7741d8a63dce2fb9988bf5 Mon Sep 17 00:00:00 2001 From: Salome Gene Date: Fri, 15 May 2026 11:57:30 -0500 Subject: [PATCH 05/15] test(frontend): add unit tests for favorites flow - Add LoveButton.test.jsx with 9 cases (render, disabled states, click, propagation, tooltip) - Add ContextMenus.test.jsx with 8 cases for AlbumContextMenu and ArtistContextMenu - Extend useToggleLove.test.js with error handling and loading state cases - Add useToggleLove.test.md documenting test cases and mocks - Add frontend-test service to docker-compose.dev.yml (profile: test) Co-Authored-By: Claude Sonnet 4.6 --- docker-compose.dev.yml | 10 +++ ui/src/common/ContextMenus.test.jsx | 99 +++++++++++++++++++++++++++ ui/src/common/LoveButton.test.jsx | 100 ++++++++++++++++++++++++++++ ui/src/common/useToggleLove.test.js | 58 +++++++++++++++- ui/src/common/useToggleLove.test.md | 27 ++++++++ 5 files changed, 291 insertions(+), 3 deletions(-) create mode 100644 ui/src/common/ContextMenus.test.jsx create mode 100644 ui/src/common/LoveButton.test.jsx create mode 100644 ui/src/common/useToggleLove.test.md diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml index 0d9713896..58737ab83 100644 --- a/docker-compose.dev.yml +++ b/docker-compose.dev.yml @@ -35,6 +35,16 @@ services: depends_on: - backend + frontend-test: + image: node:24 + working_dir: /app + volumes: + - ./ui:/app + - node-modules:/app/node_modules + command: sh -c "npm ci && npm test" + profiles: + - test + volumes: go-mod-cache: go-build-cache: diff --git a/ui/src/common/ContextMenus.test.jsx b/ui/src/common/ContextMenus.test.jsx new file mode 100644 index 000000000..787e30805 --- /dev/null +++ b/ui/src/common/ContextMenus.test.jsx @@ -0,0 +1,99 @@ +import React from 'react' +import { render, screen } from '@testing-library/react' +import { describe, it, expect, vi, beforeEach } from 'vitest' +import { AlbumContextMenu, ArtistContextMenu } from './ContextMenus' + +const capturedLoveButtonProps = {} + +vi.mock('./LoveButton', () => ({ + LoveButton: (props) => { + Object.assign(capturedLoveButtonProps, props) + return props.visible ?