react-native-queue-player 1.1.2 → 2.0.0

package/ios/Tests/TrackPlayerCastStateTests.swift

@@ -0,0 +1,78 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `getState()` reports the receiver while a cast session owns playback. The
+/// local engine is parked and paused for the session's duration, so reading it
+/// would describe nothing the user can hear.
+final class TrackPlayerCastStateTests: XCTestCase {
+
+  private let router = PlaybackStateRouter.shared
+
+  override func setUp() {
+    super.setUp()
+    router._resetForTesting()
+  }
+
+  override func tearDown() {
+    router._resetForTesting()
+    super.tearDown()
+  }
+
+  /// Register a session that has already reported `state` to the receiver.
+  private func activateReporting(_ state: RemotePlaybackStateKind) throws {
+    let session = ControllableRemoteSession()
+    session.fireState(state)
+    try router.setActive(session)
+  }
+
+  func testReportsReceiverPlayingDuringCastSession() throws {
+    try activateReporting(.playing)
+    XCTAssertEqual(try TrackPlayer().getState(), .playing)
+  }
+
+  func testReportsReceiverPausedDuringCastSession() throws {
+    try activateReporting(.paused)
+    XCTAssertEqual(try TrackPlayer().getState(), .paused)
+  }
+
+  func testMapsBufferingReceiverToBuffering() throws {
+    try activateReporting(.buffering)
+    XCTAssertEqual(try TrackPlayer().getState(), .buffering)
+  }
+
+  func testMapsEndedReceiverToEnded() throws {
+    try activateReporting(.ended)
+    XCTAssertEqual(try TrackPlayer().getState(), .ended)
+  }
+
+  func testReportsIdleReceiverOnceItHasReported() throws {
+    // A receiver that has spoken stays authoritative: a later idle means it
+    // genuinely has nothing loaded, not that it is still activating.
+    let session = ControllableRemoteSession()
+    session.fireState(.playing)
+    session.fireState(.idle)
+    try router.setActive(session)
+
+    XCTAssertEqual(try TrackPlayer().getState(), PlayerState.none)
+  }
+
+  func testReadsLocalEngineUntilReceiverReports() throws {
+    // Session activating: the receiver holds a state it has not reported, so
+    // the local engine answers. Distinguishable from the receiver's `.playing`
+    // precisely because no engine is configured here.
+    let session = ControllableRemoteSession()
+    session.lastState = .playing
+    try router.setActive(session)
+
+    XCTAssertFalse(session.hasReportedState)
+    XCTAssertEqual(try TrackPlayer().getState(), PlayerState.none)
+  }
+
+  func testReadsLocalEngineWithNoCastSession() throws {
+    // An unregistered session must not be consulted, however it reports.
+    let session = ControllableRemoteSession()
+    session.fireState(.playing)
+
+    XCTAssertEqual(try TrackPlayer().getState(), PlayerState.none)
+  }
+}

package/ios/Tests/TrackPlayerConfigureTeardownTests.swift

