From f160ca6af8ce36cb00af3e6923a0d299d263f231 Mon Sep 17 00:00:00 2001 From: sudacode Date: Fri, 6 Mar 2026 00:25:24 -0800 Subject: [PATCH] test: add sqlite immersion verification lane --- .github/workflows/ci.yml | 8 + .github/workflows/release.yml | 8 + README.md | 6 +- ...sistence-tests-visible-and-reproducible.md | 53 ++++-- ...026-03-06-immersion-sqlite-verification.md | 155 ++++++++++++++++++ package.json | 5 +- .../immersion-tracker-service.test.ts | 6 + .../immersion-tracker/storage-session.test.ts | 6 + .../services/immersion-tracker/storage.ts | 4 +- 9 files changed, 232 insertions(+), 19 deletions(-) create mode 100644 docs/plans/2026-03-06-immersion-sqlite-verification.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index aae5105..1be3409 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,6 +20,11 @@ jobs: with: bun-version: 1.3.5 + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 22.12.0 + - name: Cache dependencies uses: actions/cache@v4 with: @@ -54,6 +59,9 @@ jobs: - name: Build (bundle) run: bun run build + - name: Immersion SQLite verification + run: bun run test:immersion:sqlite:dist + - name: Dist smoke suite run: bun run test:smoke:dist diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 1dba6d8..3bf81ad 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -26,6 +26,11 @@ jobs: with: bun-version: 1.3.5 + - name: Setup Node + uses: actions/setup-node@v4 + with: + node-version: 22.12.0 + - name: Install dependencies run: bun install --frozen-lockfile @@ -59,6 +64,9 @@ jobs: - name: Build (bundle) run: bun run build + - name: Immersion SQLite verification + run: bun run test:immersion:sqlite:dist + - name: Dist smoke suite run: bun run test:smoke:dist diff --git a/README.md b/README.md index ee66cc6..fb49afc 100644 --- a/README.md +++ b/README.md @@ -98,8 +98,12 @@ For full guides on configuration, Anki, Jellyfin, and more, see [docs.subminer.m ## Verification +- Run `bun run test` for the default Bun source suite. +- Run `bun run test:immersion:sqlite` to compile `dist/**` and execute the SQLite-backed immersion tracker persistence tests under Node with `node:sqlite` support; on Node 22 this lane enables that with `--experimental-sqlite`. +- If you only run the Bun source tests, the SQLite-backed immersion tracker cases may be skipped when `node:sqlite` is unavailable; those files now print an explicit warning telling you to use the dedicated SQLite lane for real DB coverage. - Run `bun run test:subtitle` to verify subtitle sync coverage for the maintained `alass`/`ffsubsync` test surface. -- That lane reuses `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`, which are also included in the broader `bun run test:core` suite. +- The SQLite lane covers persistence/finalization behavior beyond the seam tests, including session finalization, telemetry writes, and storage-session schema/write paths. +- The subtitle lane reuses `src/core/services/subsync.test.ts` and `src/subsync/utils.test.ts`, which are also included in the broader `bun run test:core` suite. ## Acknowledgments diff --git a/backlog/tasks/task-87.3 - Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md b/backlog/tasks/task-87.3 - Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md index 2655b8b..01cf4d3 100644 --- a/backlog/tasks/task-87.3 - Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md +++ b/backlog/tasks/task-87.3 - Immersion-tracking-verification-make-SQLite-backed-persistence-tests-visible-and-reproducible.md @@ -3,10 +3,11 @@ id: TASK-87.3 title: >- Immersion tracking verification: make SQLite-backed persistence tests visible and reproducible -status: To Do -assignee: [] +status: Done +assignee: + - Kyle Yasuda created_date: '2026-03-06 03:19' -updated_date: '2026-03-06 03:21' +updated_date: '2026-03-06 08:20' labels: - tests - immersion-tracking @@ -26,27 +27,49 @@ priority: medium ## Description - The immersion tracker is persistence-heavy, but its SQLite-backed tests are conditionally skipped in the standard Bun run when node:sqlite support is unavailable. That creates a blind spot around session finalization, telemetry persistence, and retention behavior. This task should establish a reliable automated verification path for the database-backed cases and make the prerequisite/runtime behavior explicit to contributors and CI. - ## Acceptance Criteria - - -- [ ] #1 Database-backed immersion tracking tests run in at least one documented automated command that is practical for contributors or CI to execute. -- [ ] #2 If the current runtime cannot execute the SQLite-backed tests, the repository exposes that limitation clearly instead of silently reporting a misleading green result. -- [ ] #3 Contributor-facing documentation explains how to run the immersion tracker verification lane and any environment prerequisites it depends on. -- [ ] #4 The resulting verification covers session persistence or finalization behavior that is not exercised by the pure seam tests alone. +- [x] #1 Database-backed immersion tracking tests run in at least one documented automated command that is practical for contributors or CI to execute. +- [x] #2 If the current runtime cannot execute the SQLite-backed tests, the repository exposes that limitation clearly instead of silently reporting a misleading green result. +- [x] #3 Contributor-facing documentation explains how to run the immersion tracker verification lane and any environment prerequisites it depends on. +- [x] #4 The resulting verification covers session persistence or finalization behavior that is not exercised by the pure seam tests alone. ## Implementation Plan +Implementation plan recorded in `docs/plans/2026-03-06-immersion-sqlite-verification.md`. -1. Confirm which SQLite-backed immersion tests are currently skipped and why in the standard Bun environment. -2. Establish a reproducible command or lane for the DB-backed cases, or make the unsupported-runtime limitation explicit and actionable. -3. Document prerequisites and expected behavior for contributors and CI. -4. Verify at least one persistence/finalization path beyond the seam tests is exercised by the new lane. +1. Update `src/core/services/immersion-tracker-service.test.ts` and `src/core/services/immersion-tracker/storage-session.test.ts` so unsupported `node:sqlite` runtimes emit an explicit skip reason instead of a silent top-level skip alias. +2. Add a dedicated `package.json` SQLite verification lane that runs both immersion persistence suites together under a runtime with `node:sqlite` support, likely via built `dist/**` tests executed by Node. +3. Wire that lane into `.github/workflows/ci.yml` and `.github/workflows/release.yml` so automated verification includes a real DB-backed persistence/finalization check. +4. Document the new command, prerequisites, and coverage in `README.md`, including the distinction between Bun's default lane and the reproducible SQLite lane. +5. Validate the final lane by running the dedicated command and confirming it exercises persistence/finalization behavior beyond the seam-only tests. + +Execution adjustment: the reproducible lane uses `node --experimental-sqlite --test ...` because Node 22 exposes `node:sqlite` behind the experimental flag. Running that lane also exposed placeholder-count mismatches in `src/core/services/immersion-tracker/storage.ts`, so the final implementation includes a small SQL placeholder fix required for the new cross-runtime verification path. + +## Implementation Notes + + +Confirmed Bun 1.3.5 lacks `node:test` `t.skip()` support, so explicit unsupported-runtime messaging is surfaced with file-level warnings while the SQLite-backed tests remain conditionally skipped. + +Added `test:immersion:sqlite:src`, `test:immersion:sqlite:dist`, and `test:immersion:sqlite` scripts; the source lane now prints explicit warnings when `node:sqlite` is unavailable, and the dist lane runs both SQLite-backed immersion suites under Node with `--experimental-sqlite`. + +Wired the dist SQLite lane into `.github/workflows/ci.yml` and `.github/workflows/release.yml` after the bundle build, with explicit `actions/setup-node@v4` provisioning for Node 22.12.0. + +Fixed SQL prepared-statement placeholder counts in `src/core/services/immersion-tracker/storage.ts`, which the new Node-backed SQLite lane surfaced immediately. + +Verification: `bun run test:immersion:sqlite:src` -> pass with explicit unsupported-runtime warnings and 10 skips under Bun 1.3.5; `bun run test:immersion:sqlite` -> pass with 14/14 tests under Node 22.12.0 + `--experimental-sqlite`. + + +## Final Summary + + +Added an explicit SQLite-backed immersion verification lane and documented it so persistence-heavy coverage is no longer hidden behind Bun-only skips. `package.json` now exposes source and dist SQLite scripts, the source test files print actionable warnings when `node:sqlite` is unavailable, and `README.md` explains the dedicated contributor command plus its Node 22 `--experimental-sqlite` prerequisite. + +Automated verification now includes the new dist lane in both `.github/workflows/ci.yml` and `.github/workflows/release.yml` after build output is available. While wiring the reproducible Node lane, it exposed placeholder-count mismatches in `src/core/services/immersion-tracker/storage.ts`; fixing those placeholders makes the SQLite-backed persistence/finalization tests pass cross-runtime, covering session finalization, telemetry persistence, and storage-session write paths. + diff --git a/docs/plans/2026-03-06-immersion-sqlite-verification.md b/docs/plans/2026-03-06-immersion-sqlite-verification.md new file mode 100644 index 0000000..edf9904 --- /dev/null +++ b/docs/plans/2026-03-06-immersion-sqlite-verification.md @@ -0,0 +1,155 @@ +# Immersion SQLite Verification Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Make the SQLite-backed immersion tracking persistence tests visible in the repo's verification surface and reproducible through at least one documented automated command. + +**Architecture:** Keep the existing Bun fast lane intact for routine local verification, but add an explicit SQLite verification lane that runs the database-backed immersion tests under a runtime with `node:sqlite` support. Surface unsupported-runtime behavior clearly in the source tests and contributor docs so skipped or omitted coverage is no longer mistaken for a fully green persistence lane. + +**Tech Stack:** TypeScript, Bun scripts in `package.json`, Node's built-in `node:test` and `node:sqlite`, GitHub Actions workflows, Markdown docs in `README.md`. + +--- + +### Task 1: Audit and expose the SQLite-backed immersion test surface + +**Files:** + +- Modify: `src/core/services/immersion-tracker-service.test.ts` +- Modify: `src/core/services/immersion-tracker/storage-session.test.ts` +- Reference: `src/main/runtime/registry.test.ts` + +**Step 1: Write the failing test** + +Refactor the SQLite-gated immersion tests so missing `node:sqlite` support is reported with an explicit skip reason instead of a silent top-level `test.skip` alias. + +**Step 2: Run test to verify it fails** + +Run: `bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts` +Expected: the current output shows generic skips or hides the storage-session suite from normal scripted verification, which is too opaque for contributors. + +**Step 3: Write minimal implementation** + +Mirror the `src/main/runtime/registry.test.ts` pattern: add a helper that either loads `DatabaseSync` or skips with a message like `requires node:sqlite support in this runtime`, then wrap each SQLite-backed test through that helper. + +**Step 4: Run test to verify it passes** + +Run: `bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts` +Expected: PASS, with explicit skip messages in unsupported runtimes. + +### Task 2: Add a reproducible SQLite verification command + +**Files:** + +- Modify: `package.json` +- Reference: `src/core/services/immersion-tracker-service.test.ts` +- Reference: `src/core/services/immersion-tracker/storage-session.test.ts` + +**Step 1: Write the failing test** + +Add a dedicated script contract for the SQLite-backed immersion verification lane so both persistence-heavy suites are intentionally grouped and runnable together. + +**Step 2: Run test to verify it fails** + +Run: `bun run test:immersion:sqlite` +Expected: FAIL because no such reproducible lane exists yet. + +**Step 3: Write minimal implementation** + +Update `package.json` with explicit scripts for the SQLite lane. Prefer a command shape that actually executes the built JS tests under Node with `node:sqlite` support, for example: + +- `test:immersion:sqlite:dist`: `node --test dist/core/services/immersion-tracker-service.test.js dist/core/services/immersion-tracker/storage-session.test.js` +- `test:immersion:sqlite`: `bun run build && bun run test:immersion:sqlite:dist` + +If build cost or runtime behavior requires a small adjustment, keep the core contract the same: one documented command must run both SQLite-backed immersion suites end-to-end. + +**Step 4: Run test to verify it passes** + +Run: `bun run test:immersion:sqlite` +Expected: PASS in a Node runtime with `node:sqlite`, executing both persistence suites without Bun-only skips. + +### Task 3: Wire the SQLite lane into automated verification + +**Files:** + +- Modify: `.github/workflows/ci.yml` +- Modify: `.github/workflows/release.yml` +- Reference: `package.json` + +**Step 1: Write the failing test** + +Add the new SQLite immersion lane to the repo's automated verification so contributors and CI can rely on a real persistence check rather than the Bun fast lane alone. + +**Step 2: Run test to verify it fails** + +Run: `bun run test:immersion:sqlite` +Expected: local command may pass, but CI/release workflows still omit the lane entirely. + +**Step 3: Write minimal implementation** + +Update both workflows to provision a Node version with `node:sqlite` support before the SQLite lane runs, then execute `bun run test:immersion:sqlite` in the quality gate after the bundle build produces `dist/**` test files. + +**Step 4: Run test to verify it passes** + +Run: `bun run test:immersion:sqlite` +Expected: PASS locally, and workflow definitions clearly show the SQLite lane as part of automated verification. + +### Task 4: Document contributor-facing prerequisites and commands + +**Files:** + +- Modify: `README.md` +- Reference: `package.json` +- Reference: `.github/workflows/ci.yml` + +**Step 1: Write the failing test** + +Extend the verification docs so contributors can discover the SQLite lane, know why the Bun source lane may skip those cases, and understand which command reproduces the persistence coverage. + +**Step 2: Run test to verify it fails** + +Run: `grep -n "test:immersion:sqlite" README.md` +Expected: FAIL because the dedicated immersion SQLite lane is undocumented. + +**Step 3: Write minimal implementation** + +Update `README.md` to document: + +- the Bun fast/default lane versus the SQLite persistence lane +- the `node:sqlite` prerequisite for the reproducible command +- that the dedicated lane covers session persistence/finalization behavior beyond seam tests + +**Step 4: Run test to verify it passes** + +Run: `grep -n "test:immersion:sqlite" README.md && grep -n "node:sqlite" README.md` +Expected: PASS, with clear contributor guidance. + +### Task 5: Verify persistence coverage end-to-end + +**Files:** + +- Test: `src/core/services/immersion-tracker-service.test.ts` +- Test: `src/core/services/immersion-tracker/storage-session.test.ts` +- Reference: `README.md` +- Reference: `package.json` + +**Step 1: Write the failing test** + +Prove the final lane exercises real DB-backed persistence/finalization paths, not just the seam tests. + +**Step 2: Run test to verify it fails** + +Run: `bun run test:immersion:sqlite` +Expected: before implementation, the command does not exist or does not cover both SQLite-backed suites. + +**Step 3: Write minimal implementation** + +Keep the dedicated lane pointed at both existing SQLite-backed test files so it covers representative finalization and persistence behavior such as: + +- `destroy finalizes active session and persists final telemetry` +- `start/finalize session updates ended_at and status` +- `executeQueuedWrite inserts event and telemetry rows` + +**Step 4: Run test to verify it passes** + +Run: `bun run test:immersion:sqlite` +Expected: PASS, with those DB-backed persistence/finalization cases executing successfully under Node. diff --git a/package.json b/package.json index ac2d06e..9d4390c 100644 --- a/package.json +++ b/package.json @@ -38,7 +38,10 @@ "build:appimage": "bun run build && electron-builder --linux AppImage", "build:mac": "bun run build && electron-builder --mac dmg zip", "build:mac:unsigned": "bun run build && env -u APPLE_ID -u APPLE_APP_SPECIFIC_PASSWORD -u APPLE_TEAM_ID -u CSC_LINK -u CSC_KEY_PASSWORD CSC_IDENTITY_AUTO_DISCOVERY=false electron-builder --mac dmg zip", - "build:mac:zip": "bun run build && electron-builder --mac zip" + "build:mac:zip": "bun run build && electron-builder --mac zip", + "test:immersion:sqlite:src": "bun test src/core/services/immersion-tracker-service.test.ts src/core/services/immersion-tracker/storage-session.test.ts", + "test:immersion:sqlite:dist": "node --experimental-sqlite --test dist/core/services/immersion-tracker-service.test.js dist/core/services/immersion-tracker/storage-session.test.js", + "test:immersion:sqlite": "bun run tsc && bun run test:immersion:sqlite:dist" }, "keywords": [ "anki", diff --git a/src/core/services/immersion-tracker-service.test.ts b/src/core/services/immersion-tracker-service.test.ts index 2c2e21c..5c8a173 100644 --- a/src/core/services/immersion-tracker-service.test.ts +++ b/src/core/services/immersion-tracker-service.test.ts @@ -27,6 +27,12 @@ const DatabaseSync: DatabaseSyncCtor | null = (() => { })(); const testIfSqlite = DatabaseSync ? test : test.skip; +if (!DatabaseSync) { + console.warn( + 'Skipping SQLite-backed immersion tracker persistence tests in this runtime; run `bun run test:immersion:sqlite` for real DB coverage.', + ); +} + let trackerCtor: ImmersionTrackerServiceCtor | null = null; async function loadTrackerCtor(): Promise { diff --git a/src/core/services/immersion-tracker/storage-session.test.ts b/src/core/services/immersion-tracker/storage-session.test.ts index 66d2d18..1fd28de 100644 --- a/src/core/services/immersion-tracker/storage-session.test.ts +++ b/src/core/services/immersion-tracker/storage-session.test.ts @@ -23,6 +23,12 @@ const DatabaseSync: DatabaseSyncCtor | null = (() => { })(); const testIfSqlite = DatabaseSync ? test : test.skip; +if (!DatabaseSync) { + console.warn( + 'Skipping SQLite-backed immersion tracker storage/session tests in this runtime; run `bun run test:immersion:sqlite` for real DB coverage.', + ); +} + function makeDbPath(): string { const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'subminer-imm-storage-session-')); return path.join(dir, 'immersion.sqlite'); diff --git a/src/core/services/immersion-tracker/storage.ts b/src/core/services/immersion-tracker/storage.ts index 3066aa5..277fadc 100644 --- a/src/core/services/immersion-tracker/storage.ts +++ b/src/core/services/immersion-tracker/storage.ts @@ -315,7 +315,7 @@ export function createTrackerPreparedStatements(db: DatabaseSync): TrackerPrepar lookup_hits, pause_count, pause_ms, seek_forward_count, seek_backward_count, media_buffer_events, CREATED_DATE, LAST_UPDATE_DATE ) VALUES ( - ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ? + ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ? ) `), eventInsertStmt: db.prepare(` @@ -323,7 +323,7 @@ export function createTrackerPreparedStatements(db: DatabaseSync): TrackerPrepar session_id, ts_ms, event_type, line_index, segment_start_ms, segment_end_ms, words_delta, cards_delta, payload_json, CREATED_DATE, LAST_UPDATE_DATE ) VALUES ( - ?, ?, ?, ?, ?, ?, ?, ?, ?, ? + ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ? ) `), wordUpsertStmt: db.prepare(`