test: add unit test target with first 19 tests over the pure core

jasonzh0 · jasonzh0 · commit ff6f8a1e9ee7 · 2026-07-02T00:16:35.000-04:00
The repo had zero automated tests. This adds an app-hosted
CineScreenTests target (project.yml + explicit scheme, make test) and
covers the logic where the recent bug fixes live:

- Spring/adaptive smoothing: convergence, the zero-smoothTime click
  collapse staying finite, blend endpoints + monotonicity.
- RenderSnapshot: proximity-factor binary search, mouse-ups not
  collapsing smoothing, lag urgency, zoom ramp/identity, pan-table
  monotonicity, defensive section sorting, cursor interpolation.
- Metadata: encode/decode round trip and back-compat decode of files
  missing the newer optional fields.
- Zoom generation: click clustering, sorted non-overlapping output,
  bounds clamping, mouse-up filtering.
- ProjectsLibrary: descriptor creation/collisions and the marker check
  that keeps arbitrary folders out of the (deletable) project list.
diff --git a/Makefile b/Makefile
@@ -32,6 +32,15 @@ build: project
 	  -derivedDataPath $(BUILD_DIR)/derived \
 	  build
 
+.PHONY: test
+test: project
+	xcodebuild \
+	  -project $(PROJECT) \
+	  -scheme $(SCHEME) \
+	  -configuration $(CONFIG_DEBUG) \
+	  -derivedDataPath $(BUILD_DIR)/derived \
+	  test
+
 .PHONY: build-release
 build-release: project
 	xcodebuild \
@@ -100,6 +109,7 @@ help:
 	@echo "Targets:"
 	@echo "  project        — regenerate $(PROJECT) from project.yml"
 	@echo "  build          — debug build"
+	@echo "  test           — run unit tests"
 	@echo "  build-release  — release build"
 	@echo "  archive        — create xcarchive"
 	@echo "  export         — export signed .app from archive"