@@ -0,0 +1,86 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `configure()` is a clean-slate operation: it releases whichever engine is
+/// live and clears the queue model before building the fresh one. The
+/// "is anything configured?" gate keys on the engine, which both engines
+/// populate — `player` holds the gapless `AVQueuePlayer` and is nil for the
+/// whole time a `CrossfadeEngine` is active, so it cannot answer that
+/// question.
+final class TrackPlayerConfigureTeardownTests: XCTestCase {
+
+  private var player: TrackPlayer!
+
+  override func setUp() async throws {
+    try await super.setUp()
+    player = TrackPlayer()
+  }
+
+  override func tearDown() async throws {
+    if let player {
+      _ = try await player.destroy().await()
+    }
+    player = nil
+    try await super.tearDown()
+  }
+
+  func testReconfigureClearsQueueUnderGapless() async throws {
+    try await assertReconfigureIsCleanSlate(
+      mode: PlaybackMode(kind: .gapless, crossfadeDurationMs: nil),
+      label: "gapless"
+    )
+  }
+
+  func testReconfigureClearsQueueUnderCrossfade() async throws {
+    try await assertReconfigureIsCleanSlate(
+      mode: PlaybackMode(kind: .crossfade, crossfadeDurationMs: 3000),
+      label: "crossfade"
+    )
+  }
+
+  /// Configure, install [mode], load a queue, then configure again without an
+  /// intervening `destroy()`. The second configure must have torn the prior
+  /// engine down: queue empty, current index reset.
+  private func assertReconfigureIsCleanSlate(
+    mode: PlaybackMode, label: String
+  ) async throws {
+    _ = try await player.configure(config: PlayerFixtures.config()).await()
+    _ = try await player.setPlaybackMode(mode: mode).await()
+    let tracks = try PlayerFixtures.localTracks(count: 3, for: self)
+    _ = try await player.setQueue(tracks: tracks, startAtIndex: 0).await()
+
+    let seeded = try await player.getQueue().await()
+    XCTAssertEqual(
+      seeded.count, tracks.count,
+      "\(label): expected the seeded queue before the re-configure")
+
+    _ = try await player.configure(config: PlayerFixtures.config()).await()
+
+    let cleared = try await player.getQueue().await()
+    XCTAssertEqual(
+      cleared.count, 0,
+      "\(label): configure() must clear the queue, got \(cleared.count) entries")
+    XCTAssertEqual(
+      try player.getCurrentTrackIndex(), -1,
+      "\(label): configure() must reset the current index")
+  }
+
+  /// The re-configure clears the queue without an emit; the revision the next
+  /// emit carries skips one, which is the signal a delta mirror re-reads on.
+  func testReconfigureLeavesARevisionGapForTheNextEmit() async throws {
+    _ = try await player.configure(config: PlayerFixtures.config()).await()
+    var revisions: [Int] = []
+    let unsubscribe = try player.onQueueChange { delta, _, _ in
+      revisions.append(Int(delta.revision))
+    }
+    defer { unsubscribe() }
+    _ = try await player.setQueue(tracks: PlayerFixtures.localTracks(count: 2, for: self), startAtIndex: 0).await()
+    let before = try XCTUnwrap(revisions.last)
+
+    _ = try await player.configure(config: PlayerFixtures.config()).await()
+    _ = try await player.setQueue(tracks: PlayerFixtures.localTracks(count: 1, for: self), startAtIndex: 0).await()
+
+    XCTAssertEqual(revisions.last, before + 2)
+  }
+
+}

package/ios/Tests/TrackPlayerEndVerdictTests.swift

