react-native-queue-player 1.0.0

package/ios/Tests/GaplessEngineLifecycleTests.swift

@@ -0,0 +1,160 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// Lifecycle smoke coverage for `GaplessEngine` — empty-queue
+/// sentinels + idempotent / delegate-clearing release contract.
+/// Behavioural coverage of transport + seek runs through the
+/// existing TrackPlayer integration suites + Maestro flows.
+final class GaplessEngineLifecycleTests: XCTestCase {
+
+  func testEmptyQueueReturnsDocumentedSentinelState() {
+    let engine = GaplessEngine()
+    XCTAssertEqual(engine.currentMediaItemIndex, -1)
+    XCTAssertFalse(engine.isPlaying)
+    XCTAssertNil(engine.currentMediaItem)
+    XCTAssertEqual(engine.allMediaItems.count, 0)
+    XCTAssertEqual(engine.currentPositionSeconds, 0)
+    XCTAssertEqual(engine.currentDurationSeconds, 0)
+    XCTAssertEqual(engine.bufferedPositionSeconds, 0)
+  }
+
+  func testReleaseIsIdempotentAndClearsDelegate() {
+    let engine = GaplessEngine()
+    let delegate = NoopDelegate()
+    engine.delegate = delegate
+    XCTAssertNotNil(engine.delegate)
+
+    engine.release()
+    XCTAssertNil(engine.delegate)
+
+    engine.release()
+    XCTAssertNil(engine.delegate)
+  }
+
+  // MARK: - Queue-mutation surface
+
+  /// `setItems` installs the slice from `startIndex` onward; items
+  /// before `startIndex` never enter the AVQueuePlayer (matches
+  /// `AVQueuePlayer`'s forward-only contract).
+  func testSetItemsInstallsSliceFromStartIndex() {
+    let engine = GaplessEngine()
+    let items = makeItems(count: 5)
+    engine.setItems(items, startIndex: 2, startPositionSeconds: 0)
+    XCTAssertEqual(engine.allMediaItems.count, 3)
+    XCTAssertEqual(engine.currentMediaItem, items[2])
+  }
+
+  /// Drain-on-bad-input: empty items, negative startIndex, and
+  /// startIndex >= items.count all leave the queue empty. Matches
+  /// the existing `TrackPlayer.fullRebuildPlayerQueue` shape
+  /// (removeAllItems unconditional, then guard).
+  func testSetItemsDrainsQueueOnEmptyOrOutOfRangeStartIndex() {
+    let engine = GaplessEngine()
+    // Seed the queue first so we can verify the drain.
+    engine.setItems(makeItems(count: 3), startIndex: 0, startPositionSeconds: 0)
+    XCTAssertEqual(engine.allMediaItems.count, 3)
+
+    // Empty items drains.
+    engine.setItems([], startIndex: 0, startPositionSeconds: 0)
+    XCTAssertEqual(engine.allMediaItems.count, 0)
+
+    // Negative startIndex drains.
+    engine.setItems(makeItems(count: 3), startIndex: -1, startPositionSeconds: 0)
+    XCTAssertEqual(engine.allMediaItems.count, 0)
+
+    // startIndex past end drains.
+    engine.setItems(makeItems(count: 3), startIndex: 3, startPositionSeconds: 0)
+    XCTAssertEqual(engine.allMediaItems.count, 0)
+  }
+
+  /// `insertItems` with `nil` after appends to the END of the queue
+  /// (matches `AVQueuePlayer.insert(_:after:)`'s contract). Returns
+  /// `true` when every item was accepted.
+  func testInsertItemsWithNilAfterAppendsToEnd() {
+    let engine = GaplessEngine()
+    let initial = makeItems(count: 2)
+    engine.setItems(initial, startIndex: 0, startPositionSeconds: 0)
+    let appended = makeItems(count: 2)
+    let ok = engine.insertItems(appended, after: nil)
+    XCTAssertTrue(ok)
+    XCTAssertEqual(engine.allMediaItems.count, 4)
+    XCTAssertEqual(engine.allMediaItems[2], appended[0])
+    XCTAssertEqual(engine.allMediaItems[3], appended[1])
+  }
+
+  /// `insertItems` with an explicit `after` cursor surgically slots
+  /// the new items behind it.
+  func testInsertItemsAfterExplicitCursorSlotsBehindIt() {
+    let engine = GaplessEngine()
+    let initial = makeItems(count: 3)
+    engine.setItems(initial, startIndex: 0, startPositionSeconds: 0)
+    let inserted = makeItems(count: 1)
+    let ok = engine.insertItems(inserted, after: initial[0])
+    XCTAssertTrue(ok)
+    XCTAssertEqual(engine.allMediaItems.count, 4)
+    XCTAssertEqual(engine.allMediaItems[1], inserted[0])
+  }
+
+  /// `remove(_:)` drops the named item; AVQueuePlayer auto-advances
+  /// when the current item is removed, but the removed item is no
+  /// longer in `allMediaItems`.
+  func testRemoveDropsTheNamedItem() {
+    let engine = GaplessEngine()
+    let items = makeItems(count: 4)
+    engine.setItems(items, startIndex: 0, startPositionSeconds: 0)
+    engine.remove(items[2])
+    XCTAssertEqual(engine.allMediaItems.count, 3)
+    XCTAssertFalse(engine.allMediaItems.contains(items[2]))
+  }
+
+  /// `removeAllItems()` drains the queue; subsequent state queries
+  /// return the empty-queue sentinels.
+  func testRemoveAllItemsDrainsTheQueue() {
+    let engine = GaplessEngine()
+    engine.setItems(makeItems(count: 3), startIndex: 0, startPositionSeconds: 0)
+    XCTAssertEqual(engine.allMediaItems.count, 3)
+    engine.removeAllItems()
+    XCTAssertEqual(engine.allMediaItems.count, 0)
+    XCTAssertEqual(engine.currentMediaItemIndex, -1)
+    XCTAssertNil(engine.currentMediaItem)
+  }
+
+  /// `canInsert(_:after:)` mirrors `AVQueuePlayer.canInsert`. Fresh
+  /// items are insertable; items already in the queue are not
+  /// (AVQueuePlayer rejects re-insert of an in-flight item).
+  func testCanInsertReportsAVQueuePlayerAcceptance() {
+    let engine = GaplessEngine()
+    let initial = makeItems(count: 2)
+    engine.setItems(initial, startIndex: 0, startPositionSeconds: 0)
+    let fresh = makeItem()
+    XCTAssertTrue(engine.canInsert(fresh, after: nil))
+    XCTAssertFalse(engine.canInsert(initial[0], after: nil))
+  }
+
+  // MARK: - Test helpers
+
+  private func makeItem() -> AVPlayerItem {
+    // file:// URL keeps the AVURLAsset cheap; we never actually
+    // play these — the queue-mutation surface only inspects the
+    // items() snapshot + canInsert/insert/remove primitives.
+    let url = URL(fileURLWithPath: "/dev/null/\(UUID().uuidString).mp3")
+    return AVPlayerItem(url: url)
+  }
+
+  private func makeItems(count: Int) -> [AVPlayerItem] {
+    (0 ..< count).map { _ in makeItem() }
+  }
+}
+
+private final class NoopDelegate: PlaybackEngineDelegate {
+  func engineStateMaybeChanged(_ engine: PlaybackEngine, reason: StateChangeReason?) {}
+  func engineIsPlayingChanged(_ engine: PlaybackEngine, isPlaying: Bool) {}
+  func engineDidTransitionTrack(_ engine: PlaybackEngine) {}
+  func engineActiveItemFormatChanged(_ engine: PlaybackEngine) {}
+  func engineDidFailWithError(_ engine: PlaybackEngine, error: Error) {}
+  func engineDidPlayItemToEnd(_ engine: PlaybackEngine) {}
+  func enginePlaybackEnded(_ engine: PlaybackEngine) {}
+  func engineCrossfadeDidBegin(_ engine: PlaybackEngine, incomingIndex: Int) {}
+  func engineCrossfadeDidCancel(_ engine: PlaybackEngine, revertedIndex: Int) {}
+}

