docs(04-01): complete queue unit tests plan
This commit is contained in:
@@ -37,7 +37,7 @@ Requirements for the consolidation milestone. Each maps to roadmap phases.
|
||||
### Testing
|
||||
|
||||
- [x] **TEST-01**: In-memory SQLite test helper (database.NewTestDB) exists, applies same migrations and PRAGMAs as production NewDB, returns a clean DB per test
|
||||
- [ ] **TEST-02**: Queue package has unit tests covering SetQueue, Next, Previous, shuffle mode, repeat modes, and state persistence (~15-20 tests)
|
||||
- [x] **TEST-02**: Queue package has unit tests covering SetQueue, Next, Previous, shuffle mode, repeat modes, and state persistence (~15-20 tests)
|
||||
- [ ] **TEST-03**: Database package has unit tests covering FTS5 search queries (basic, empty, special characters), search index rebuild, and schema migrations (~10-15 tests)
|
||||
- [ ] **TEST-04**: Config package has unit tests covering load/save roundtrip, validation rules, default application, and behavior with missing/empty config files (~8-10 tests)
|
||||
- [ ] **TEST-05**: Player pure logic (UserVolume-to-Volume conversion, state serialization, format detection) is extracted into testable functions with unit tests (~5-8 tests)
|
||||
@@ -108,7 +108,7 @@ Which phases cover which requirements. Updated during roadmap creation.
|
||||
| PERF-04 | Phase 3: Test Infrastructure | Complete |
|
||||
| PERF-05 | Phase 8: Frontend Performance & UX | Pending |
|
||||
| TEST-01 | Phase 3: Test Infrastructure | Complete |
|
||||
| TEST-02 | Phase 4: Queue, Config & Player Tests | Pending |
|
||||
| TEST-02 | Phase 4: Queue, Config & Player Tests | Complete |
|
||||
| TEST-03 | Phase 5: Database & Library Tests | Pending |
|
||||
| TEST-04 | Phase 4: Queue, Config & Player Tests | Pending |
|
||||
| TEST-05 | Phase 4: Queue, Config & Player Tests | Pending |
|
||||
|
||||
+25
-22
@@ -2,13 +2,13 @@
|
||||
gsd_state_version: 1.0
|
||||
milestone: v1.0
|
||||
milestone_name: milestone
|
||||
status: completed
|
||||
last_updated: "2026-03-03T03:10:27.876Z"
|
||||
status: in-progress
|
||||
last_updated: "2026-03-03T22:00:46Z"
|
||||
progress:
|
||||
total_phases: 3
|
||||
total_phases: 4
|
||||
completed_phases: 3
|
||||
total_plans: 4
|
||||
completed_plans: 4
|
||||
total_plans: 6
|
||||
completed_plans: 5
|
||||
---
|
||||
|
||||
# YellowJacket — Consolidation Milestone State
|
||||
@@ -16,17 +16,17 @@ progress:
|
||||
## Project Reference
|
||||
|
||||
**Core value:** The music player works reliably and feels solid — every interaction is correct, responsive, and trustworthy.
|
||||
**Current focus:** Phase 3 complete — test infrastructure foundation with NewTestDB helper.
|
||||
**Current focus:** Phase 4 in progress — queue unit tests complete, config/player tests next.
|
||||
**Milestone:** Consolidation (correctness, performance, code quality, UX polish, test coverage)
|
||||
|
||||
## Current Position
|
||||
|
||||
**Phase:** 03-test-infrastructure (complete)
|
||||
**Plan:** 1/1 (complete)
|
||||
**Status:** Milestone complete
|
||||
**Phase:** 04-queue-config-player-tests (in progress)
|
||||
**Plan:** 1/2 (Plan 01 complete)
|
||||
**Status:** In progress
|
||||
|
||||
```
|
||||
Phase Progress: [###.....] 3/8 phases complete
|
||||
Phase Progress: [###.....] 3/8 phases complete (Phase 4: 1/2 plans)
|
||||
```
|
||||
|
||||
## Performance Metrics
|
||||
@@ -34,14 +34,15 @@ Phase Progress: [###.....] 3/8 phases complete
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Phases complete | 3/8 |
|
||||
| Plans complete | 1/1 (Phase 3) |
|
||||
| Requirements delivered | 11/26 |
|
||||
| Tests added | 0 |
|
||||
| Plans complete | 1/2 (Phase 4) |
|
||||
| Requirements delivered | 12/26 |
|
||||
| Tests added | 29 |
|
||||
| Bugs fixed | 9 |
|
||||
| 01-01 duration | 11 min |
|
||||
| 02-01 duration | 12 min |
|
||||
| 02-02 duration | 50 min |
|
||||
| 03-01 duration | 3 min |
|
||||
| 04-01 duration | 3 min |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -61,6 +62,8 @@ Phase Progress: [###.....] 3/8 phases complete
|
||||
| Fatal vs warning error classification | tx.Commit failures are fatal; all other scan errors are warnings in ScanMetrics | Phase 2 |
|
||||
| applyPRAGMAs unexported, shared | Package-internal function ensures NewDB and NewTestDB have identical PRAGMA config | Phase 3 |
|
||||
| NewTestDB uses t.Fatalf not error return | Test DB setup failures are always fatal — no partial test execution | Phase 3 |
|
||||
| Internal queue tests (package queue) | Access unexported fields (shuffleOrder, mu) for thorough state verification | Phase 4 |
|
||||
| Persistence roundtrip verifies shuffleOrder JSON | Safety net for Phase 7 incremental persistence refactoring | Phase 4 |
|
||||
|
||||
### TODOs
|
||||
|
||||
@@ -72,7 +75,7 @@ Phase Progress: [###.....] 3/8 phases complete
|
||||
- [x] Plan Phase 3 (complete)
|
||||
- [x] Execute Phase 3 Plan 01 (complete)
|
||||
- [ ] Validate sqlc + SQLite VIEW + FTS5 compatibility during Phase 6 planning (research flag)
|
||||
- [ ] Design queue test architecture during Phase 4 planning (research flag)
|
||||
- [x] Design queue test architecture during Phase 4 planning (complete)
|
||||
- [ ] Determine library scan test fixture strategy during Phase 5 planning (research flag)
|
||||
- [ ] Measure startup time with large library before Phase 7 lazy loading work
|
||||
|
||||
@@ -104,19 +107,19 @@ None currently.
|
||||
### Last Session
|
||||
|
||||
**Date:** 2026-03-03
|
||||
**What happened:** Executed Phase 3 Plan 01 — test infrastructure with shared applyPRAGMAs + NewTestDB helper
|
||||
**Where we stopped:** Completed 03-01-PLAN.md (all 2 tasks, verification passed)
|
||||
**Next action:** `/gsd-plan-phase 4` to create execution plan for Backend Unit Tests
|
||||
**What happened:** Executed Phase 4 Plan 01 — 29 queue unit tests (core ops, navigation, persistence roundtrip)
|
||||
**Where we stopped:** Completed 04-01-PLAN.md (all 2 tasks, verification passed)
|
||||
**Next action:** `/gsd-execute-phase 4` to execute Plan 04-02 (config/player tests)
|
||||
|
||||
### Context for Next Session
|
||||
|
||||
- Phase 3 complete: TEST-01 and PERF-04 requirements delivered
|
||||
- `NewTestDB(t)` available in `database` package for all future DB tests
|
||||
- `applyPRAGMAs` shared between NewDB and NewTestDB — production PRAGMAs: foreign_keys, synchronous=NORMAL, cache_size=-8000, mmap_size=67108864
|
||||
- Phase 4 Plan 01 complete: TEST-02 requirement delivered (queue tests)
|
||||
- 29 queue tests passing with `-race`: 14 core ops, 9 navigation, 6 persistence
|
||||
- mockTrackLoader and seedAudioFiles helpers available in queue package for reuse
|
||||
- `codegen-check` lefthook pre-commit hook hangs — use `LEFTHOOK=0` for commits
|
||||
- Ready for Phase 4 (Backend Unit Tests)
|
||||
- Plan 04-02 (config/player tests) is next
|
||||
|
||||
---
|
||||
*State initialized: 2026-02-27*
|
||||
Last activity: 2026-03-03 - Completed 03-01: Test infrastructure with shared applyPRAGMAs + NewTestDB
|
||||
Last activity: 2026-03-03 - Completed 04-01: Queue unit tests (core ops, navigation, persistence)
|
||||
*Last updated: 2026-03-03*
|
||||
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
phase: 04-queue-config-player-tests
|
||||
plan: 01
|
||||
subsystem: testing
|
||||
tags: [queue, sqlite, unit-tests, shuffle, repeat, persistence]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 03-test-infrastructure
|
||||
provides: "NewTestDB(t) helper for in-memory SQLite test databases"
|
||||
provides:
|
||||
- "29 queue tests covering core ops, navigation, and persistence roundtrip"
|
||||
- "Mock TrackLoader and seedAudioFiles test helpers in queue package"
|
||||
- "Safety net for Phase 7 (PERF-01) queue persistence refactoring"
|
||||
affects: [07-performance-optimization]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: ["internal package tests (package queue, not queue_test)", "direct field manipulation for pure logic tests (no DB)", "seedAudioFiles helper with FK chain for DB-backed tests"]
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- backend/queue/queue_test.go
|
||||
- backend/queue/navigation_test.go
|
||||
- backend/queue/persistence_test.go
|
||||
modified: []
|
||||
|
||||
key-decisions:
|
||||
- "Internal tests (package queue) to access unexported fields like shuffleOrder, mu"
|
||||
- "Navigation tests use direct struct construction (no DB) for fast pure-logic testing"
|
||||
- "Persistence roundtrip test verifies ALL state fields including shuffleOrder JSON"
|
||||
|
||||
patterns-established:
|
||||
- "mockTrackLoader pattern: no-op TrackLoader with loadedFile tracking"
|
||||
- "seedAudioFiles helper: creates FK chain (artist_credit → recordings → audio_files) for N tracks"
|
||||
- "newTestQueueDirect: direct Queue construction for navigation/logic tests without DB"
|
||||
|
||||
requirements-completed: [TEST-02]
|
||||
|
||||
# Metrics
|
||||
duration: 3min
|
||||
completed: 2026-03-03
|
||||
---
|
||||
|
||||
# Phase 04 Plan 01: Queue Unit Tests Summary
|
||||
|
||||
**29 unit tests for queue core operations (SetQueue, Add, Insert, Move, Remove, Shuffle, Repeat), navigation logic (Next/Previous in all modes), and SaveState/RestoreState persistence roundtrip**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 3 min
|
||||
- **Started:** 2026-03-03T21:57:38Z
|
||||
- **Completed:** 2026-03-03T22:00:46Z
|
||||
- **Tasks:** 2
|
||||
- **Files modified:** 3
|
||||
|
||||
## Accomplishments
|
||||
- 14 core operation tests: SetQueue (3 variants), AddTrack, InsertTracksAt (before/after current), MoveQueueTracks (forward/backward/current), RemoveTrack (normal/current), Clear, ToggleShuffle, CycleRepeat
|
||||
- 9 navigation tests: nextIndex/previousIndex in RepeatOff/RepeatAll/RepeatOne modes, shuffle navigation, generateShuffleOrder property validation (all indices, no duplicates, current at [0])
|
||||
- 6 persistence roundtrip tests: full state fidelity, empty/single/10-track edge cases, overwrite semantics, no-prior-save safety
|
||||
- All 29 tests pass with `-race` flag
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Queue core operations and navigation tests** - `8d60dc0` (test)
|
||||
2. **Task 2: Queue persistence round-trip tests** - `77cc993` (test)
|
||||
|
||||
## Files Created/Modified
|
||||
- `backend/queue/queue_test.go` - Core operation tests + mock TrackLoader + setupTestQueue/seedAudioFiles helpers
|
||||
- `backend/queue/navigation_test.go` - Navigation edge case tests + shuffle order property tests
|
||||
- `backend/queue/persistence_test.go` - SaveState/RestoreState roundtrip fidelity tests
|
||||
|
||||
## Decisions Made
|
||||
- Used internal tests (`package queue`) to access unexported fields (shuffleOrder, mu) — necessary for shuffle verification and roundtrip assertions
|
||||
- Navigation tests bypass DB entirely using direct struct construction for fast, focused tests
|
||||
- Roundtrip test asserts on shuffleOrder (JSON-serialized) to ensure Phase 7 refactoring won't silently lose shuffle state
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None - plan executed exactly as written.
|
||||
|
||||
## Issues Encountered
|
||||
None
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
- Queue test safety net complete — ready for Phase 7 (PERF-01) incremental persistence refactoring
|
||||
- Test helpers (mockTrackLoader, seedAudioFiles) available for reuse in Plan 04-02 (config/player tests)
|
||||
- Ready for Plan 04-02 execution
|
||||
|
||||
---
|
||||
*Phase: 04-queue-config-player-tests*
|
||||
*Completed: 2026-03-03*
|
||||
Reference in New Issue
Block a user