@@ -0,0 +1,165 @@
+import XCTest
+@testable import QueuePlayer
+
+/// A drained engine reaches the same end-of-queue verdict whichever engine is
+/// installed. The engines report that they drained; the queue above them
+/// decides what that means.
+final class TrackPlayerEndVerdictTests: XCTestCase {
+
+  private var player: TrackPlayer!
+
+  override func setUp() async throws {
+    try await super.setUp()
+    player = TrackPlayer()
+    _ = try await player.configure(config: PlayerFixtures.config()).await()
+  }
+
+  override func tearDown() async throws {
+    if let player {
+      _ = try await player.destroy().await()
+    }
+    player = nil
+    try await super.tearDown()
+  }
+
+  // MARK: - The wrap case
+
+  func testRepeatQueueWrapsToTheHeadFromTheTail() async throws {
+    try await seedQueue(count: 3, at: 2, repeatMode: .queue)
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let state = try await read { (index: $0.currentTrackIndex, ended: $0.reachedQueueEnd) }
+    XCTAssertEqual(state.index, 0)
+    XCTAssertFalse(state.ended, "a wrap is not the end of the queue")
+  }
+
+  /// A single-track queue is already at position 0, so only the re-seat marks
+  /// the wrap: the dedup key is cleared so the repeated track still emits.
+  func testRepeatQueueReSeatsASingleTrackQueue() async throws {
+    try await seedQueue(count: 1, at: 0, repeatMode: .queue)
+    await onQueue { $0.lastEmittedQueueItemId = "stale" }
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let state = try await read {
+      (ended: $0.reachedQueueEnd, emitted: $0.lastEmittedQueueItemId,
+       head: $0.queueItemIds.first)
+    }
+    XCTAssertFalse(state.ended)
+    XCTAssertEqual(
+      state.emitted, state.head,
+      "clearing the dedup key lets the repeated track emit again")
+  }
+
+  /// Under crossfade there is no `AVQueuePlayer`, and the verdict must not
+  /// depend on one being there.
+  func testRepeatQueueWrapsUnderCrossfadeToo() async throws {
+    try await installCrossfade()
+    try await seedQueue(count: 3, at: 2, repeatMode: .queue)
+    let queuePlayer = try await read { $0.player }
+    XCTAssertNil(queuePlayer, "precondition: no gapless queue player")
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let state = try await read { (index: $0.currentTrackIndex, ended: $0.reachedQueueEnd) }
+    XCTAssertEqual(state.index, 0)
+    XCTAssertFalse(state.ended, "a wrap is not the end of the queue on either engine")
+  }
+
+  func testRepeatOffEndsTheQueueAtTheTail() async throws {
+    try await seedQueue(count: 3, at: 2, repeatMode: .off)
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let ended = try await read { $0.reachedQueueEnd }
+    XCTAssertTrue(ended)
+  }
+
+  // MARK: - The engine's own signal reaches the verdict
+
+  /// The crossfade engine reports a drain through the delegate, which is the
+  /// route that has to reach the same decision.
+  func testTheEngineDelegateEndSignalWrapsTheQueue() async throws {
+    try await installCrossfade()
+    try await seedQueue(count: 3, at: 2, repeatMode: .queue)
+    let engine = try await read { $0.engine }
+    let reporting = try XCTUnwrap(engine)
+
+    await onQueue { $0.enginePlaybackEnded(reporting) }
+
+    let state = try await read { (index: $0.currentTrackIndex, ended: $0.reachedQueueEnd) }
+    XCTAssertEqual(state.index, 0)
+    XCTAssertFalse(state.ended)
+  }
+
+  // MARK: - A tail that cannot be built
+
+  /// A track whose URL cannot be built is dropped from the engine's items, so
+  /// the engine drains before the logical tail. Re-seating that position
+  /// installs nothing and fires no further engine signal, so the decision has
+  /// to be retaken rather than left parked mid-queue.
+  func testAnUnbuildableTailStillEndsTheQueue() async throws {
+    try await installCrossfade()
+    try await seedQueue(count: 3, at: 1, repeatMode: .off, lastTrackURL: "")
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let ended = try await read { $0.reachedQueueEnd }
+    XCTAssertTrue(ended, "an unplayable last track must still end the queue")
+  }
+
+  /// Repeat-track re-seats the same position, so when that position cannot
+  /// be built there is nothing to refill: the queue ends rather than being
+  /// re-decided on the same anchor again.
+  func testAnUnbuildableCurrentTrackUnderRepeatTrackEndsTheQueue() async throws {
+    try await installCrossfade()
+    try await seedQueue(count: 3, at: 2, repeatMode: .track, lastTrackURL: "")
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let state = try await read { (index: $0.currentTrackIndex, ended: $0.reachedQueueEnd) }
+    XCTAssertEqual(state.index, 2)
+    XCTAssertTrue(state.ended, "an unplayable repeated track has nothing to refill")
+  }
+
+  func testAnUnbuildableTailStillWrapsUnderRepeatQueue() async throws {
+    try await installCrossfade()
+    try await seedQueue(count: 3, at: 1, repeatMode: .queue, lastTrackURL: "")
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let state = try await read { (index: $0.currentTrackIndex, ended: $0.reachedQueueEnd) }
+    XCTAssertEqual(state.index, 0)
+    XCTAssertFalse(state.ended)
+  }
+
+  // MARK: - Helpers
+
+  private func installCrossfade() async throws {
+    _ = try await player.setPlaybackMode(
+      mode: PlaybackMode(kind: .crossfade, crossfadeDurationMs: 3000)).await()
+  }
+
+  private func seedQueue(
+    count: Int, at index: Int, repeatMode: RepeatMode, lastTrackURL: String? = nil
+  ) async throws {
+    var tracks = try PlayerFixtures.localTracks(count: count, for: self)
+    if let lastTrackURL {
+      tracks[count - 1] = PlayerFixtures.track(id: "unbuildable", url: lastTrackURL)
+    }
+    _ = try await player.setQueue(tracks: tracks, startAtIndex: 0).await()
+    _ = try await player.setRepeatMode(mode: repeatMode).await()
+    await onQueue { $0.currentTrackIndex = index }
+  }
+
+  private func onQueue(_ body: @escaping (TrackPlayer) -> Void) async {
+    guard let player else { return }
+    await player.onPlayerQueue { body(player) }
+  }
+
+  private func read<T>(_ body: @escaping (TrackPlayer) -> T) async throws -> T {
+    let player = try XCTUnwrap(self.player)
+    return await player.onPlayerQueueValue { body(player) }
+  }
+}