package/ios/Tests/InputGuardsTests.swift

@@ -0,0 +1,75 @@
+import XCTest
+@testable import QueuePlayer
+@_spi(QueuePlayerTests) import QueuePlayer
+
+/// Pure-Swift validation helpers for the JS↔native boundary. Tests
+/// hit the helpers directly — they're SPI-exposed for exactly this
+/// reason — so the consumer-facing `skipToIndex` / `seekTo` paths
+/// are covered without a live AVPlayer or AudioSession.
+final class InputGuardsTests: XCTestCase {
+
+  // MARK: - validQueueIndex
+
+  func testValidQueueIndexReturnsIntForInRangeValue() {
+    XCTAssertEqual(InputGuards.validQueueIndex(0, count: 5), 0)
+    XCTAssertEqual(InputGuards.validQueueIndex(2, count: 5), 2)
+    XCTAssertEqual(InputGuards.validQueueIndex(4, count: 5), 4)
+  }
+
+  func testValidQueueIndexFloorsFractionalValues() {
+    XCTAssertEqual(
+      InputGuards.validQueueIndex(2.7, count: 5), 2,
+      "fractional indices floor — matches Android (value * 1.0).toLong() parity")
+  }
+
+  func testValidQueueIndexRejectsNegative() {
+    XCTAssertNil(InputGuards.validQueueIndex(-1, count: 5))
+    XCTAssertNil(InputGuards.validQueueIndex(-0.5, count: 5))
+  }
+
+  func testValidQueueIndexRejectsAtBoundary() {
+    XCTAssertNil(
+      InputGuards.validQueueIndex(5, count: 5),
+      "boundary is exclusive: value < count")
+  }
+
+  func testValidQueueIndexRejectsOversized() {
+    XCTAssertNil(InputGuards.validQueueIndex(100, count: 5))
+    XCTAssertNil(InputGuards.validQueueIndex(.greatestFiniteMagnitude, count: 5))
+  }
+
+  func testValidQueueIndexRejectsNaN() {
+    XCTAssertNil(InputGuards.validQueueIndex(.nan, count: 5))
+    XCTAssertNil(InputGuards.validQueueIndex(.signalingNaN, count: 5))
+  }
+
+  func testValidQueueIndexRejectsInfinity() {
+    XCTAssertNil(InputGuards.validQueueIndex(.infinity, count: 5))
+    XCTAssertNil(InputGuards.validQueueIndex(-.infinity, count: 5))
+  }
+
+  func testValidQueueIndexEmptyQueueRejectsEverything() {
+    XCTAssertNil(InputGuards.validQueueIndex(0, count: 0))
+    XCTAssertNil(InputGuards.validQueueIndex(-1, count: 0))
+    XCTAssertNil(InputGuards.validQueueIndex(.nan, count: 0))
+  }
+
+  // MARK: - sanitisedSeekPosition
+
+  func testSanitisedSeekPositionReturnsFiniteValueUnchanged() {
+    XCTAssertEqual(InputGuards.sanitisedSeekPosition(0), 0)
+    XCTAssertEqual(InputGuards.sanitisedSeekPosition(42.5), 42.5)
+    XCTAssertEqual(InputGuards.sanitisedSeekPosition(-3.7), -3.7,
+      "negative values pass through; clamping is the caller's job")
+  }
+
+  func testSanitisedSeekPositionRejectsNaN() {
+    XCTAssertNil(InputGuards.sanitisedSeekPosition(.nan))
+    XCTAssertNil(InputGuards.sanitisedSeekPosition(.signalingNaN))
+  }
+
+  func testSanitisedSeekPositionRejectsInfinity() {
+    XCTAssertNil(InputGuards.sanitisedSeekPosition(.infinity))
+    XCTAssertNil(InputGuards.sanitisedSeekPosition(-.infinity))
+  }
+}

