test(recording-viewer): Vitest infrastructure with fixture-based parser tests

Predixx · Predixx · commit 1b9174ffe1b6 · 2026-04-21T17:14:25.000+02:00
- Install vitest 4.1.5, add test/test:watch scripts, vitest.config.ts (node env)
- Add resolveSchemaVersion() to parseSession.ts with precedence:
  metadata.schemaVersion &gt; sessionStart.schemaVersion &gt; 1 (legacy)
- Extend LoadedSession with required schemaVersion: number field
- Update App.tsx API load path to call resolveSchemaVersion() and pass it into setSession()
- Improve parseEventsFile() malformed-line handling: console.warn with 1-based line number
- Sync generated types: add schemaVersion to SessionStartEvent/SessionMetadata,
  recorderVersion to SessionMetadata (aligns with extension source)
- Add 4 fixture recordings: v1-basic, v2-basic, v2-no-metadata, malformed-last-line
- Add tsconfig.test.json for test type-checking scope
- 23 parser tests covering version resolution, new event types, malformed lines,
  legacy buildResult shape
diff --git a/recording-viewer/package-lock.json b/recording-viewer/package-lock.json
diff --git a/recording-viewer/package.json b/recording-viewer/package.json
@@ -8,7 +8,9 @@
     "build": "tsc -b && vite build",
     "lint": "eslint .",
     "preview": "vite preview",
-    "sync-types": "node scripts/sync-types.mjs"
+    "sync-types": "node scripts/sync-types.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "dependencies": {
     "react": "^19.2.4",
@@ -27,6 +29,7 @@
     "globals": "^17.4.0",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.56.1",
-    "vite": "^8.0.0"
+    "vite": "^8.0.0",
+    "vitest": "4.1.5"
   }
 }
diff --git a/recording-viewer/src/App.tsx b/recording-viewer/src/App.tsx
@@ -1,5 +1,6 @@
 import { useState, useCallback, useRef, useMemo } from 'react';
-import type { Annotation, AnnotationLabel, LoadedSession, RecordedEvent, SessionMetadata, ReplayEqSnapshot, VideoSyncConfig } from './types';
+import type { Annotation, AnnotationLabel, LoadedSession, RecordedEvent, SessionMetadata, SessionStartEvent, ReplayEqSnapshot, VideoSyncConfig } from './types';
+import { resolveSchemaVersion } from './parseSession';
 import { FileDropZone } from './components/FileDropZone';
 import { RecordingInfo } from './components/RecordingInfo';
 import { SessionList } from './components/SessionList';