package/ios/Tests/TrackPlayerSeekTests.swift

@@ -0,0 +1,137 @@
+import MediaPlayer
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// `seekTo` resolves on every branch, including the ones that complete without
+/// issuing a seek — a branch that returned without resuming would strand the
+/// calling JS Promise for the life of the process.
+final class TrackPlayerSeekTests: XCTestCase {
+
+  /// A seek against a live engine writes the process-global
+  /// `MPNowPlayingInfoCenter` on main. Drain that write and clear the centre
+  /// so it does not reach the next test class.
+  override func tearDown() {
+    let drained = expectation(description: "pending main-queue now-playing writes complete")
+    DispatchQueue.main.async { drained.fulfill() }
+    wait(for: [drained], timeout: 5.0)
+    MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+    super.tearDown()
+  }
+
+  func testSeekResolvesWithNoEngineAttached() {
+    let player = TrackPlayer()
+    expectSeekToResolve(player, position: 10, "no engine and no queue player")
+  }
+
+  func testSeekResolvesOnADrainedQueuePlayer() {
+    let player = TrackPlayer()
+    player.player = AVQueuePlayer()
+    expectSeekToResolve(player, position: 10, "a queue player with no current item")
+  }
+
+  /// With no queue there is nothing to reinstall, so a seek on a drained
+  /// player resolves without changing the end-of-queue state.
+  func testSeekOnADrainedQueuePlayerWithNoQueueLeavesTheEndOfQueueStateSet() {
+    let player = TrackPlayer()
+    player.player = AVQueuePlayer()
+    player.reachedQueueEnd = true
+
+    expectSeekToResolve(player, position: 10, "a drained player at the end of the queue")
+
+    XCTAssertTrue(
+      player.reachedQueueEnd,
+      "a seek that never reached the player must not report the queue as replaying")
+  }
+
+  func testSeekResolvesForAPositionBelowZero() {
+    let player = TrackPlayer()
+    expectSeekToResolve(player, position: -5, "a negative position")
+  }
+
+  /// A crossfade engine that does not hold the current track has it
+  /// reinstalled, and the seek is then issued against the reinstalled run.
+  func testSeekReinstallsAnAbsentCurrentTrackAndThenSeeksIt() {
+    let player = TrackPlayer()
+    let engine = RecordingEngineStub()
+    _ = player.queueState.replaceAll((0 ..< 2).map {
+      PlayerFixtures.track(id: "t\($0)", url: "http://127.0.0.1:1/\($0).m4a")
+    })
+    player.currentTrackIndex = 1
+    player.engine = engine
+
+    expectSeekToResolve(player, position: 30, "a current track the engine does not hold")
+
+    XCTAssertTrue(
+      engine.installedIds.contains(player.queueItemIds[1]),
+      "the reinstalled run holds the current track")
+    let seek = try? XCTUnwrap(engine.seeks.first)
+    XCTAssertEqual(
+      engine.allMediaItems[safe: seek?.index ?? -1]?.queueItemId, player.queueItemIds[1],
+      "the seek targets the current track's position in the reinstalled run")
+    XCTAssertEqual(seek?.position, 30)
+  }
+
+  /// Drives `seekTo` to completion and fails if it has not resolved within the
+  /// timeout, rather than hanging the suite on a stranded continuation.
+  private func expectSeekToResolve(
+    _ player: TrackPlayer, position: Double, _ branch: String,
+    file: StaticString = #filePath, line: UInt = #line
+  ) {
+    let resolved = expectation(description: "seekTo resolves on \(branch)")
+    Task {
+      do {
+        _ = try await player.seekTo(position: position).await()
+        resolved.fulfill()
+      } catch {
+        XCTFail("seekTo rejected on \(branch): \(error)", file: file, line: line)
+      }
+    }
+    wait(for: [resolved], timeout: 5.0)
+  }
+}
+
+/// Holds what it is given and records the seeks it is asked for.
+private final class RecordingEngineStub: PlaybackEngine {
+  private(set) var seeks: [(index: Int, position: TimeInterval)] = []
+  private var installed: [AVPlayerItem] = []
+  var installedIds: [String] { installed.compactMap { $0.queueItemId } }
+
+  var currentMediaItem: AVPlayerItem? { nil }
+  var allMediaItems: [AVPlayerItem] { installed }
+  var attachedQueueItemIds: [String] { [] }
+  var isFadePendingOrActive: Bool { false }
+  var currentMediaItemIndex: Int { -1 }
+  var currentPositionSeconds: TimeInterval { 0 }
+  var currentDurationSeconds: TimeInterval { 0 }
+  var bufferedPositionSeconds: TimeInterval { 0 }
+  var isPlaying: Bool { false }
+  var timeControlStatus: AVPlayer.TimeControlStatus { .paused }
+  var delegate: PlaybackEngineDelegate?
+
+  func release() {}
+  func setItems(_ items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) {
+    installed = items
+  }
+  @discardableResult
+  func insertItems(_ items: [AVPlayerItem], after: AVPlayerItem?) -> Bool {
+    installed.append(contentsOf: items)
+    return true
+  }
+  func remove(_ item: AVPlayerItem) { installed.removeAll { $0 === item } }
+  func removeAllItems() { installed.removeAll() }
+  func canInsert(_ item: AVPlayerItem, after: AVPlayerItem?) -> Bool { true }
+  func play() {}
+  func pause() {}
+  func stop() {}
+  func seek(toIndex index: Int, position: TimeInterval) { seeks.append((index, position)) }
+  func skipToNext() {}
+  func skipToPrevious() {}
+  func setVolume(_ volume: Float) {}
+  func setPlaybackSpeed(_ speed: Float) {}
+  func seedPlaybackSpeed(_ speed: Float) {}
+  func setRepeatMode(_ mode: RepeatMode) {}
+  func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {}
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {}
+  func refreshAllItemMixes() {}
+}