package/ios/Tests/InterruptionEventMappingTests.swift

@@ -0,0 +1,91 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `InterruptionEventMapping` is a pure-function namespace mapping
+/// `AudioSession.InterruptionKind` to the lib-standardized
+/// `nativeDomain` string + a stable human-readable message + the
+/// non-fatal `PlaybackError` that `TrackPlayer.wireAudioSession()`
+/// fires through `errorListeners`.
+final class InterruptionEventMappingTests: XCTestCase {
+
+  // MARK: - nativeDomain
+
+  func testNativeDomainBeganIsBeganLiteral() {
+    XCTAssertEqual(
+      InterruptionEventMapping.nativeDomain(for: .began),
+      "AUDIO_SESSION_INTERRUPTION_BEGAN"
+    )
+  }
+
+  func testNativeDomainEndedShouldResumeIsResumeHintLiteral() {
+    XCTAssertEqual(
+      InterruptionEventMapping.nativeDomain(for: .endedShouldResume),
+      "AUDIO_SESSION_INTERRUPTION_ENDED_SHOULD_RESUME"
+    )
+  }
+
+  func testNativeDomainEndedShouldNotResumeIsBareEndedLiteral() {
+    XCTAssertEqual(
+      InterruptionEventMapping.nativeDomain(for: .endedShouldNotResume),
+      "AUDIO_SESSION_INTERRUPTION_ENDED"
+    )
+  }
+
+  func testAllInterruptionDomainsShareTheBranchablePrefix() {
+    let kinds: [AudioSession.InterruptionKind] = [
+      .began, .endedShouldResume, .endedShouldNotResume,
+    ]
+    for kind in kinds {
+      let domain = InterruptionEventMapping.nativeDomain(for: kind)
+      XCTAssertTrue(
+        domain.hasPrefix(InterruptionEventMapping.nativeDomainPrefix),
+        "domain for \(kind) must use the consumer-branchable prefix; got \(domain)"
+      )
+    }
+  }
+
+  func testTheThreeDomainsAreExactlyTheSetOfWireLiterals() {
+    let domains: Set<String> = [
+      InterruptionEventMapping.nativeDomain(for: .began),
+      InterruptionEventMapping.nativeDomain(for: .endedShouldResume),
+      InterruptionEventMapping.nativeDomain(for: .endedShouldNotResume),
+    ]
+    XCTAssertEqual(domains, [
+      "AUDIO_SESSION_INTERRUPTION_BEGAN",
+      "AUDIO_SESSION_INTERRUPTION_ENDED_SHOULD_RESUME",
+      "AUDIO_SESSION_INTERRUPTION_ENDED",
+    ], "wire-protocol literals must not drift; rename = breaking change for JS consumers")
+  }
+
+  // MARK: - message
+
+  func testMessagesAreNonEmpty() {
+    let kinds: [AudioSession.InterruptionKind] = [
+      .began, .endedShouldResume, .endedShouldNotResume,
+    ]
+    for kind in kinds {
+      XCTAssertFalse(
+        InterruptionEventMapping.message(for: kind).isEmpty,
+        "message for \(kind) must be non-empty"
+      )
+    }
+  }
+
+  func testMessagesAreDistinctPerKind() {
+    let began = InterruptionEventMapping.message(for: .began)
+    let resume = InterruptionEventMapping.message(for: .endedShouldResume)
+    let ended = InterruptionEventMapping.message(for: .endedShouldNotResume)
+    XCTAssertNotEqual(began, resume)
+    XCTAssertNotEqual(began, ended)
+    XCTAssertNotEqual(resume, ended)
+  }
+
+  // PlaybackError construction lives inline at the call site in
+  // `TrackPlayer.wireAudioSession()` — Swift cxx-interop excludes
+  // internal helpers that return C++-bridged types like
+  // `PlaybackError` from the `@testable import` swiftmodule export,
+  // so the construction can't be invoked from an XCTest target. The
+  // wire literals + messages are pinned by the tests above; full-
+  // path coverage lives in the Maestro `interruption-handling`
+  // suite.
+}

