Skip to content

Testing

Suite Command (from) Network In CI
Backend unit (≈420 tests) python -m pytest -m "not integration" (amp/) no yes
Backend coverage add --cov=backend --cov-report=term-missing no yes, floor 60 % (currently ~87 %)
Backend integration python -m pytest -m integration (amp/) yes no
Frontend unit npm test (amp/frontend/) no yes (Tauri workflow)
Rust cargo test (amp/frontend/src-tauri/) no no
Lint ruff check amp/backend/ (repo root) no yes
Type check + bundle npm run build (amp/frontend/) no yes (via tauri build)

Backend unit tests

amp/backend/tests/, fully mocked (no network, no yt-dlp calls). One file per module:

File Covers
test_config.py defaults, directory creation, configure_paths / restore, models CRUD
test_mp4.py box iteration (largesize, size 0, truncation), sidx v0/v1/hierarchical, real header fixture
test_layout.py virtual layout, Range → segment mapping, position → segment, layout_id
test_extractor.py format selection, error classification, build_ydl_opts, SingleFlight, caches, client rotation, cookie handling
test_registry.py the segment state machine
test_downloader.py heap ordering, superseded items, fetch_segment checks, unique temp files
test_cache.py LRU with touch, protection rules, accounting, reconciliation
test_serving.py Range parsing, first-segment JSON errors, mid-stream abort, vanished files
test_playback.py buffer_plan, session
test_streaming.py StreamingService: sidx tables, layout identity, ensure_segment, 403 refresh, buffer policy
test_play_api.py /play contract, error codes, superseded plays, prefetch
test_endpoints.py middleware (Host, Origin, token), route order, auth and log routes
test_library_api.py song/playlist/album normalization, song → album, loudness, likes, saved queues
test_history.py /api/history: add, list (days filter, percent), validation, delete / clear
test_widget.py OBS widget server: page, now.json, Host check, position extrapolation
test_auth.py SAPISIDHASH, credential store v2, v1 migration, cookie filtering, Netscape file
test_lifecycle.py CLI args, data dir, PID file, socket bind, parent watch (incl. a real subprocess that must exit < 3 s after stdin EOF), log rotation

Fixtures (conftest.py)

Fixture Gives
temp_dirs a temporary data dir + DB through settings.configure_paths(), restored afterwards
reset_singletons (autouse) fresh service singletons for every test
client, auth_headers TestClient of an app with a token, and its headers
client_no_auth, no_auth_headers the same in open mode

Test-writing rules

  • Redirect storage with temp_dirs. Never monkeypatch.setattr(settings, "_cache_dir", …): with pydantic 2.14 the undo deletes the attribute and breaks every later test.
  • TestClient requests need Host: 127.0.0.1:8000, or the middleware answers 403.
  • Don't make real network calls in unit tests: mock requests / yt-dlp.

tests/fixtures/itag140_head.bin is the first 1,012 bytes (ftyp + moov + sidx, no audio) of a real itag 140 stream, used by the MP4 parser tests.

Integration tests

Marked @pytest.mark.integration, deselected by default in CI. They hit YouTube for real, take a couple of minutes, and work signed out.

File Does
test_integration.py extraction, segment table, first segments, Range reads, seek, eviction and reconciliation on pinned songs (dQw4w9WgXcQ, LTDxBgP0lqA)
test_integration_download.py downloads every segment of one song and checks that init + segments == one GET of the CDN file (sha256). Song: BAgTQhR8MLo, override with AMP_TEST_SONG_ID
cd amp
python -m pytest backend/tests/test_integration_download.py -m integration -v -s
AMP_TEST_SONG_ID=Tmz3mpOq8aE python -m pytest backend/tests/test_integration_download.py -m integration -v -s

Run them after every yt-dlp upgrade. If a pinned song disappears or gets region-blocked, replace its ID.

Frontend tests

vitest, for the pure helpers that don't need a DOM:

  • src/player/player.test.ts: describeError, describeMediaError, queue persistence (round trip, junk input, clamping), shouldPrefetch.
  • src/player/queue.test.ts: queue edits, shuffle / restore, navigation and repeat.
  • src/player/history.test.ts: HistoryTracker (forward time only, end reasons), parsePending.
  • src/player/keyboard.test.ts: space bar outside text fields.
  • src/settings.test.ts: parseSettings, accent contrast (onAccentColor), fadeGain, crossfadeDue, normalizationGain.
  • src/authSession.test.ts: badge labels, a 401 from /api/user/* refreshes the status.

Documentation screenshots

The images in docs/assets/screenshots/ come from real runs. To refresh the app's after a UI change, start a backend on a scratch data folder (the script adds history entries and saved queues) and the Vite dev server, then run the script (Node 22+, Edge or Chrome):

cd amp
python -m backend.main --data-dir /tmp/amp-shots     # terminal 1
cd frontend && npm run dev                           # terminal 2
node scripts/docs_screenshots.mjs                    # terminal 3, from amp/; --browser <path> for Chrome

It searches, plays a song, then captures Search, History, Saved queues, Settings and Developer in the dark theme, History and Settings in the light theme, and the OBS widget (transparent PNG). The launcher screenshots (launcher-*.png) were taken by hand from app.py.

Manual checks

The UI itself has no automated tests. When changing playback, check by hand in the app: play an uncached song, seek into grey segments, skip quickly through several songs (only the last should play), restart the app (queue restored, paused), and watch Logs → API relay for the TTFA lines.