package/ios/Tests/TrackPlayerThreadingTests.swift

@@ -0,0 +1,127 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `onPlayerQueueSync` serialises on `playerQueue`, and recognises when it is already
+/// there. The recognition is what makes re-entrancy safe: a `sync` onto the
+/// queue from a block already running on it deadlocks immediately.
+final class TrackPlayerThreadingTests: XCTestCase {
+
+  func testSyncAccessorRunsInlineWhenAlreadyOnThePlayerQueue() {
+    let player = TrackPlayer()
+    let returned = expectation(description: "onPlayerQueueSync returns from the player queue")
+    var value = 0
+
+    player.playerQueue.async {
+      value = player.onPlayerQueueSync { 42 }
+      returned.fulfill()
+    }
+
+    wait(for: [returned], timeout: 2.0)
+    XCTAssertEqual(value, 42)
+  }
+
+  func testSyncAccessorReturnsFromOffTheQueue() {
+    let player = TrackPlayer()
+    let returned = expectation(description: "onPlayerQueueSync returns from an off-queue caller")
+    var value = 0
+
+    DispatchQueue.global().async {
+      value = player.onPlayerQueueSync { 7 }
+      returned.fulfill()
+    }
+
+    wait(for: [returned], timeout: 2.0)
+    XCTAssertEqual(value, 7)
+  }
+
+  func testNestedSyncAccessorsDoNotDeadlock() {
+    let player = TrackPlayer()
+    let returned = expectation(description: "a nested onPlayerQueueSync returns")
+    var value = 0
+
+    DispatchQueue.global().async {
+      value = player.onPlayerQueueSync { player.onPlayerQueueSync { 9 } }
+      returned.fulfill()
+    }
+
+    wait(for: [returned], timeout: 2.0)
+    XCTAssertEqual(value, 9)
+  }
+
+  func testOnQueueRecognitionIsPerInstance() {
+    let first = TrackPlayer()
+    let second = TrackPlayer()
+    let checked = expectation(description: "recognition evaluated on first's queue")
+    var firstSeesItsOwnQueue = false
+    var secondSeesAnotherPlayersQueue = true
+
+    first.playerQueue.async {
+      firstSeesItsOwnQueue = first.isOnPlayerQueue
+      secondSeesAnotherPlayersQueue = second.isOnPlayerQueue
+      checked.fulfill()
+    }
+
+    wait(for: [checked], timeout: 2.0)
+    XCTAssertTrue(firstSeesItsOwnQueue)
+    XCTAssertFalse(
+      secondSeesAnotherPlayersQueue,
+      "one player must not report being serialised by another player's queue")
+  }
+
+  // MARK: - Call-order preservation
+
+  /// Work enqueued from one thread runs in the order it was enqueued. This is
+  /// what makes a JS `play()` then `pause()` reach the player in that order:
+  /// a serial queue gives mutual exclusion, and enqueueing at call time is
+  /// what gives ordering on top of it.
+  func testEnqueuedWorkRunsInTheOrderItWasCalled() {
+    let player = TrackPlayer()
+    let lock = NSLock()
+    var order: [Int] = []
+    let ran = expectation(description: "every enqueued body ran")
+    ran.expectedFulfillmentCount = 50
+
+    for i in 0 ..< 50 {
+      _ = player.enqueue {
+        lock.lock()
+        order.append(i)
+        lock.unlock()
+        ran.fulfill()
+      }
+    }
+
+    wait(for: [ran], timeout: 5.0)
+    XCTAssertEqual(order, Array(0 ..< 50))
+  }
+
+  func testEnqueueResolvesItsPromiseAfterTheBodyRuns() async throws {
+    let player = TrackPlayer()
+    var didRun = false
+    let promise = player.enqueue { didRun = true }
+
+    _ = try await promise.await()
+
+    XCTAssertTrue(didRun, "the promise must not resolve before the body has run")
+  }
+
+  func testEnqueueThrowingRejectsWithTheThrownError() async {
+    let player = TrackPlayer()
+    struct Boom: Error {}
+    do {
+      _ = try await player.enqueueThrowing { throw Boom() }.await()
+      XCTFail("expected the promise to reject")
+    } catch {
+      // The bridge surfaces the message; reaching here is the contract.
+    }
+  }
+
+  func testEnqueueValueCarriesItsResultBack() async throws {
+    let player = TrackPlayer()
+    player.currentTrackIndex = 7
+
+    let value = try await player.enqueueValue { player.currentTrackIndex }.await()
+
+    XCTAssertEqual(value, 7)
+  }
+
+}

