test(frontend): vitest framework bootstrap + hot-path coverage gate (#536)

* test(frontend): vitest framework bootstrap + hot-path file coverage gate

Adds the harness for component, hook and store tests on top of the existing
util tests in src/utils/. Mirrors the backend rust-tests rollout: jsdom env,
v8 coverage, soft hot-path file gate, dedicated CI workflow.

What's in:
- vitest.config.ts: jsdom environment, v8 coverage, alias @ -> src
- src/test/setup.ts: jest-dom, @testing-library cleanup, vi.mock for
  @tauri-apps/api/{core,event} + plugin-shell, Map-backed Storage polyfill
  for Node 25 + jsdom 26 (both ship a broken native localStorage)
- src/test/mocks/tauri.ts: programmable onInvoke() / emitTauriEvent() helpers,
  auto-reset between tests
- src/test/helpers/factories.ts: makeTrack / makeTracks
- src/test/helpers/renderWithProviders.tsx: render() wrapped with
  MemoryRouter + I18nextProvider
- src/test/README.md: conventions doc (where tests go, how to mock Tauri,
  what to never mock)

Sample tests showing the patterns:
- src/components/CoverLightbox.test.tsx: component, queries by role
- src/store/previewStore.test.ts: store characterization, event handlers
  + stopPreview (startPreview deferred until the cross-store provider
  strategy is decided)

CI:
- .github/workflows/frontend-tests.yml: jobs for vitest, tsc, coverage +
  hot-path gate. coverage job carries continue-on-error: true (soft).
- .github/frontend-hot-path-files.txt: initial list (3 utils at >=70%).
  playerStore + the unfinished half of previewStore are deferred until
  Phase 1 coverage work lands.
- scripts/check-frontend-hot-path-coverage.sh: mirror of the rust gate.

npm scripts:
- test: one-shot run (unchanged)
- test⌚ vitest in watch mode
- test:coverage: v8 coverage + html / lcov / json-summary reports

57 / 57 tests pass; tsc --noEmit clean.

* chore(nix): sync npmDepsHash with package-lock.json

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.github/frontend-hot-path-files.txt

@@ -0,0 +1,28 @@
+# Hot-path source files for the per-file ≥70 % coverage gate (frontend).
+#
+# Mirrors `.github/hot-path-files.txt` for the Rust crates. Each entry is a
+# workspace-relative path; the gate script (`scripts/check-frontend-hot-path-
+# coverage.sh`) reads `coverage/coverage-summary.json` produced by
+# `vitest run --coverage` and warns when a listed file drops below the floor.
+#
+# Soft today (warnings only — the workflow carries `continue-on-error: true`).
+# Flip to a hard PR-blocker by removing `continue-on-error` from the
+# `frontend-tests` workflow once a few PRs have run cleanly.
+#
+# Curation rule (mirrors the backend list): a file belongs here when its
+# hot-path code dominates the file and ≥70 % is a reasonable floor. Files
+# that are partially covered today but contain large untested surface area
+# (e.g. `playerStore.ts`, the unfinished half of `previewStore.ts`) live
+# OUTSIDE the gate until their tests grow. Add them as Phase 1 coverage
+# work lands.
+#
+# Deferred from the gate, with current coverage shown for reference:
+#   - src/store/previewStore.ts          (33 % — only `_on*` + `stopPreview` covered)
+#   - src/store/playerStore.ts           (0 % — 3300-LOC monolith, Phase 2 target)
+#   - src/utils/dynamicColors.ts         (44 % — existing tests miss branches)
+#   - src/utils/shareLink.ts             (69 % — borderline, ~5 lines short)
+
+# ── utils (already at or above threshold) ────────────────────────────
+src/utils/coverArtRegisteredSizes.ts
+src/utils/serverDisplayName.ts
+src/utils/serverMagicString.ts

.github/workflows/frontend-tests.yml

@@ -0,0 +1,85 @@
+name: frontend-tests
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'vitest.config.ts'
+      - 'vite.config.ts'
+      - 'tsconfig.json'
+      - '.github/workflows/frontend-tests.yml'
+      - '.github/frontend-hot-path-files.txt'
+      - 'scripts/check-frontend-hot-path-coverage.sh'
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'vitest.config.ts'
+      - 'vite.config.ts'
+      - 'tsconfig.json'
+      - '.github/workflows/frontend-tests.yml'
+      - '.github/frontend-hot-path-files.txt'
+      - 'scripts/check-frontend-hot-path-coverage.sh'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: vitest run
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - name: vitest
+        run: npm test
+
+  typecheck:
+    name: tsc --noEmit
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - name: tsc
+        run: npx tsc --noEmit
+
+  coverage:
+    name: vitest --coverage (baseline + hot-path file gate)
+    # Two-layer gate: the script exits 1 when any listed file drops below the
+    # threshold (warning annotations show in the PR checks panel), but
+    # `continue-on-error: true` keeps it from BLOCKING merges. Drop the flag
+    # to flip the gate hard once we've watched a few PRs run cleanly.
+    runs-on: ubuntu-24.04
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - name: install jq
+        run: sudo apt-get update && sudo apt-get install -y jq
+      - run: npm ci
+      - name: vitest run --coverage
+        run: npx vitest run --coverage
+      - name: hot-path file coverage soft gate
+        run: bash scripts/check-frontend-hot-path-coverage.sh
+      - uses: actions/upload-artifact@v4
+        with:
+          name: frontend-coverage-lcov
+          path: coverage/lcov.info
+          if-no-files-found: error

.gitignore

@@ -34,6 +34,9 @@ src-tauri/target/
 src-tauri/gen/
 src-tauri/lcov.info
 
+# Frontend test coverage
+coverage/
+
 # Documentation
 CLAUDE.md
 

nix/upstream-sources.json

@@ -1,3 +1,3 @@
 {
-  "npmDepsHash": "sha256-5u9O1O7q936/Ik7/X++pK2Bg65+GYh0RdL4YVvasNSQ="
+  "npmDepsHash": "sha256-zcd6mudbopF0hlcJnFxwUOKpPt6IamfLmabSZ5rN7HI="
 }

package.json

@@ -9,7 +9,9 @@
     "tauri": "tauri",
     "tauri:dev": "tauri dev",
     "tauri:build": "tauri build",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "@fontsource-variable/dm-sans": "^5.2.8",
@@ -50,13 +52,18 @@
   },
   "devDependencies": {
     "@tauri-apps/cli": "^2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/md5": "^2.3.6",
     "@types/node": "^25.6.0",
     "@types/papaparse": "^5.5.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",
+    "@vitest/coverage-v8": "^4.1.5",
     "esbuild": "^0.28.0",
+    "jsdom": "^26.1.0",
     "typescript": "^6.0.3",
     "vite": "^8.0.10",
     "vitest": "^4.1.5"

scripts/check-frontend-hot-path-coverage.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+#
+# Hot-path file coverage gate — frontend, soft mode.
+#
+# Mirrors `scripts/check-hot-path-coverage.sh` for the Rust workspace. For
+# each source file listed in `.github/frontend-hot-path-files.txt`, verifies
+# that line coverage is at least $THRESHOLD %. Emits GitHub Actions warning
+# annotations for files below the floor; exits 1 when any file is below, but
+# the wrapping CI job carries `continue-on-error: true` so it doesn't block
+# merges yet (drop that flag once we've watched a few PRs run cleanly).
+#
+# Why files instead of per-function: v8 coverage's per-function data is
+# fragile under React Compiler / Vite minification — file-level line
+# coverage tracks the underlying intent ("is the hot-path file thoroughly
+# tested?") more robustly.
+#
+# Usage:
+#   scripts/check-frontend-hot-path-coverage.sh [<summary.json>] [<hot-path-list.txt>]
+#
+# Defaults:
+#   summary.json       — coverage/coverage-summary.json
+#   hot-path-list.txt  — .github/frontend-hot-path-files.txt
+#
+# Requires: jq.
+
+set -euo pipefail
+export LC_ALL=C
+
+JSON="${1:-coverage/coverage-summary.json}"
+HOT_PATH_LIST="${2:-.github/frontend-hot-path-files.txt}"
+THRESHOLD=70
+
+if [[ ! -f "$JSON" ]]; then
+    echo "::error::Coverage summary not found at $JSON. Did you run 'npm run test:coverage' first?"
+    exit 2
+fi
+
+if [[ ! -f "$HOT_PATH_LIST" ]]; then
+    echo "::error::Hot-path file list not found at $HOT_PATH_LIST"
+    exit 2
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+    echo "::error::jq not found in PATH. Install via apt-get install jq / brew install jq / winget install jqlang.jq"
+    exit 2
+fi
+
+# The v8 / Istanbul coverage-summary.json has the form:
+#   { "total": {...}, "<absolute-path>": { "lines": { "pct": 87.5 }, ... }, ... }
+# We want each file path + its line pct as a TSV keyed by basename suffix.
+ALL_FILES=$(mktemp)
+trap 'rm -f "$ALL_FILES"' EXIT
+jq -r 'to_entries[] | select(.key != "total") | [.key, .value.lines.pct] | @tsv' "$JSON" > "$ALL_FILES"
+
+TOTAL=0
+BELOW=0
+NOT_FOUND=0
+
+echo "── Hot-path file coverage check, frontend (threshold: ≥${THRESHOLD}%) ──"
+
+while IFS= read -r raw_line || [[ -n "$raw_line" ]]; do
+    line="${raw_line%%#*}"
+    line="${line#"${line%%[![:space:]]*}"}"
+    line="${line%"${line##*[![:space:]]}"}"
+    [[ -z "$line" ]] && continue
+    TOTAL=$((TOTAL + 1))
+
+    # Match suffix — JSON paths are absolute, hot-path list is workspace-relative.
+    pct=$(awk -F'\t' -v target="$line" '
+        {
+            path = $1
+            gsub(/\\\\/, "/", path)
+            gsub(/\\/, "/", path)
+            n = length(path)
+            tlen = length(target)
+            if (n >= tlen && substr(path, n - tlen + 1) == target) {
+                printf "%s\n", $2
+                exit
+            }
+        }
+    ' "$ALL_FILES")
+
+    if [[ -z "$pct" ]]; then
+        echo "::warning::Hot-path file '$line' not found in coverage report (deleted? renamed? or no test imports it yet)"
+        NOT_FOUND=$((NOT_FOUND + 1))
+        continue
+    fi
+
+    pct_int=${pct%.*}
+    if [[ "$pct_int" -lt "$THRESHOLD" ]]; then
+        printf "::warning::Hot-path file '%s': %.1f%% — below %d%%\n" "$line" "$pct" "$THRESHOLD"
+        BELOW=$((BELOW + 1))
+    else
+        printf "  ok  %s  %.1f%%\n" "$line" "$pct"
+    fi
+done < "$HOT_PATH_LIST"
+
+echo
+echo "── Summary ─────────────────────────────────────────────────────────"
+echo "Checked: $TOTAL hot-path file(s)"
+echo "Below threshold: $BELOW"
+echo "Not found: $NOT_FOUND"
+
+if [[ "$BELOW" -gt 0 ]]; then
+    exit 1
+fi
+exit 0

src/components/CoverLightbox.test.tsx

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi } from 'vitest';
+import { screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { renderWithProviders } from '@/test/helpers/renderWithProviders';
+import CoverLightbox from './CoverLightbox';
+
+describe('CoverLightbox', () => {
+  it('renders the cover image with the supplied src and alt', () => {
+    renderWithProviders(
+      <CoverLightbox src="https://example/cover.jpg" alt="Album cover" onClose={vi.fn()} />,
+    );
+
+    const img = screen.getByRole('img', { name: 'Album cover' });
+    expect(img).toHaveAttribute('src', 'https://example/cover.jpg');
+  });
+
+  it('calls onClose when the overlay is clicked', async () => {
+    const onClose = vi.fn();
+    renderWithProviders(
+      <CoverLightbox src="https://example/cover.jpg" alt="Album cover" onClose={onClose} />,
+    );
+
+    await userEvent.click(screen.getByRole('dialog'));
+
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('does not call onClose when the image itself is clicked (stops propagation)', async () => {
+    const onClose = vi.fn();
+    renderWithProviders(
+      <CoverLightbox src="https://example/cover.jpg" alt="Album cover" onClose={onClose} />,
+    );
+
+    await userEvent.click(screen.getByRole('img', { name: 'Album cover' }));
+
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it('calls onClose when Escape is pressed', () => {
+    const onClose = vi.fn();
+    renderWithProviders(
+      <CoverLightbox src="https://example/cover.jpg" alt="Album cover" onClose={onClose} />,
+    );
+
+    fireEvent.keyDown(window, { key: 'Escape' });
+
+    expect(onClose).toHaveBeenCalledOnce();
+  });
+
+  it('ignores other keys', () => {
+    const onClose = vi.fn();
+    renderWithProviders(
+      <CoverLightbox src="https://example/cover.jpg" alt="Album cover" onClose={onClose} />,
+    );
+
+    fireEvent.keyDown(window, { key: 'Enter' });
+    fireEvent.keyDown(window, { key: 'a' });
+
+    expect(onClose).not.toHaveBeenCalled();
+  });
+});

src/store/previewStore.test.ts

@@ -0,0 +1,140 @@
+/**
+ * Characterization tests for `previewStore`.
+ *
+ * Pattern demonstration: drives the store through its public action surface
+ * with the real Zustand instance, and uses the `onInvoke` helper to stub the
+ * Tauri commands the actions call. Aims to lock current behaviour before
+ * playerStore-adjacent refactoring lands in Phase 2.
+ *
+ * Scope here is intentionally narrow — the internal `_on*` event handlers
+ * plus `stopPreview`. `startPreview` adds dependencies on authStore /
+ * orbitStore and is covered in its own follow-up suite once we settle on a
+ * provider strategy for cross-store reads.
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { usePreviewStore } from './previewStore';
+import { onInvoke, invokeMock } from '@/test/mocks/tauri';
+
+function resetStore() {
+  usePreviewStore.setState({
+    previewingId: null,
+    previewingTrack: null,
+    elapsed: 0,
+    duration: 30,
+    audioStarted: false,
+  });
+}
+
+describe('previewStore — event handlers', () => {
+  beforeEach(resetStore);
+
+  describe('_onStart', () => {
+    it('flips audioStarted to true when the id matches the active preview', () => {
+      usePreviewStore.setState({
+        previewingId: 'song-1',
+        previewingTrack: { id: 'song-1', title: 't', artist: 'a' },
+      });
+
+      usePreviewStore.getState()._onStart('song-1');
+
+      expect(usePreviewStore.getState().audioStarted).toBe(true);
+      expect(usePreviewStore.getState().previewingId).toBe('song-1');
+    });
+
+    it('takes over the previewingId when the engine fires start for an unknown id', () => {
+      usePreviewStore.setState({ previewingId: null });
+
+      usePreviewStore.getState()._onStart('song-99');
+
+      const state = usePreviewStore.getState();
+      expect(state.previewingId).toBe('song-99');
+      expect(state.elapsed).toBe(0);
+      expect(state.audioStarted).toBe(true);
+    });
+  });
+
+  describe('_onProgress', () => {
+    it('updates elapsed + duration when the id matches', () => {
+      usePreviewStore.setState({ previewingId: 'song-1' });
+
+      usePreviewStore.getState()._onProgress('song-1', 12.5, 30);
+
+      const state = usePreviewStore.getState();
+      expect(state.elapsed).toBe(12.5);
+      expect(state.duration).toBe(30);
+    });
+
+    it('ignores progress for a stale id', () => {
+      usePreviewStore.setState({ previewingId: 'song-1', elapsed: 5 });
+
+      usePreviewStore.getState()._onProgress('song-stale', 99, 30);
+
+      expect(usePreviewStore.getState().elapsed).toBe(5);
+    });
+  });
+
+  describe('_onEnd', () => {
+    it('clears state when the id matches', () => {
+      usePreviewStore.setState({
+        previewingId: 'song-1',
+        previewingTrack: { id: 'song-1', title: 't', artist: 'a' },
+        elapsed: 27,
+        audioStarted: true,
+      });
+
+      usePreviewStore.getState()._onEnd('song-1');
+
+      const state = usePreviewStore.getState();
+      expect(state.previewingId).toBeNull();
+      expect(state.previewingTrack).toBeNull();
+      expect(state.elapsed).toBe(0);
+      expect(state.audioStarted).toBe(false);
+    });
+
+    it('ignores end events for a stale id', () => {
+      usePreviewStore.setState({ previewingId: 'song-1', elapsed: 5, audioStarted: true });
+
+      usePreviewStore.getState()._onEnd('song-stale');
+
+      expect(usePreviewStore.getState().previewingId).toBe('song-1');
+      expect(usePreviewStore.getState().audioStarted).toBe(true);
+    });
+  });
+});
+
+describe('previewStore — stopPreview', () => {
+  beforeEach(resetStore);
+
+  it('returns early without invoking when no preview is active', async () => {
+    await usePreviewStore.getState().stopPreview();
+
+    expect(invokeMock).not.toHaveBeenCalled();
+  });
+
+  it('invokes audio_preview_stop when a preview is active', async () => {
+    usePreviewStore.setState({ previewingId: 'song-1' });
+    onInvoke('audio_preview_stop', () => undefined);
+
+    await usePreviewStore.getState().stopPreview();
+
+    expect(invokeMock).toHaveBeenCalledWith('audio_preview_stop');
+  });
+
+  it('falls back to clearing state locally if invoke rejects', async () => {
+    usePreviewStore.setState({
+      previewingId: 'song-1',
+      previewingTrack: { id: 'song-1', title: 't', artist: 'a' },
+      audioStarted: true,
+    });
+    onInvoke('audio_preview_stop', () => {
+      throw new Error('engine offline');
+    });
+
+    await usePreviewStore.getState().stopPreview();
+
+    const state = usePreviewStore.getState();
+    expect(state.previewingId).toBeNull();
+    expect(state.previewingTrack).toBeNull();
+    expect(state.audioStarted).toBe(false);
+  });
+});

src/test/README.md

@@ -0,0 +1,125 @@
+# Frontend test framework
+
+Vitest + jsdom + @testing-library/react. Existing util tests in
+`src/utils/*.test.ts` keep working; this folder adds the harness for store,
+hook, component and (eventually) integration tests.
+
+## Layout
+
+```
+src/test/
+  setup.ts                      # global setup: jest-dom, @testing-library cleanup,
+                                # vi.mock for @tauri-apps/api/*
+  mocks/
+    tauri.ts                    # programmable invoke() + listen() helpers
+  helpers/
+    factories.ts                # makeTrack / makeTracks fixtures
+    renderWithProviders.tsx     # render() wrapped with MemoryRouter + i18n
+  CLAUDE.md                     # this file
+```
+
+## Running tests
+
+```bash
+npm test                       # one-shot run
+npm run test:watch             # watch mode
+npm run test:coverage          # with v8 coverage → ./coverage/
+```
+
+## Where tests go
+
+- **Co-located with the unit under test**: `Foo.tsx` → `Foo.test.tsx`,
+  `barStore.ts` → `barStore.test.ts`. Mirrors the existing util test layout
+  and avoids a parallel directory tree.
+- Vitest picks them up via `include: src/**/*.test.{ts,tsx}` in
+  `vitest.config.ts`.
+
+## Mocking Tauri
+
+`@tauri-apps/api/core` and `@tauri-apps/api/event` are mocked globally in
+`setup.ts`. To configure per-test behaviour, import the helpers in
+`mocks/tauri.ts`:
+
+```ts
+import { onInvoke, emitTauriEvent, invokeMock } from '@/test/mocks/tauri';
+
+beforeEach(() => {
+  onInvoke('audio_play', () => undefined);
+});
+
+it('responds to engine events', () => {
+  emitTauriEvent('audio:progress', { id: 't1', currentTime: 42 });
+  expect(invokeMock).toHaveBeenCalledWith('audio_play', { id: 't1' });
+});
+```
+
+Unhandled `invoke()` calls throw a descriptive error — tests are honest about
+which commands they exercise. Handlers are auto-cleared between tests.
+
+## Mocking HTTP
+
+For Subsonic / Navidrome / Last.fm calls, prefer **module-level mocks** for
+unit tests:
+
+```ts
+vi.mock('@/api/subsonic', () => ({
+  getAlbum: vi.fn(async () => ({ id: 'a1', tracks: [] })),
+  buildStreamUrl: (id: string) => `https://mock/stream/${id}`,
+}));
+```
+
+For broader integration tests that touch many endpoints we can introduce
+**MSW** later. The framework is intentionally MSW-free right now to keep
+the dep surface small until we need it.
+
+## Patterns
+
+### Pure utilities
+
+Direct import + assert (see `src/utils/dynamicColors.test.ts`). No setup
+needed beyond `import { describe, it, expect } from 'vitest'`.
+
+### Zustand stores
+
+- Import the hook, drive it via `useFooStore.getState()`.
+- Reset state in a `beforeEach` — Zustand stores are module-level singletons
+  and leak across tests otherwise.
+- Stub Tauri side effects via `onInvoke()`.
+- Use `emitTauriEvent()` to drive event-driven state transitions.
+
+See `src/store/previewStore.test.ts` for the reference pattern.
+
+### Components
+
+- `renderWithProviders(<MyComponent />)` from `helpers/renderWithProviders`.
+- Query by role / label / text first; fall back to `data-testid` only when
+  the DOM provides no semantic anchor.
+- Use `userEvent` (not `fireEvent`) for click / type / keyboard, with the
+  exception of `keydown` on `window` for global shortcut paths.
+
+See `src/components/CoverLightbox.test.tsx`.
+
+### Hooks
+
+Wrap in `renderHook()` from `@testing-library/react`. Provide custom
+wrappers when the hook reads from a provider.
+
+## What to NOT mock
+
+- **Real Zustand stores.** The whole point of characterization tests is to
+  exercise the actual state graph. Mock only at the system boundary
+  (Tauri / network / browser APIs).
+- **The router.** `MemoryRouter` via `renderWithProviders` is fine — don't
+  stub `useNavigate` etc. unless a test specifically inspects navigation.
+- **react-i18next.** `I18nextProvider` with the real `i18n.ts` instance is
+  cheap and avoids tests that lie about labels.
+
+## Coverage gates
+
+- `vitest run --coverage` writes `coverage/coverage-summary.json` which the
+  hot-path gate consumes.
+- `.github/frontend-hot-path-files.txt` lists the files held to ≥70% line
+  coverage by `scripts/check-frontend-hot-path-coverage.sh`.
+- CI runs both. The gate is currently soft (`continue-on-error: true`) —
+  flip to a hard PR-blocker once a few PRs run cleanly. Mirrors the backend
+  rust-tests rollout.

src/test/helpers/factories.ts

@@ -0,0 +1,33 @@
+/**
+ * Test fixture factories.
+ *
+ * Build minimal but valid domain objects with sensible defaults; override only
+ * the fields the test cares about. Keeps tests focused on behaviour rather
+ * than on assembling boilerplate.
+ */
+import type { Track } from '@/store/playerStore';
+
+let trackCounter = 0;
+
+export function makeTrack(overrides: Partial<Track> = {}): Track {
+  trackCounter += 1;
+  const id = overrides.id ?? `track-${trackCounter}`;
+  return {
+    id,
+    title: `Track ${trackCounter}`,
+    artist: 'Test Artist',
+    album: 'Test Album',
+    albumId: `album-${trackCounter}`,
+    duration: 180,
+    coverArt: id,
+    ...overrides,
+  } as Track;
+}
+
+export function makeTracks(n: number, overridesFn?: (i: number) => Partial<Track>): Track[] {
+  return Array.from({ length: n }, (_, i) => makeTrack(overridesFn?.(i) ?? {}));
+}
+
+export function resetFactoryCounters(): void {
+  trackCounter = 0;
+}

src/test/helpers/renderWithProviders.tsx

@@ -0,0 +1,35 @@
+/**
+ * Wraps `render()` from @testing-library/react with the providers most
+ * Psysonic components need: a router (for hooks like useNavigate / useParams)
+ * and i18n (for components that call `useTranslation`).
+ *
+ * Tests that don't need a specific route can call `renderWithProviders(<X />)`.
+ * Tests that need a specific URL pass `{ route: '/album/42' }`.
+ */
+import type { ReactElement, ReactNode } from 'react';
+import { render, type RenderOptions, type RenderResult } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { I18nextProvider } from 'react-i18next';
+import i18n from '@/i18n';
+
+interface WrapperOptions {
+  route?: string;
+}
+
+function makeWrapper({ route = '/' }: WrapperOptions) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <I18nextProvider i18n={i18n}>
+        <MemoryRouter initialEntries={[route]}>{children}</MemoryRouter>
+      </I18nextProvider>
+    );
+  };
+}
+
+export function renderWithProviders(
+  ui: ReactElement,
+  options: WrapperOptions & Omit<RenderOptions, 'wrapper'> = {},
+): RenderResult {
+  const { route, ...rest } = options;
+  return render(ui, { wrapper: makeWrapper({ route }), ...rest });
+}

src/test/mocks/tauri.ts

@@ -0,0 +1,82 @@
+/**
+ * Tauri test harness — programmable `invoke()` + `listen()` mocks.
+ *
+ * Usage in a test:
+ *
+ *   import { onInvoke, emitTauriEvent } from '@/test/mocks/tauri';
+ *
+ *   beforeEach(() => {
+ *     onInvoke('audio_play', () => undefined);
+ *     onInvoke('audio_get_state', () => ({ playing: true }));
+ *   });
+ *
+ *   it('emits progress', () => {
+ *     emitTauriEvent('audio:progress', { id: 't1', currentTime: 42 });
+ *   });
+ *
+ * Handlers are auto-cleared between tests (`beforeEach` hook below).
+ * Unhandled invokes throw — keeps tests honest about which commands they touch.
+ */
+import { beforeEach, vi } from 'vitest';
+import { invoke } from '@tauri-apps/api/core';
+import { listen } from '@tauri-apps/api/event';
+
+export type InvokeHandler = (args: unknown) => unknown | Promise<unknown>;
+export type EventCallback = (payload: unknown) => void;
+
+const invokeHandlers = new Map<string, InvokeHandler>();
+const eventListeners = new Map<string, EventCallback[]>();
+
+// Tauri's typed signatures are strict (InvokeArgs / Event<T>). Tests don't
+// need that level of precision — cast the mocks to `any` so the helpers
+// accept simple `{ payload }` envelopes and plain object args.
+const invokeMock = vi.mocked(invoke) as unknown as ReturnType<typeof vi.fn>;
+const listenMock = vi.mocked(listen) as unknown as ReturnType<typeof vi.fn>;
+
+invokeMock.mockImplementation(async (cmd: string, args?: unknown) => {
+  const handler = invokeHandlers.get(cmd);
+  if (!handler) {
+    throw new Error(
+      `Unhandled invoke('${cmd}'). Register via onInvoke('${cmd}', …) in the test.`,
+    );
+  }
+  return await handler(args);
+});
+
+listenMock.mockImplementation(
+  async (event: string, cb: (e: { payload: unknown }) => void) => {
+    const wrapped: EventCallback = (payload) =>
+      cb({ payload } as { payload: unknown });
+    const arr = eventListeners.get(event) ?? [];
+    arr.push(wrapped);
+    eventListeners.set(event, arr);
+    return () => {
+      const list = eventListeners.get(event);
+      if (!list) return;
+      const i = list.indexOf(wrapped);
+      if (i >= 0) list.splice(i, 1);
+    };
+  },
+);
+
+/** Register a handler for `invoke('<cmd>', …)`. Last-write-wins per command. */
+export function onInvoke(cmd: string, handler: InvokeHandler): void {
+  invokeHandlers.set(cmd, handler);
+}
+
+/** Synchronously deliver an `<event>` payload to every active listener. */
+export function emitTauriEvent(event: string, payload: unknown): void {
+  for (const cb of eventListeners.get(event) ?? []) cb(payload);
+}
+
+/** Clear all handlers + listeners + call counts. Wired to `beforeEach` below. */
+export function resetTauriMocks(): void {
+  invokeHandlers.clear();
+  eventListeners.clear();
+  invokeMock.mockClear();
+  listenMock.mockClear();
+}
+
+export { invokeMock, listenMock };
+
+beforeEach(resetTauriMocks);

src/test/setup.ts

@@ -0,0 +1,100 @@
+import '@testing-library/jest-dom/vitest';
+import { afterEach, vi } from 'vitest';
+import { cleanup } from '@testing-library/react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Node 25 ships a native `localStorage` global that is broken on this
+// platform — `typeof localStorage === 'object'` but `localStorage.getItem`
+// is `undefined`. jsdom 26 simply forwards to it, so both globalThis and
+// window expose a non-functional storage. Any code that runs
+// `localStorage.getItem(...)` at module load (e.g. `i18n.ts`, `authStore.ts`)
+// crashes before tests start.
+//
+// Fix: install a Map-backed polyfill that conforms to the DOM Storage
+// interface, on both globalThis and window. Per-test isolation comes from
+// the `afterEach(() => store.clear())` hook below.
+// ─────────────────────────────────────────────────────────────────────────────
+class MemoryStorage implements Storage {
+  private map = new Map<string, string>();
+  get length(): number {
+    return this.map.size;
+  }
+  key(index: number): string | null {
+    return Array.from(this.map.keys())[index] ?? null;
+  }
+  getItem(key: string): string | null {
+    return this.map.has(key) ? (this.map.get(key) as string) : null;
+  }
+  setItem(key: string, value: string): void {
+    this.map.set(String(key), String(value));
+  }
+  removeItem(key: string): void {
+    this.map.delete(String(key));
+  }
+  clear(): void {
+    this.map.clear();
+  }
+}
+
+const memLocal = new MemoryStorage();
+const memSession = new MemoryStorage();
+
+function installStorage(globalKey: 'localStorage' | 'sessionStorage', store: Storage) {
+  try {
+    Object.defineProperty(globalThis, globalKey, {
+      configurable: true,
+      writable: true,
+      value: store,
+    });
+  } catch {
+    /* ignore — non-configurable global */
+  }
+  if (typeof window !== 'undefined') {
+    try {
+      Object.defineProperty(window, globalKey, {
+        configurable: true,
+        writable: true,
+        value: store,
+      });
+    } catch {
+      /* ignore */
+    }
+  }
+}
+
+installStorage('localStorage', memLocal);
+installStorage('sessionStorage', memSession);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Global Tauri mocks.
+//
+// Every test file that imports `@tauri-apps/api/core` or `@tauri-apps/api/event`
+// gets these stubs. They start as bare `vi.fn()`s; the helpers in
+// `src/test/mocks/tauri.ts` attach programmable implementations the first time
+// they are imported by a test file. Tests that don't need Tauri can ignore
+// the helpers entirely.
+//
+// We mock here (in setupFiles) rather than per-test-file so individual tests
+// don't have to repeat `vi.mock('@tauri-apps/api/core', …)` boilerplate.
+// ─────────────────────────────────────────────────────────────────────────────
+vi.mock('@tauri-apps/api/core', () => ({
+  invoke: vi.fn(),
+  convertFileSrc: vi.fn((p: string) => `tauri://localhost/${p}`),
+}));
+
+vi.mock('@tauri-apps/api/event', () => ({
+  listen: vi.fn(),
+  emit: vi.fn(),
+  once: vi.fn(),
+}));
+
+// Linker for Tauri shell / dialog / store plugins — same idea. Extend as needed.
+vi.mock('@tauri-apps/plugin-shell', () => ({
+  open: vi.fn(async () => {}),
+}));
+
+afterEach(() => {
+  cleanup();
+  memLocal.clear();
+  memSession.clear();
+});

vitest.config.ts

@@ -1,8 +1,44 @@
 import { defineConfig } from 'vitest/config';
+import path from 'node:path';
 
 export default defineConfig({
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
   test: {
-    environment: 'node',
+    // jsdom by default — most new tests touch the DOM or React state. Pure
-    include: ['src/**/*.test.ts'],
+    // utility tests work fine in jsdom too, so we keep a single environment.
+    environment: 'jsdom',
+    globals: false,
+    setupFiles: ['./src/test/setup.ts'],
+    include: ['src/**/*.test.{ts,tsx}'],
+    exclude: [
+      'node_modules/**',
+      'dist/**',
+      'src-tauri/**',
+    ],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'json-summary', 'html', 'lcov'],
+      reportsDirectory: './coverage',
+      include: ['src/**/*.{ts,tsx}'],
+      exclude: [
+        'src/**/*.test.{ts,tsx}',
+        'src/**/*.d.ts',
+        'src/test/**',
+        'src/main.tsx',
+        'src/vite-env.d.ts',
+      ],
+      // Soft thresholds — Phase 0 is infra, not coverage push. Real numbers
+      // land in Phase 1 once cucadmuh and Frank lock the gate.
+      thresholds: {
+        lines: 0,
+        functions: 0,
+        branches: 0,
+        statements: 0,
+      },
+    },
   },
 });