@@ -102,7 +103,9 @@ function App() {
             setIsVideoPlaying(false);
             videoTimeRef.current = 0;
             setZoomedXDomain(null);
-            setSession({ metadata, events, fileName: sessionId, replayEq, annotations: loadedAnnotations });
+            const firstSessionStart = events.find(e => e.type === 'sessionStart') as SessionStartEvent | undefined;
+            const schemaVersion = resolveSchemaVersion(metadata, firstSessionStart);
+            setSession({ metadata, events, fileName: sessionId, schemaVersion, replayEq, annotations: loadedAnnotations });
         } catch (err) {
             console.error('Failed to load session:', err);
         } finally {
diff --git a/recording-viewer/src/generated/recordingTypes.ts b/recording-viewer/src/generated/recordingTypes.ts
@@ -80,6 +80,8 @@ export interface SessionStartEvent {
     exerciseId: number;
     participantId: string | undefined;
     exerciseRoot?: string;
+    /** Schema version for forward-compat parsing. Introduced in Block AB (version 2). */
+    schemaVersion?: number;
 }
 
 export interface SessionEndEvent {
@@ -277,4 +279,8 @@ export interface SessionMetadata {
     startTime: number;
     endTime: number | undefined;
     eventCount: number;
+    /** Schema version for forward-compat parsing. Introduced in Block D (version 2). */
+    schemaVersion?: number;
+    /** Recorder version string, set by storageWriter at write time. */
+    recorderVersion?: string;
 }
diff --git a/recording-viewer/src/parseSession.ts b/recording-viewer/src/parseSession.ts
@@ -1,13 +1,33 @@
-import type { RecordedEvent, SessionMetadata, LoadedSession } from './types';
+import type { RecordedEvent, SessionMetadata, SessionStartEvent } from './types';
+import type { LoadedSession } from './types';
+
+/**
+ * Resolve the schema version for a session.
+ *
+ * Precedence (highest to lowest):
+ *   1. metadata.schemaVersion  — written by storageWriter at flush time
+ *   2. firstSessionStartEvent.schemaVersion — written inline by recorder
+ *   3. 1 — legacy recordings that pre-date versioning
+ */
+export function resolveSchemaVersion(
+    metadata: SessionMetadata | undefined | null,
+    firstSessionStartEvent: SessionStartEvent | undefined,
+): number {
+    if (metadata?.schemaVersion != null) return metadata.schemaVersion;
+    if (firstSessionStartEvent?.schemaVersion != null) return firstSessionStartEvent.schemaVersion;
+    return 1;
+}
 
 export function parseEventsFile(text: string): RecordedEvent[] {
     const events: RecordedEvent[] = [];
-    for (const line of text.split('\n')) {
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
         if (line.trim().length === 0) continue;
         try {
             events.push(JSON.parse(line) as RecordedEvent);
         } catch {
-            // Skip malformed JSONL lines
+            console.warn(`[parseSession] Skipping malformed JSONL line ${i + 1}: ${line.slice(0, 80)}`);
         }
     }
     return events;
@@ -49,5 +69,8 @@ export async function parseDroppedFiles(files: FileList): Promise<LoadedSession>
         fileName = files[0].name;
     }
 
-    return { metadata, events, fileName };
+    const firstSessionStart = events.find((e): e is SessionStartEvent => e.type === 'sessionStart');
+    const schemaVersion = resolveSchemaVersion(metadata, firstSessionStart);
+
+    return { metadata, events, fileName, schemaVersion };
 }
diff --git a/recording-viewer/src/types.ts b/recording-viewer/src/types.ts
@@ -55,6 +55,8 @@ export interface LoadedSession {
     metadata: SessionMetadata | null;
     events: RecordedEvent[];
     fileName: string;
+    /** Resolved schema version: metadata.schemaVersion > sessionStart.schemaVersion > 1 */
+    schemaVersion: number;
     replayEq?: ReplayEqSnapshot[];
     annotations?: Annotation[];
 }
diff --git a/recording-viewer/test/fixtures/recordings/malformed-last-line/events.jsonl b/recording-viewer/test/fixtures/recordings/malformed-last-line/events.jsonl
@@ -0,0 +1,4 @@
+{"type":"sessionStart","timestamp":1700300000000,"exerciseId":55,"participantId":"student-4"}
+{"type":"textChange","timestamp":1700300001000,"uri":"file:///workspace/src/Broken.java","changes":[{"range":{"startLine":0,"startCharacter":0,"endLine":0,"endCharacter":0},"rangeOffset":0,"rangeLength":0,"text":"class Broken {"}]}
+{"type":"save","timestamp":1700300002000,"uri":"file:///workspace/src/Broken.java"}
+{"type":"textChange","ti
diff --git a/recording-viewer/test/fixtures/recordings/v1-basic/events.jsonl b/recording-viewer/test/fixtures/recordings/v1-basic/events.jsonl
@@ -0,0 +1,6 @@
+{"type":"sessionStart","timestamp":1700000000000,"exerciseId":42,"participantId":"student-1"}
+{"type":"textChange","timestamp":1700000001000,"uri":"file:///workspace/src/Main.java","changes":[{"range":{"startLine":0,"startCharacter":0,"endLine":0,"endCharacter":0},"rangeOffset":0,"rangeLength":0,"text":"public class Main {"}]}
+{"type":"save","timestamp":1700000002000,"uri":"file:///workspace/src/Main.java"}
+{"type":"textChange","timestamp":1700000003000,"uri":"file:///workspace/src/Main.java","changes":[{"range":{"startLine":1,"startCharacter":0,"endLine":1,"endCharacter":0},"rangeOffset":19,"rangeLength":0,"text":"    public static void main(String[] args) {}"}]}
+{"type":"save","timestamp":1700000004000,"uri":"file:///workspace/src/Main.java"}
+{"type":"sessionEnd","timestamp":1700000005000,"exerciseId":42}
diff --git a/recording-viewer/test/fixtures/recordings/v1-basic/metadata.json b/recording-viewer/test/fixtures/recordings/v1-basic/metadata.json
@@ -0,0 +1,8 @@
+{
+  "sessionId": "v1-basic-session",
+  "exerciseId": 42,
+  "participantId": "student-1",
+  "startTime": 1700000000000,
+  "endTime": 1700000005000,
+  "eventCount": 6
+}
diff --git a/recording-viewer/test/fixtures/recordings/v2-basic/events.jsonl b/recording-viewer/test/fixtures/recordings/v2-basic/events.jsonl
@@ -0,0 +1,11 @@
+{"type":"sessionStart","timestamp":1700100000000,"exerciseId":99,"participantId":"student-2","schemaVersion":2}
+{"type":"textChange","timestamp":1700100001000,"uri":"file:///workspace/src/Solution.java","changes":[{"range":{"startLine":0,"startCharacter":0,"endLine":0,"endCharacter":0},"rangeOffset":0,"rangeLength":0,"text":"class Solution {"}]}
+{"type":"irisChatSendAttempt","timestamp":1700100002000,"content":"How do I fix this?","status":"sent"}
+{"type":"intervention","timestamp":1700100003000,"action":"blocked","level":"notification","shouldIntervene":false,"eq":0.1,"confidence":"insufficient"}
+{"type":"fileSnapshotError","timestamp":1700100004000,"uri":"file:///workspace/src/Solution.java","reason":"File not found after 3 retries"}
+{"type":"fileCreate","timestamp":1700100005000,"uri":"file:///workspace/src/Helper.java"}
+{"type":"textDocumentOpen","timestamp":1700100006000,"uri":"file:///workspace/src/Helper.java"}
+{"type":"textDocumentClose","timestamp":1700100007000,"uri":"file:///workspace/src/Solution.java"}
+{"type":"fileDelete","timestamp":1700100008000,"uri":"file:///workspace/src/Helper.java"}
+{"type":"fileRename","timestamp":1700100009000,"oldUri":"file:///workspace/src/Helper.java","newUri":"file:///workspace/src/Util.java"}
+{"type":"sessionEnd","timestamp":1700100010000,"exerciseId":99}
diff --git a/recording-viewer/test/fixtures/recordings/v2-basic/metadata.json b/recording-viewer/test/fixtures/recordings/v2-basic/metadata.json
@@ -0,0 +1,10 @@
+{
+  "sessionId": "v2-basic-session",
+  "exerciseId": 99,
+  "participantId": "student-2",
+  "startTime": 1700100000000,
+  "endTime": 1700100010000,
+  "eventCount": 11,
+  "schemaVersion": 2,
+  "recorderVersion": "0.4.1"
+}
diff --git a/recording-viewer/test/fixtures/recordings/v2-no-metadata/events.jsonl b/recording-viewer/test/fixtures/recordings/v2-no-metadata/events.jsonl
@@ -0,0 +1,3 @@
+{"type":"sessionStart","timestamp":1700200000000,"exerciseId":77,"participantId":"student-3","schemaVersion":2}
+{"type":"textChange","timestamp":1700200001000,"uri":"file:///workspace/src/App.java","changes":[{"range":{"startLine":0,"startCharacter":0,"endLine":0,"endCharacter":0},"rangeOffset":0,"rangeLength":0,"text":"class App {}"}]}
+{"type":"sessionEnd","timestamp":1700200002000,"exerciseId":77}
diff --git a/recording-viewer/test/parseSession.test.ts b/recording-viewer/test/parseSession.test.ts
@@ -0,0 +1,211 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { parseEventsFile, parseMetadataFile, resolveSchemaVersion } from '../src/parseSession.ts';
+import type { SessionStartEvent } from '../src/types.ts';
+
+const FIXTURES = join(import.meta.dirname, 'fixtures/recordings');
+
+function readFixture(name: string, file: string): string {
+    return readFileSync(join(FIXTURES, name, file), 'utf-8');
+}
+
+// ── resolveSchemaVersion ───────────────────────────────────────────────────────
+
+describe('resolveSchemaVersion', () => {
+    it('returns metadata.schemaVersion when present (highest precedence)', () => {
+        const meta = { sessionId: 's', exerciseId: 1, participantId: undefined, startTime: 0, endTime: undefined, eventCount: 0, schemaVersion: 2 };
+        const start: SessionStartEvent = { type: 'sessionStart', timestamp: 0, exerciseId: 1, participantId: undefined, schemaVersion: 1 };
+        expect(resolveSchemaVersion(meta, start)).toBe(2);
+    });
+
+    it('falls back to sessionStart.schemaVersion when metadata has no version', () => {
+        const meta = { sessionId: 's', exerciseId: 1, participantId: undefined, startTime: 0, endTime: undefined, eventCount: 0 };
+        const start: SessionStartEvent = { type: 'sessionStart', timestamp: 0, exerciseId: 1, participantId: undefined, schemaVersion: 2 };
+        expect(resolveSchemaVersion(meta, start)).toBe(2);
+    });
+
+    it('returns 1 (legacy) when neither metadata nor sessionStart carries a version', () => {
+        const meta = { sessionId: 's', exerciseId: 1, participantId: undefined, startTime: 0, endTime: undefined, eventCount: 0 };
+        const start: SessionStartEvent = { type: 'sessionStart', timestamp: 0, exerciseId: 1, participantId: undefined };
+        expect(resolveSchemaVersion(meta, start)).toBe(1);
+    });
+
+    it('returns 1 (legacy) when both metadata and sessionStart are undefined', () => {
+        expect(resolveSchemaVersion(undefined, undefined)).toBe(1);
+    });
+
+    it('returns 1 (legacy) when metadata is null and sessionStart is undefined', () => {
+        expect(resolveSchemaVersion(null, undefined)).toBe(1);
+    });
+});
+
+// ── V1 fixture: no schemaVersion anywhere ─────────────────────────────────────
+
+describe('V1 basic fixture (no schemaVersion)', () => {
+    it('parses all 6 events', () => {
+        const text = readFixture('v1-basic', 'events.jsonl');
+        const events = parseEventsFile(text);
+        expect(events).toHaveLength(6);
+    });
+
+    it('first event is sessionStart without schemaVersion', () => {
+        const text = readFixture('v1-basic', 'events.jsonl');
+        const events = parseEventsFile(text);
+        const start = events[0] as SessionStartEvent;
+        expect(start.type).toBe('sessionStart');
+        expect(start.schemaVersion).toBeUndefined();
+    });
+
+    it('resolves schemaVersion to 1 from metadata and sessionStart', () => {
+        const metaText = readFixture('v1-basic', 'metadata.json');
+        const eventsText = readFixture('v1-basic', 'events.jsonl');
+        const metadata = parseMetadataFile(metaText);
+        const events = parseEventsFile(eventsText);
+        const start = events.find((e): e is SessionStartEvent => e.type === 'sessionStart');
+        expect(resolveSchemaVersion(metadata, start)).toBe(1);
+    });
+
+    it('metadata has no schemaVersion field', () => {
+        const metaText = readFixture('v1-basic', 'metadata.json');
+        const metadata = parseMetadataFile(metaText);
+        expect(metadata.schemaVersion).toBeUndefined();
+    });
+});
+
+// ── V2 fixture: new event types ───────────────────────────────────────────────
+
+describe('V2 basic fixture (schemaVersion 2, new event types)', () => {
+    it('parses all 11 events', () => {
+        const text = readFixture('v2-basic', 'events.jsonl');
+        const events = parseEventsFile(text);
+        expect(events).toHaveLength(11);
+    });
+
+    it('resolves schemaVersion to 2 (metadata wins over sessionStart)', () => {
+        const metaText = readFixture('v2-basic', 'metadata.json');
+        const eventsText = readFixture('v2-basic', 'events.jsonl');
+        const metadata = parseMetadataFile(metaText);
+        const events = parseEventsFile(eventsText);
+        const start = events.find((e): e is SessionStartEvent => e.type === 'sessionStart');
+        expect(resolveSchemaVersion(metadata, start)).toBe(2);
+    });
+
+    it('metadata carries recorderVersion', () => {
+        const metaText = readFixture('v2-basic', 'metadata.json');
+        const metadata = parseMetadataFile(metaText);
+        expect(metadata.recorderVersion).toBe('0.4.1');
+    });
+
+    it('contains an intervention event with action "blocked"', () => {
+        const text = readFixture('v2-basic', 'events.jsonl');
+        const events = parseEventsFile(text);
+        const intervention = events.find(e => e.type === 'intervention');
+        expect(intervention).toBeDefined();
+        expect((intervention as { action: string }).action).toBe('blocked');
+    });
+
+    it('contains fileSnapshotError, irisChatSendAttempt, fileCreate, textDocumentOpen, textDocumentClose, fileDelete, fileRename', () => {
+        const text = readFixture('v2-basic', 'events.jsonl');
+        const events = parseEventsFile(text);
+        const types = new Set(events.map(e => e.type));
+        expect(types.has('fileSnapshotError')).toBe(true);
+        expect(types.has('irisChatSendAttempt')).toBe(true);
+        expect(types.has('fileCreate')).toBe(true);
+        expect(types.has('textDocumentOpen')).toBe(true);
+        expect(types.has('textDocumentClose')).toBe(true);
+        expect(types.has('fileDelete')).toBe(true);
+        expect(types.has('fileRename')).toBe(true);
+    });
+});
+
+// ── V2 without metadata: schemaVersion comes from sessionStart ────────────────
+
+describe('V2 no-metadata fixture (schemaVersion from sessionStart)', () => {
+    it('parses 3 events', () => {
+        const text = readFixture('v2-no-metadata', 'events.jsonl');
+        const events = parseEventsFile(text);
+        expect(events).toHaveLength(3);
+    });
+
+    it('resolves schemaVersion to 2 from sessionStart when no metadata', () => {
+        const text = readFixture('v2-no-metadata', 'events.jsonl');
+        const events = parseEventsFile(text);
+        const start = events.find((e): e is SessionStartEvent => e.type === 'sessionStart');
+        expect(resolveSchemaVersion(null, start)).toBe(2);
+    });
+});
+
+// ── Conflicting versions: metadata wins ───────────────────────────────────────
+
+describe('resolveSchemaVersion — conflicting metadata vs sessionStart', () => {
+    it('metadata version 3 beats sessionStart version 2', () => {
+        const meta = { sessionId: 's', exerciseId: 1, participantId: undefined, startTime: 0, endTime: undefined, eventCount: 0, schemaVersion: 3 };
+        const start: SessionStartEvent = { type: 'sessionStart', timestamp: 0, exerciseId: 1, participantId: undefined, schemaVersion: 2 };
+        expect(resolveSchemaVersion(meta, start)).toBe(3);
+    });
+
+    it('metadata version 1 beats sessionStart version 2 (metadata always wins)', () => {
+        const meta = { sessionId: 's', exerciseId: 1, participantId: undefined, startTime: 0, endTime: undefined, eventCount: 0, schemaVersion: 1 };
+        const start: SessionStartEvent = { type: 'sessionStart', timestamp: 0, exerciseId: 1, participantId: undefined, schemaVersion: 2 };
+        expect(resolveSchemaVersion(meta, start)).toBe(1);
+    });
+});
+
+// ── Malformed last line ───────────────────────────────────────────────────────
+
+describe('malformed-last-line fixture (partial-write crash simulation)', () => {
+    beforeEach(() => {
+        vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it('parses the 3 valid events and skips the malformed line', () => {
+        const text = readFixture('malformed-last-line', 'events.jsonl');
+        const events = parseEventsFile(text);
+        expect(events).toHaveLength(3);
+    });
+
+    it('emits a console.warn for the malformed line', () => {
+        const text = readFixture('malformed-last-line', 'events.jsonl');
+        parseEventsFile(text);
+        expect(console.warn).toHaveBeenCalledOnce();
+        expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('[parseSession]'));
+    });
+
+    it('warn message contains the line number', () => {
+        const text = readFixture('malformed-last-line', 'events.jsonl');
+        parseEventsFile(text);
+        expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('4'));
+    });
+
+    it('last valid event is a save event', () => {
+        const text = readFixture('malformed-last-line', 'events.jsonl');
+        const events = parseEventsFile(text);
+        expect(events[events.length - 1]?.type).toBe('save');
+    });
+});
+
+// ── Legacy failedTests: string[] without failedTestDetails ────────────────────
+
+describe('legacy buildResult: failedTests as string[] without failedTestDetails', () => {
+    it('parses a buildResult with failedTests array and no failedTestDetails', () => {
+        const line = JSON.stringify({
+            type: 'buildResult',
+            timestamp: 1700000000000,
+            successful: false,
+            errorCount: 2,
+            failedTests: ['com.example.TestA#testFoo', 'com.example.TestB#testBar'],
+            buildFailed: false,
+        });
+        const events = parseEventsFile(line);
+        expect(events).toHaveLength(1);
+        const ev = events[0] as { type: string; failedTests: string[]; failedTestDetails?: unknown };
+        expect(ev.type).toBe('buildResult');
+        expect(ev.failedTests).toEqual(['com.example.TestA#testFoo', 'com.example.TestB#testBar']);
+        expect(ev.failedTestDetails).toBeUndefined();
+    });
+});
diff --git a/recording-viewer/tsconfig.test.json b/recording-viewer/tsconfig.test.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "skipLibCheck": true,
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src", "test"]
+}
diff --git a/recording-viewer/vitest.config.ts b/recording-viewer/vitest.config.ts

Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,8 @@ export interface LoadedSession {`
`55`	`55`	`metadata: SessionMetadata \| null;`
`56`	`56`	`events: RecordedEvent[];`
`57`	`57`	`fileName: string;`
	`58`	`+ /** Resolved schema version: metadata.schemaVersion > sessionStart.schemaVersion > 1 */`
	`59`	`+ schemaVersion: number;`
`58`	`60`	`replayEq?: ReplayEqSnapshot[];`
`59`	`61`	`annotations?: Annotation[];`
`60`	`62`	`}`