package/ios/Tests/TrackSourceClassifierTests.swift

@@ -1,14 +1,16 @@
 import XCTest
 @testable import QueuePlayer
 
-/// `TrackPlayer.classifyTrackSource(url:isUrlCached:)` decides how the active
-/// track is being played from lib-observable facts only: the URL scheme plus a
-/// cache-hit probe. Pure + static, so it's exercised directly without a live
-/// engine. Mirrors the Android source-classifier coverage.
+/// `TrackPlayer.classifyTrackSource` decides how the active track is being
+/// played from lib-observable facts only: the URL scheme, whether the item is
+/// routed through the read-through server, and a cache-hit probe. Pure +
+/// static, so it's exercised directly without a live engine.
 final class TrackSourceClassifierTests: XCTestCase {
 
-  private func classify(_ url: String?, cached: Bool = false) -> TrackSource? {
-    TrackPlayer.classifyTrackSource(url: url) { _ in cached }
+  private func classify(
+    _ url: String?, routed: Bool = true, cached: Bool = false
+  ) -> TrackSource? {
+    TrackPlayer.classifyTrackSource(url: url, isRouted: routed) { _ in cached }
   }
 
   func testNilUrlIsUnclassified() {
@@ -40,11 +42,35 @@ final class TrackSourceClassifierTests: XCTestCase {
 
   func testLocalFileNeverConsultsTheCacheProbe() {
     var probed = false
-    let source = TrackPlayer.classifyTrackSource(url: "file:///a.m4a") { _ in
+    let source = TrackPlayer.classifyTrackSource(url: "file:///a.m4a", isRouted: true) { _ in
       probed = true
       return true
     }
     XCTAssertEqual(source, .local)
     XCTAssertFalse(probed, "a file:// URL is local without a cache lookup")
   }
+
+  /// Cached on disk is not the same as played from disk. Only an item bound to
+  /// the read-through server reads the cache, so a complete file the player is
+  /// not routed through is still being streamed — reporting otherwise is what
+  /// made this field claim `cached` while every byte came from the origin.
+  func testACachedTrackThePlayerIsNotRoutedThroughIsStreaming() {
+    XCTAssertEqual(
+      classify("https://example.com/a.mp3", routed: false, cached: true), .streaming)
+  }
+
+  func testARoutedTrackTheCacheHoldsInFullIsCached() {
+    XCTAssertEqual(
+      classify("https://example.com/a.mp3", routed: true, cached: true), .cached)
+  }
+
+  func testARoutedTrackTheCacheDoesNotHoldIsStreaming() {
+    XCTAssertEqual(
+      classify("https://example.com/a.mp3", routed: true, cached: false), .streaming)
+  }
+
+  /// A local file is local whatever the server and cache report.
+  func testAFileTrackIsLocalRegardlessOfRouting() {
+    XCTAssertEqual(classify("file:///a.m4a", routed: false, cached: true), .local)
+  }
 }

package/ios/Tests/VoiceVocabularyOptInTests.swift

@@ -0,0 +1,38 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Siri vocabulary donation is off unless the consumer opts in, and the
+/// opt-in is fixed once taken.
+///
+/// The flag stands for the `com.apple.developer.siri` entitlement, which
+/// `INVocabulary` checks at runtime and which iOS gives a process no way to
+/// read. An entitlement is decided when the app is signed, so a value that
+/// changed later could not describe anything — and re-reading one would let a
+/// consumer re-arm a path that terminates a host without the capability.
+final class VoiceVocabularyOptInTests: XCTestCase {
+
+  func testDonationIsOffUntilTheConsumerOptsIn() {
+    let player = TrackPlayer()
+    XCTAssertFalse(
+      player.voiceVocabularyDonationEnabled,
+      "an untouched player has not been given the entitlement to assert")
+  }
+
+  func testTheFirstOptInIsTheOneThatCounts() {
+    let player = TrackPlayer()
+    player.pinVoiceVocabularyDonation(true)
+    player.pinVoiceVocabularyDonation(false)
+    XCTAssertTrue(
+      player.voiceVocabularyDonationEnabled,
+      "a later value does not unset an opt-in already taken")
+  }
+
+  func testDecliningIsAlsoFixed() {
+    let player = TrackPlayer()
+    player.pinVoiceVocabularyDonation(false)
+    player.pinVoiceVocabularyDonation(true)
+    XCTAssertFalse(
+      player.voiceVocabularyDonationEnabled,
+      "a later value does not turn donation on after it was declined")
+  }
+}