diff --git a/Tests/CineScreenTests/Fixtures.swift b/Tests/CineScreenTests/Fixtures.swift
@@ -0,0 +1,65 @@
+import Foundation
+@testable import CineScreen
+
+/// Shared builders for metadata fixtures used across the unit tests.
+enum Fixtures {
+    static func metadata(
+        width: Int = 2000,
+        height: Int = 1000,
+        duration: Double = 10_000,
+        keyframes: [CursorKeyframe] = [],
+        clicks: [ClickEvent] = [],
+        sections: [ZoomSection] = [],
+        zoomEnabled: Bool = true,
+        webcamOffsetMs: Double? = nil
+    ) -> RecordingMetadata {
+        RecordingMetadata(
+            version: RecordingMetadata.currentVersion,
+            video: VideoInfo(
+                path: "/tmp/fixture.mp4",
+                width: width,
+                height: height,
+                frameRate: 60,
+                duration: duration
+            ),
+            cursor: CursorTrack(
+                keyframes: keyframes,
+                segments: nil,
+                config: CursorConfig(size: 96, shape: .arrow, motionBlur: nil, hideWhenStatic: nil)
+            ),
+            zoom: ZoomTrack(
+                sections: sections,
+                config: ZoomConfig(
+                    enabled: zoomEnabled,
+                    level: 2.0,
+                    transitionSpeed: 300,
+                    padding: 0,
+                    followSpeed: 1.0,
+                    smoothness: nil,
+                    animationStyle: .mellow,
+                    deadZone: nil,
+                    motionBlur: nil,
+                    physics: nil,
+                    autoZoom: false
+                )
+            ),
+            clicks: clicks,
+            effects: nil,
+            trim: nil,
+            webcamOffsetMs: webcamOffsetMs,
+            createdAt: 0
+        )
+    }
+
+    static func keyframe(_ t: Double, _ x: Double, _ y: Double) -> CursorKeyframe {
+        CursorKeyframe(timestamp: t, x: x, y: y, size: nil, shape: .arrow, easing: .linear)
+    }
+
+    static func click(_ t: Double, x: Double = 0, y: Double = 0, action: ClickAction = .down) -> ClickEvent {
+        ClickEvent(timestamp: t, x: x, y: y, button: .left, action: action)
+    }
+
+    static func section(_ start: Double, _ end: Double, scale: Double = 2.0) -> ZoomSection {
+        ZoomSection(startTime: start, endTime: end, scale: scale, centerX: 0, centerY: 0)
+    }
+}
diff --git a/Tests/CineScreenTests/MetadataTests.swift b/Tests/CineScreenTests/MetadataTests.swift
@@ -0,0 +1,34 @@
+import XCTest
+@testable import CineScreen
+
+final class MetadataTests: XCTestCase {
+    func testRoundTripPreservesEverything() throws {
+        let original = Fixtures.metadata(
+            keyframes: [Fixtures.keyframe(0, 1, 2), Fixtures.keyframe(100, 3, 4)],
+            clicks: [Fixtures.click(50)],
+            sections: [Fixtures.section(10, 500, scale: 3)],
+            webcamOffsetMs: 456.7
+        )
+        let decoded = try RecordingMetadata.decode(from: original.encode())
+        XCTAssertEqual(decoded, original)
+    }
+
+    /// Files written before the newer optional fields existed must still
+    /// decode, with those fields nil.
+    func testDecodingOldFileWithoutNewFieldsYieldsNil() throws {
+        let original = Fixtures.metadata(webcamOffsetMs: 456.7)
+        var json = try XCTUnwrap(
+            JSONSerialization.jsonObject(with: original.encode()) as? [String: Any]
+        )
+        json.removeValue(forKey: "webcamOffsetMs")
+        json.removeValue(forKey: "webcam")
+        json.removeValue(forKey: "canvas")
+        json.removeValue(forKey: "trim")
+        let data = try JSONSerialization.data(withJSONObject: json)
+        let decoded = try RecordingMetadata.decode(from: data)
+        XCTAssertNil(decoded.webcamOffsetMs)
+        XCTAssertNil(decoded.webcam)
+        XCTAssertNil(decoded.canvas)
+        XCTAssertNil(decoded.trim)
+    }
+}
diff --git a/Tests/CineScreenTests/ProjectsLibraryTests.swift b/Tests/CineScreenTests/ProjectsLibraryTests.swift
@@ -0,0 +1,52 @@
+import XCTest
+@testable import CineScreen
+
+final class ProjectsLibraryTests: XCTestCase {
+    private var root: URL!
+
+    override func setUpWithError() throws {
+        root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("CineScreenTests-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+    }
+
+    override func tearDownWithError() throws {
+        try? FileManager.default.removeItem(at: root)
+    }
+
+    @MainActor
+    func testCreateNewWritesDescriptorAndAvoidsCollisions() throws {
+        let a = try ProjectsLibrary.createNew(in: root, name: "Take")
+        let b = try ProjectsLibrary.createNew(in: root, name: "Take")
+        XCTAssertNotEqual(a.folderURL, b.folderURL)
+        XCTAssertTrue(FileManager.default.fileExists(
+            atPath: a.folderURL.appendingPathComponent(Project.projectFileName).path
+        ))
+    }
+
+    /// The library must never present arbitrary folders as projects —
+    /// Settings allows pointing it at any directory, and Delete moves listed
+    /// folders to the Trash.
+    @MainActor
+    func testListingIgnoresFoldersWithoutCineScreenArtifacts() throws {
+        _ = try ProjectsLibrary.createNew(in: root, name: "Real")
+        let foreign = root.appendingPathComponent("Vacation Photos", isDirectory: true)
+        try FileManager.default.createDirectory(at: foreign, withIntermediateDirectories: true)
+
+        let listed = ProjectsLibrary.projects(in: root)
+        XCTAssertEqual(listed.count, 1)
+        XCTAssertEqual(listed.first?.name, "Real")
+    }
+
+    /// Pre-descriptor recordings (video only, no project.json) stay visible.
+    @MainActor
+    func testListingKeepsFoldersWithVideoButNoDescriptor() throws {
+        let legacy = root.appendingPathComponent("Old Recording", isDirectory: true)
+        try FileManager.default.createDirectory(at: legacy, withIntermediateDirectories: true)
+        FileManager.default.createFile(
+            atPath: legacy.appendingPathComponent(Project.videoFileName).path,
+            contents: Data([0x00])
+        )
+        XCTAssertEqual(ProjectsLibrary.projects(in: root).count, 1)
+    }
+}
diff --git a/Tests/CineScreenTests/RenderSnapshotTests.swift b/Tests/CineScreenTests/RenderSnapshotTests.swift
@@ -0,0 +1,92 @@
+import XCTest
+@testable import CineScreen
+
+final class RenderSnapshotTests: XCTestCase {
+    func testProximityFactorBinarySearch() {
+        let times = [1000.0, 2000.0]
+        XCTAssertEqual(RenderSnapshot.proximityFactor(to: times, at: 1000, window: 140), 0)
+        XCTAssertEqual(RenderSnapshot.proximityFactor(to: times, at: 1070, window: 140), 0.5, accuracy: 1e-9)
+        XCTAssertEqual(RenderSnapshot.proximityFactor(to: times, at: 1500, window: 140), 1)
+        XCTAssertEqual(RenderSnapshot.proximityFactor(to: times, at: 500, window: 140), 1)
+        XCTAssertEqual(RenderSnapshot.proximityFactor(to: times, at: 2010, window: 140), 10.0 / 140.0, accuracy: 1e-9)
+        XCTAssertEqual(RenderSnapshot.proximityFactor(to: [], at: 0, window: 140), 1)
+    }
+
+    /// The smoothing collapse keys off mouse-DOWNs only — an up (e.g. a drag
+    /// release, often far from any ring) must not snap the sprite.
+    func testMouseUpsDoNotCollapseSmoothing() {
+        let metadata = Fixtures.metadata(
+            keyframes: [Fixtures.keyframe(0, 100, 100), Fixtures.keyframe(5000, 100, 100)],
+            clicks: [Fixtures.click(1000, action: .down), Fixtures.click(1600, action: .up)]
+        )
+        let snapshot = RenderSnapshot(metadata: metadata, zoomSections: [])
+        XCTAssertEqual(snapshot.adaptiveCursorSmoothTime(atMilliseconds: 1000), 0, accuracy: 1e-9)
+        XCTAssertEqual(
+            snapshot.adaptiveCursorSmoothTime(atMilliseconds: 1600),
+            CursorAnimationStyle.mellow.smoothTime,
+            accuracy: 1e-9
+        )
+    }
+
+    /// A sprite trailing far behind a stationary pointer must tighten —
+    /// the move-then-hover case, where speed alone reads as calm.
+    func testLagUrgencyTightensSmoothTime() {
+        let metadata = Fixtures.metadata(
+            keyframes: [Fixtures.keyframe(0, 0, 0), Fixtures.keyframe(5000, 0, 0)]
+        )
+        let snapshot = RenderSnapshot(metadata: metadata, zoomSections: [])
+        let calm = snapshot.adaptiveCursorSmoothTime(atMilliseconds: 2500, spriteAt: SIMD2(0, 0))
+        let lagging = snapshot.adaptiveCursorSmoothTime(atMilliseconds: 2500, spriteAt: SIMD2(500, 0))
+        XCTAssertLessThan(lagging, calm)
+        XCTAssertEqual(lagging, CursorAnimationStyle.mellow.minSmoothTime, accuracy: 1e-9)
+    }
+
+    func testZoomStateRampAndIdentity() {
+        let metadata = Fixtures.metadata(
+            keyframes: [Fixtures.keyframe(0, 1000, 500), Fixtures.keyframe(10_000, 1000, 500)],
+            sections: [Fixtures.section(1000, 5000)]
+        )
+        let snapshot = RenderSnapshot(metadata: metadata, zoomSections: metadata.zoom.sections)
+        XCTAssertEqual(snapshot.zoomState(atMilliseconds: 500).scale, 1.0)
+        XCTAssertEqual(snapshot.zoomState(atMilliseconds: 1000).scale, 1.0, accuracy: 1e-4)
+        XCTAssertEqual(snapshot.zoomState(atMilliseconds: 3000).scale, 2.0, accuracy: 1e-4)
+        XCTAssertEqual(snapshot.zoomState(atMilliseconds: 6000).scale, 1.0)
+    }
+
+    /// The pan lookup table is binary-searched by time — it must be
+    /// monotonic no matter how many sections feed it.
+    func testPanSamplesAreMonotonic() {
+        let metadata = Fixtures.metadata(
+            keyframes: stride(from: 0.0, through: 10_000, by: 50).map {
+                Fixtures.keyframe($0, 500 + $0 / 10, 400)
+            },
+            sections: [Fixtures.section(1000, 4000), Fixtures.section(6000, 9000)]
+        )
+        let snapshot = RenderSnapshot(metadata: metadata, zoomSections: metadata.zoom.sections)
+        XCTAssertFalse(snapshot.panSamples.isEmpty)
+        for pair in zip(snapshot.panSamples, snapshot.panSamples.dropFirst()) {
+            XCTAssertLessThanOrEqual(pair.0.t, pair.1.t)
+        }
+    }
+
+    /// Defensive sort: old metadata files may carry sections in drag order.
+    func testInitSortsSections() {
+        let metadata = Fixtures.metadata(
+            sections: [Fixtures.section(6000, 9000), Fixtures.section(1000, 4000)]
+        )
+        let snapshot = RenderSnapshot(metadata: metadata, zoomSections: metadata.zoom.sections)
+        XCTAssertEqual(snapshot.zoomSections.map(\.startTime), [1000, 6000])
+    }
+
+    func testRawCursorPositionInterpolatesAndClamps() {
+        let metadata = Fixtures.metadata(
+            keyframes: [Fixtures.keyframe(0, 0, 0), Fixtures.keyframe(1000, 100, 200)]
+        )
+        let mid = RenderSnapshot.rawCursorPosition(atMilliseconds: 500, metadata: metadata)
+        XCTAssertEqual(Double(mid?.x ?? -1), 50, accuracy: 0.001)
+        XCTAssertEqual(Double(mid?.y ?? -1), 100, accuracy: 0.001)
+        let past = RenderSnapshot.rawCursorPosition(atMilliseconds: 5000, metadata: metadata)
+        XCTAssertEqual(Double(past?.x ?? -1), 100, accuracy: 0.001)
+        XCTAssertNil(RenderSnapshot.rawCursorPosition(atMilliseconds: 0, metadata: Fixtures.metadata()))
+    }
+}
diff --git a/Tests/CineScreenTests/SpringTests.swift b/Tests/CineScreenTests/SpringTests.swift
@@ -0,0 +1,47 @@
+import XCTest
+@testable import CineScreen
+
+final class SpringTests: XCTestCase {
+    func testSmoothDampConvergesToTarget() {
+        var spring = SmoothPosition2D(x: 0, y: 0, smoothTime: 0.2)
+        var pos = SIMD2<Double>(0, 0)
+        for _ in 0..<300 {
+            pos = spring.update(targetX: 100, targetY: 50, deltaTime: 1.0 / 60.0)
+        }
+        XCTAssertEqual(pos.x, 100, accuracy: 0.5)
+        XCTAssertEqual(pos.y, 50, accuracy: 0.5)
+    }
+
+    /// The click window collapses smoothTime to exactly 0 at a mouse-down —
+    /// the update must stay finite (omega is clamped) and effectively snap.
+    func testZeroSmoothTimeIsFiniteAndSnaps() {
+        var spring = SmoothPosition2D(x: 0, y: 0, smoothTime: 0)
+        let pos = spring.update(targetX: 500, targetY: 500, deltaTime: 1.0 / 60.0)
+        XCTAssertTrue(pos.x.isFinite && pos.y.isFinite)
+        XCTAssertEqual(pos.x, 500, accuracy: 1.0)
+        XCTAssertEqual(pos.y, 500, accuracy: 1.0)
+    }
+
+    func testAdaptiveBlendEndpointsAndMonotonicity() {
+        let style = CursorAnimationStyle.mellow
+        let w = 2000.0
+
+        // At rest: full cinematic glide. Flat out (speed or lag): fully tight.
+        XCTAssertEqual(style.smoothTime(forSpeedPxPerSec: 0, videoWidth: w), style.smoothTime)
+        XCTAssertEqual(style.smoothTime(forSpeedPxPerSec: 10 * w, videoWidth: w),
+                       style.minSmoothTime, accuracy: 1e-9)
+        XCTAssertEqual(style.smoothTime(forSpeedPxPerSec: 0, lagPx: w, videoWidth: w),
+                       style.minSmoothTime, accuracy: 1e-9)
+
+        // Monotonically non-increasing in speed.
+        var last = style.smoothTime(forSpeedPxPerSec: 0, videoWidth: w)
+        for speed in stride(from: 0.0, through: 2.0 * w, by: w / 10) {
+            let t = style.smoothTime(forSpeedPxPerSec: speed, videoWidth: w)
+            XCTAssertLessThanOrEqual(t, last + 1e-12)
+            last = t
+        }
+
+        // Degenerate width falls back to the base time rather than dividing by 0.
+        XCTAssertEqual(style.smoothTime(forSpeedPxPerSec: 1e9, videoWidth: 0), style.smoothTime)
+    }
+}
diff --git a/Tests/CineScreenTests/ZoomGenerationTests.swift b/Tests/CineScreenTests/ZoomGenerationTests.swift
@@ -0,0 +1,39 @@
+import XCTest
+@testable import CineScreen
+
+final class ZoomGenerationTests: XCTestCase {
+    @MainActor
+    func testClicksClusterWithinGap() {
+        // 1000 and 2500 are within the 2s cluster gap; 8000 starts a new one.
+        let clicks = [Fixtures.click(1000), Fixtures.click(2500), Fixtures.click(8000)]
+        let sections = EditorViewModel.generateZoomSections(from: clicks, videoDuration: 20_000, scale: 2)
+        XCTAssertEqual(sections.count, 2)
+        XCTAssertEqual(sections[0].startTime, 700, accuracy: 1e-9)   // 300ms preroll
+        XCTAssertEqual(sections[0].endTime, 3700, accuracy: 1e-9)    // 1200ms postroll
+        XCTAssertEqual(sections[1].startTime, 7700, accuracy: 1e-9)
+    }
+
+    @MainActor
+    func testGeneratedSectionsAreSortedAndNonOverlapping() {
+        let clicks = stride(from: 500.0, through: 30_000, by: 2500).map { Fixtures.click($0) }
+        let sections = EditorViewModel.generateZoomSections(from: clicks, videoDuration: 32_000, scale: 2)
+        XCTAssertFalse(sections.isEmpty)
+        for pair in zip(sections, sections.dropFirst()) {
+            XCTAssertLessThanOrEqual(pair.0.endTime, pair.1.startTime)
+        }
+    }
+
+    @MainActor
+    func testMouseUpsAreIgnored() {
+        let clicks = [Fixtures.click(1000, action: .up)]
+        XCTAssertTrue(EditorViewModel.generateZoomSections(from: clicks, videoDuration: 10_000, scale: 2).isEmpty)
+    }
+
+    @MainActor
+    func testBoundsClampToVideo() {
+        let clicks = [Fixtures.click(100), Fixtures.click(9_900)]
+        let sections = EditorViewModel.generateZoomSections(from: clicks, videoDuration: 10_000, scale: 2)
+        XCTAssertGreaterThanOrEqual(sections.first?.startTime ?? -1, 0)
+        XCTAssertLessThanOrEqual(sections.last?.endTime ?? .infinity, 10_000)
+    }
+}
diff --git a/project.yml b/project.yml