package/ios/Tests/LookaheadCacheEvictionTests.swift

@@ -0,0 +1,217 @@
+import XCTest
+@testable import QueuePlayer
+@_spi(QueuePlayerTests) import QueuePlayer
+
+/// `LookaheadCacheEviction.computeEvictions` unit tests.
+///
+/// Pure-logic LRU policy. Plain JUnit-equivalent — no FS access, no
+/// URLSession. File + index mutation is tested through the
+/// LookaheadCacheTests integration path that drives `download` past
+/// the budget.
+final class LookaheadCacheEvictionTests: XCTestCase {
+
+  func testNoEvictionWhenUnderBudget() {
+    let entries = [
+      entry("a", size: 100, tick: 1),
+      entry("b", size: 200, tick: 2),
+      entry("c", size: 300, tick: 3),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 1000
+    )
+    XCTAssertTrue(evicted.isEmpty)
+  }
+
+  func testNoEvictionAtExactlyBudget() {
+    let entries = [
+      entry("a", size: 100, tick: 1),
+      entry("b", size: 200, tick: 2),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 300
+    )
+    XCTAssertTrue(evicted.isEmpty, "exactly-at-budget must not evict")
+  }
+
+  func testEvictsOldestFirstUntilUnderBudget() {
+    let entries = [
+      entry("oldest", size: 100, tick: 1),
+      entry("middle", size: 100, tick: 2),
+      entry("newest", size: 100, tick: 3),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 150
+    )
+    XCTAssertEqual(evicted.map { $0.trackId }, ["oldest", "middle"],
+      "oldest two must evict to drop total bytes from 300 → 100 ≤ 150")
+  }
+
+  func testEvictsExactlyOneWhenOneSuffices() {
+    let entries = [
+      entry("oldest", size: 200, tick: 1),
+      entry("newer", size: 100, tick: 2),
+      entry("newest", size: 100, tick: 3),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 200
+    )
+    XCTAssertEqual(evicted.map { $0.trackId }, ["oldest"],
+      "evicting just the oldest brings total from 400 → 200 (at budget)")
+  }
+
+  func testEvictsByTickNotByOrderInArray() {
+    // Index entries are stored in insertion order, but eviction
+    // must sort by lastAccessTick — a recently-touched older
+    // insertion stays.
+    let entries = [
+      entry("inserted-first-touched-newest", size: 100, tick: 5),
+      entry("inserted-second-touched-oldest", size: 100, tick: 1),
+      entry("inserted-third-touched-middle", size: 100, tick: 3),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 150
+    )
+    XCTAssertEqual(
+      evicted.map { $0.trackId },
+      ["inserted-second-touched-oldest", "inserted-third-touched-middle"]
+    )
+  }
+
+  func testEvictsAllWhenBudgetIsZero() {
+    let entries = [
+      entry("a", size: 100, tick: 1),
+      entry("b", size: 200, tick: 2),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 0
+    )
+    XCTAssertEqual(evicted.count, 2,
+      "budget=0 must evict everything")
+  }
+
+  func testTickCollisionFallsBackToTrackIdOrder() {
+    // Two entries with the same tick — eviction order must be
+    // deterministic for test reproducibility. Falls back to
+    // ascending trackId comparison.
+    let entries = [
+      entry("zzz", size: 100, tick: 5),
+      entry("aaa", size: 100, tick: 5),
+      entry("mmm", size: 100, tick: 5),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 100
+    )
+    XCTAssertEqual(evicted.map { $0.trackId }, ["aaa", "mmm"],
+      "deterministic tiebreak: ascending trackId → aaa evicts first")
+  }
+
+  func testEmptyEntriesReturnsEmpty() {
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: [], maxBytes: 100
+    )
+    XCTAssertTrue(evicted.isEmpty)
+  }
+
+  // MARK: - protectedTrackIds
+
+  func testProtectedTrackIsNeverEvicted() {
+    // The just-appended track is the LRU-newest, but if its size
+    // alone exceeds budget, plain LRU would evict it (since it's
+    // also the only entry). protectedTrackIds skips it from
+    // candidacy entirely, so an oversized download stays cached
+    // (caller may overshoot the budget — better than discarding
+    // the just-paid-for download).
+    let entries = [
+      entry("oversized", size: 500, tick: 1),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 100,
+      protectedUrls: ["oversized"]
+    )
+    XCTAssertTrue(evicted.isEmpty,
+      "single entry larger than budget must stay when protected")
+  }
+
+  func testProtectedTrackProtectedEvenIfOldest() {
+    // Mixed: protected entry IS the LRU-oldest, but should still be
+    // skipped. Other (newer) entries get evicted instead.
+    let entries = [
+      entry("protected", size: 100, tick: 1),
+      entry("newer-1", size: 100, tick: 2),
+      entry("newer-2", size: 100, tick: 3),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 150,
+      protectedUrls: ["protected"]
+    )
+    XCTAssertEqual(
+      evicted.map { $0.trackId },
+      ["newer-1", "newer-2"],
+      "protected entry must stay even though it's the LRU-oldest"
+    )
+  }
+
+  // MARK: - FIFO policy
+
+  func testFifoEvictsByInsertionOrderNotAccess() {
+    // Access ticks (LRU) and insertion order disagree. Under `.fifo` the
+    // oldest-INSERTED evicts first, regardless of playback recency.
+    let entries = [
+      entry("inserted-first-touched-newest", size: 100, tick: 9, insertion: 1),
+      entry("inserted-second-touched-oldest", size: 100, tick: 1, insertion: 2),
+      entry("inserted-third", size: 100, tick: 5, insertion: 3),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 150, useFifoOrder: true
+    )
+    XCTAssertEqual(
+      evicted.map { $0.trackId },
+      ["inserted-first-touched-newest", "inserted-second-touched-oldest"],
+      "fifo evicts oldest-inserted first even though it was touched most recently"
+    )
+  }
+
+  func testTouchReordersLruButNotFifo() {
+    // The entry touched most recently but inserted first: LRU keeps it,
+    // FIFO drops it.
+    let entries = [
+      entry("first-in", size: 100, tick: 9, insertion: 1),
+      entry("second-in", size: 100, tick: 2, insertion: 2),
+    ]
+    let lru = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 100, useFifoOrder: false
+    )
+    XCTAssertEqual(lru.map { $0.trackId }, ["second-in"],
+      "lru evicts the least-recently-touched")
+    let fifo = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 100, useFifoOrder: true
+    )
+    XCTAssertEqual(fifo.map { $0.trackId }, ["first-in"],
+      "fifo evicts the oldest-inserted regardless of touch")
+  }
+
+  func testFifoProtectedTrackIsNeverEvicted() {
+    let entries = [
+      entry("protected-oldest-insertion", size: 100, tick: 3, insertion: 1),
+      entry("newer", size: 100, tick: 1, insertion: 2),
+    ]
+    let evicted = LookaheadCacheEviction.computeEvictions(
+      entries: entries, maxBytes: 100, useFifoOrder: true,
+      protectedUrls: ["protected-oldest-insertion"]
+    )
+    XCTAssertEqual(evicted.map { $0.trackId }, ["newer"],
+      "protected entry stays even as the fifo-oldest")
+  }
+
+  // MARK: - Helpers
+
+  private func entry(
+    _ id: String, size: UInt64, tick: UInt64, insertion: UInt64? = nil
+  ) -> LookaheadCache.Entry {
+    return LookaheadCache.Entry(
+      trackId: id, fileName: "\(id).bin",
+      sizeBytes: size, lastAccessTick: tick,
+      insertionOrderTick: insertion ?? tick
+    )
+  }
+}