react-native-queue-player 1.2.0 → 2.0.1

package/ios/Tests/NowPlayingSnapshotTests.swift

@@ -0,0 +1,127 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// The lock-screen snapshot reports the engine's position, duration and
+/// effective rate — the configured speed while playing, zero otherwise — for
+/// whichever engine is active, including one with no gapless queue player.
+final class NowPlayingSnapshotTests: XCTestCase {
+
+  func testSnapshotReportsTheEnginesPositionAndDurationWithNoQueuePlayer() {
+    let player = TrackPlayer()
+    seedOneTrack(player)
+    let engine = SnapshotEngineStub()
+    engine.position = 42.5
+    engine.duration = 180
+    engine.playing = true
+    player.engine = engine
+    XCTAssertNil(player.player, "precondition: no gapless queue player to read")
+
+    let snapshot = player.nowPlayingSnapshot()
+
+    XCTAssertEqual(snapshot.elapsedSeconds, 42.5)
+    XCTAssertEqual(snapshot.durationSeconds, 180)
+    XCTAssertEqual(
+      snapshot.rate, 1.0,
+      "a playing engine must report a non-zero rate, or the lock screen renders paused")
+  }
+
+  func testRateIsZeroBecauseTheEngineIsNotPlayingRatherThanAlways() {
+    let player = TrackPlayer()
+    seedOneTrack(player)
+    let engine = SnapshotEngineStub()
+    engine.position = 10
+    engine.duration = 60
+    engine.playing = false
+    player.engine = engine
+    player.playbackSpeedState = 1.5
+
+    XCTAssertEqual(player.nowPlayingSnapshot().rate, 0)
+    XCTAssertEqual(
+      player.nowPlayingSnapshot().elapsedSeconds, 10,
+      "position still reports while paused")
+
+    // Same fixture, same configured speed — only the play state changes.
+    engine.playing = true
+    XCTAssertEqual(player.nowPlayingSnapshot().rate, 1.5)
+  }
+
+  func testSnapshotCarriesTheConfiguredSpeedAsTheRate() {
+    let player = TrackPlayer()
+    seedOneTrack(player)
+    let engine = SnapshotEngineStub()
+    engine.playing = true
+    player.engine = engine
+    player.playbackSpeedState = 1.5
+
+    XCTAssertEqual(player.nowPlayingSnapshot().rate, 1.5)
+  }
+
+  func testSnapshotHasNoTrackForAnEmptyQueue() {
+    let player = TrackPlayer()
+    player.engine = SnapshotEngineStub()
+
+    XCTAssertNil(player.nowPlayingSnapshot().track)
+  }
+
+  private func seedOneTrack(_ player: TrackPlayer) {
+    _ = player.queueState.replaceAll([
+      TrackItem(
+        id: "t0", url: "https://example.com/0.m4a", title: "Song", artist: nil,
+        album: nil, duration: nil, artworkUrl: nil, extras: nil,
+        replayGainTrackGain: nil, replayGainTrackPeak: nil,
+        replayGainAlbumGain: nil, replayGainAlbumPeak: nil)
+    ])
+    player.currentTrackIndex = 0
+  }
+}
+
+/// Reports whatever the test sets. Every other `PlaybackEngine` member is an
+/// inert stub — the snapshot only reads position, duration and
+/// `timeControlStatus`.
+private final class SnapshotEngineStub: PlaybackEngine {
+  var position: TimeInterval = 0
+  var duration: TimeInterval = 0
+  var playing = false
+
+  var currentPositionSeconds: TimeInterval { position }
+  var currentDurationSeconds: TimeInterval { duration }
+  /// The snapshot reads `timeControlStatus`; `isPlaying` is here only to
+  /// satisfy the protocol, and the two agree in this stub.
+  var isPlaying: Bool { playing }
+
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {}
+  func refreshAllItemMixes() {}
+  func release() {}
+  func setItems(_ items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) {}
+  @discardableResult
+  func insertItems(_ items: [AVPlayerItem], after: AVPlayerItem?) -> Bool { true }
+  func remove(_ item: AVPlayerItem) {}
+  func removeAllItems() {}
+  func canInsert(_ item: AVPlayerItem, after: AVPlayerItem?) -> Bool { true }
+  func play() {}
+  func pause() {}
+  func stop() {}
+  func seek(toIndex index: Int, position: TimeInterval) {}
+  func skipToNext() {}
+  func skipToPrevious() {}
+  func setVolume(_ volume: Float) {}
+  func setPlaybackSpeed(_ speed: Float) {}
+  func seedPlaybackSpeed(_ speed: Float) {}
+  func setRepeatMode(_ mode: RepeatMode) {}
+  func setPitchCorrectionMode(_ mode: PitchCorrectionMode) {}
+
+  var currentMediaItemIndex: Int { -1 }
+  var bufferedPositionSeconds: TimeInterval { 0 }
+  var timeControlStatus: AVPlayer.TimeControlStatus { playing ? .playing : .paused }
+  var currentMediaItem: AVPlayerItem? { nil }
+  var allMediaItems: [AVPlayerItem] { [] }
+
+  /// No fade to schedule — this stub exercises the rest of the surface.
+  var isFadePendingOrActive: Bool { false }
+
+  /// Nothing attached — this stub exercises the rest of the surface.
+  var attachedQueueItemIds: [String] { [] }
+
+  var delegate: PlaybackEngineDelegate?
+}

package/ios/Tests/OriginRestartStitcherTests.swift

@@ -0,0 +1,60 @@
+import XCTest
+@testable import QueuePlayer
+
+/// A re-issued origin transfer repeats bytes the client already has; the
+/// stitcher drops exactly those and refuses an answer that changed.
+final class OriginRestartStitcherTests: XCTestCase {
+
+  private func head(
+    status: Int = 200, length: String? = "1500", etag: String? = nil
+  ) -> HTTPURLResponse {
+    var headers: [String: String] = [:]
+    if let length { headers["Content-Length"] = length }
+    if let etag { headers["ETag"] = etag }
+    return HTTPURLResponse(
+      url: URL(string: "http://127.0.0.1:1/a.mp3")!, statusCode: status,
+      httpVersion: "HTTP/1.1", headerFields: headers)!
+  }
+
+  func testAFirstTransferPassesThrough() {
+    var stitcher = OriginRestartStitcher()
+    XCTAssertEqual(stitcher.head(head()), .accept)
+    XCTAssertEqual(stitcher.body(Data(repeating: 1, count: 1000)).count, 1000)
+    XCTAssertEqual(stitcher.deliveredBytes, 1000)
+  }
+
+  func testARestartRepeatsOnlyWhatWasNotDelivered() {
+    var stitcher = OriginRestartStitcher()
+    _ = stitcher.head(head())
+    _ = stitcher.body(Data(repeating: 1, count: 1000))
+
+    XCTAssertEqual(stitcher.head(head()), .accept, "the same answer is stitched")
+    let restarted = Data((0 ..< 1500).map { UInt8($0 % 251) })
+    let passed = stitcher.body(restarted)
+
+    XCTAssertEqual(passed.count, 500)
+    XCTAssertTrue(passed.elementsEqual(restarted[1000...]), "the tail past the delivered bytes")
+    XCTAssertEqual(stitcher.deliveredBytes, 1500)
+  }
+
+  /// The repeated bytes can arrive across several chunks.
+  func testTheSkipSpansChunks() {
+    var stitcher = OriginRestartStitcher()
+    _ = stitcher.head(head())
+    _ = stitcher.body(Data(repeating: 1, count: 1000))
+    _ = stitcher.head(head())
+
+    XCTAssertTrue(stitcher.body(Data(repeating: 2, count: 400)).isEmpty)
+    XCTAssertTrue(stitcher.body(Data(repeating: 2, count: 600)).isEmpty)
+    XCTAssertEqual(stitcher.body(Data(repeating: 3, count: 100)).count, 100)
+    XCTAssertEqual(stitcher.deliveredBytes, 1100)
+  }
+
+  func testADifferentAnswerIsRefused() {
+    var stitcher = OriginRestartStitcher()
+    _ = stitcher.head(head(etag: "\"v1\""))
+    XCTAssertEqual(stitcher.head(head(etag: "\"v2\"")), .reject, "a changed ETag is a different resource")
+    XCTAssertEqual(stitcher.head(head(length: "2000")), .reject, "a changed length too")
+    XCTAssertEqual(stitcher.head(head(status: 206)), .reject, "and a changed status")
+  }
+}

package/ios/Tests/PlaybackNetworkMonitorTests.swift

@@ -0,0 +1,95 @@
+import Network
+import XCTest
+@testable import QueuePlayer
+@_spi(QueuePlayerTests) import QueuePlayer
+
+/// The monitor reports the network coming back after an outage, and only that.
+/// A handoff between interfaces is not a recovery, and treating it as one would
+/// retry against a connection that never dropped.
+///
+/// `NWPathMonitor` delivers the current path once on `start`, and the monitor
+/// seeds its last status as unsatisfied, so on a device with a satisfied path
+/// every armed `start()` reports exactly one restore. That first delivery is
+/// what makes the arming observable. A device with no satisfied path fails
+/// these tests at the precondition rather than passing them empty.
+final class PlaybackNetworkMonitorTests: XCTestCase {
+
+  private let firstDeliveryTimeout: TimeInterval = 5
+
+  /// Arms `monitor` and waits for the one restore its first path delivery reports.
+  private func armAndAwaitRestore(_ monitor: PlaybackNetworkMonitor, restores: Counter) {
+    let first = expectation(description: "the current path is delivered on start")
+    // The callback stays installed for the monitor's life, so a genuine
+    // down → up during a later window reaches the counter assertions rather
+    // than tripping this expectation's over-fulfil check.
+    first.assertForOverFulfill = false
+    monitor.onNetworkRestored = {
+      restores.bump()
+      first.fulfill()
+    }
+    monitor.start()
+    let outcome = XCTWaiter.wait(for: [first], timeout: firstDeliveryTimeout)
+    guard outcome == .completed else {
+      XCTFail(
+        "no restore within \(Int(firstDeliveryTimeout))s of start — this device has no satisfied "
+          + "network path, so the monitor cannot be observed here")
+      return
+    }
+    XCTAssertEqual(restores.value, 1, "exactly one restore per armed start")
+  }
+
+  /// A `stop()` before any `start()` is not terminal: the arming that follows
+  /// still delivers the current path.
+  func testStopBeforeStartChangesNothing() {
+    let monitor = PlaybackNetworkMonitor(queue: .main)
+    let restores = Counter()
+    monitor.stop()
+    armAndAwaitRestore(monitor, restores: restores)
+    monitor.stop()
+  }
+
+}
+
+/// Main-queue counter the monitor's `queue: .main` callbacks bump.
+private final class Counter {
+  private(set) var value = 0
+  func bump() { value += 1 }
+}
+
+/// Recovery runs only when all four conditions hold together.
+final class NetworkRecoveryPolicyTests: XCTestCase {
+
+  func testRetriesWhenPlaybackIsIntendedAndTheItemFailedTransiently() {
+    XCTAssertTrue(
+      NetworkRecoveryPolicy.shouldRetry(
+        wantsToPlay: true, isInterrupted: false, isInError: true, isTransient: true))
+  }
+
+  func testDoesNotRetryWhenPlaybackWasNeverIntended() {
+    XCTAssertFalse(
+      NetworkRecoveryPolicy.shouldRetry(
+        wantsToPlay: false, isInterrupted: false, isInError: true, isTransient: true),
+      "a network change must not start audio nobody asked for")
+  }
+
+  func testDoesNotRetryDuringAnInterruption() {
+    XCTAssertFalse(
+      NetworkRecoveryPolicy.shouldRetry(
+        wantsToPlay: true, isInterrupted: true, isInError: true, isTransient: true),
+      "the network returning mid-call must not start audio")
+  }
+
+  func testDoesNotRetryWhenNothingHasFailed() {
+    XCTAssertFalse(
+      NetworkRecoveryPolicy.shouldRetry(
+        wantsToPlay: true, isInterrupted: false, isInError: false, isTransient: true),
+      "an interface handoff must not rebuild a healthy item")
+  }
+
+  func testDoesNotRetryAFailureANetworkCannotCure() {
+    XCTAssertFalse(
+      NetworkRecoveryPolicy.shouldRetry(
+        wantsToPlay: true, isInterrupted: false, isInError: true, isTransient: false),
+      "a codec, format or auth failure re-surfaces on every rebuild")
+  }
+}

package/ios/Tests/PlayerFixtures.swift

@@ -0,0 +1,48 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Shared fixtures for tests that need a configured `TrackPlayer` with a real
+/// playable queue.
+enum PlayerFixtures {
+
+  static func config(autoRetries: Double? = nil) -> PlayerConfig {
+    return PlayerConfig(
+      httpHeaders: nil, userAgent: nil, placeholderArtworkUri: nil,
+      autoRetries: autoRetries, retryBackoffMs: nil, networkTimeoutMs: nil,
+      audioContentType: nil, audioCategoryOptions: nil,
+      voiceVocabularyDonationEnabled: nil,
+      visualizationEnabled: nil, clampSeekToBuffered: nil,
+      skipToPreviousBehavior: nil, lookaheadCacheMaxSizeMb: nil,
+      lookaheadCacheEvictionPolicy: nil, progressUpdateIntervalMs: nil,
+      backgroundProgressUpdateIntervalMs: nil
+    )
+  }
+
+  static func track(id: String, url: String) -> TrackItem {
+    return TrackItem(
+      id: id, url: url, title: nil, artist: nil, album: nil,
+      duration: nil, artworkUrl: nil, extras: nil,
+      replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil
+    )
+  }
+
+  /// Queue entries backed by a bundled local asset, so the queue seats real
+  /// playable items without any network fetch or prefetch scheduling.
+  static func localTracks(count: Int, for testCase: XCTestCase) throws -> [TrackItem] {
+    let url = try fixtureURL(name: "silence-aac-128", ext: "m4a", for: testCase)
+    return (0 ..< count).map { track(id: "t\($0)", url: url.absoluteString) }
+  }
+
+  /// A file under `Tests/Fixtures`, bundled through `test_spec.resources`.
+  /// A miss is a tests-harness `pod install` regression.
+  static func fixtureURL(name: String, ext: String, for testCase: XCTestCase) throws -> URL {
+    let bundle = Bundle(for: type(of: testCase))
+    return try XCTUnwrap(
+      bundle.url(forResource: name, withExtension: ext)
+        ?? bundle.urls(forResourcesWithExtension: ext, subdirectory: nil)?
+          .first(where: { $0.deletingPathExtension().lastPathComponent == name }),
+      "fixture \(name).\(ext) not bundled — pod install regression in tests-harness"
+    )
+  }
+}

package/ios/Tests/PlayerStateDerivationTests.swift

@@ -16,7 +16,7 @@ final class PlayerStateDerivationTests: XCTestCase {
       status: status, currentIndex: index, hasCurrentItem: hasItem, reachedQueueEnd: ended)
   }
 
-  // MARK: baseline (no end-of-queue latch)
+  // MARK: baseline (queue has not drained)
 
   func testPlayingIsPlaying() {
     XCTAssertEqual(derive(.playing), .playing)
@@ -40,14 +40,14 @@ final class PlayerStateDerivationTests: XCTestCase {
   }
 
   func testWaitingWithoutItemNonEmptyQueueIsEndedFallback() {
-    // A drained AVQueuePlayer parks at .waitingToPlay with no item before the
-    // latch flips — the end-of-queue fallback covers the timing race.
+    // A drained AVQueuePlayer parks at .waitingToPlay with no item before
+    // `reachedQueueEnd` is set — the end-of-queue fallback covers the timing race.
     XCTAssertEqual(derive(.waitingToPlayAtSpecifiedRate, index: 5, hasItem: false), .ended)
   }
 
-  // MARK: reachedQueueEnd latch
+  // MARK: reachedQueueEnd
 
-  func testLatchWithTrackNotPlayingIsEnded() {
+  func testReachedQueueEndWithTrackNotPlayingIsEnded() {
     // Any non-playing status at end-of-queue is terminal — the same result for
     // both engines (crossfade keeps its finished item, so hasItem is true).
     XCTAssertEqual(derive(.paused, index: 5, ended: true), .ended)
@@ -55,14 +55,14 @@ final class PlayerStateDerivationTests: XCTestCase {
       derive(.waitingToPlayAtSpecifiedRate, index: 5, hasItem: true, ended: true), .ended)
   }
 
-  func testLatchYieldsToPlaying() {
-    // Playing takes precedence over the latch, so a resume reads correctly even
-    // before the latch clears.
+  func testReachedQueueEndYieldsToPlaying() {
+    // Playing takes precedence over `reachedQueueEnd`, so a resume reads
+    // correctly even before it is cleared.
     XCTAssertEqual(derive(.playing, index: 5, ended: true), .playing)
   }
 
-  func testLatchIgnoredWhenQueueEmpty() {
-    // A cleared queue (index < 0) skips the latch and derives normally.
+  func testReachedQueueEndIgnoredWhenQueueEmpty() {
+    // A cleared queue (index < 0) ignores `reachedQueueEnd` and derives normally.
     XCTAssertEqual(derive(.paused, index: -1, ended: true), .none)
   }
 }

package/ios/Tests/QueueMutationGenerationTests.swift

@@ -0,0 +1,141 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Receiver work runs in the order the mutations were made, and work that
+/// outlives its mutation does not act on a queue that has since been replaced.
+final class QueueMutationGenerationTests: 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: - Mirror ordering
+
+  /// `addToQueue`, `removeFromQueue` and `moveInQueue` send index deltas
+  /// resolved against the queue as it stood before their own mutation, so the
+  /// receiver has to see them in that order or it diverges.
+  func testMirrorsRunInTheOrderTheMutationsWereMade() async throws {
+    let recorded = Recorder()
+
+    for step in 0 ..< 5 {
+      _ = player.enqueueThenMirror({ step }, mirror: { value, _ in
+        await recorded.append(value)
+      })
+    }
+    let last = player.enqueueThenMirror({ 5 }, mirror: { value, _ in
+      await recorded.append(value)
+    })
+    _ = try await last.await()
+
+    let order = await recorded.values
+    XCTAssertEqual(order, [0, 1, 2, 3, 4, 5])
+  }
+
+  /// A slow round-trip holds the ones behind it rather than letting them
+  /// overtake — the whole reason the chain exists.
+  func testASlowMirrorDoesNotLetTheNextOneOvertakeIt() async throws {
+    let recorded = Recorder()
+
+    _ = player.enqueueThenMirror({ 0 }, mirror: { value, _ in
+      try? await Task.sleep(nanoseconds: 120_000_000)
+      await recorded.append(value)
+    })
+    let second = player.enqueueThenMirror({ 1 }, mirror: { value, _ in
+      await recorded.append(value)
+    })
+    _ = try await second.await()
+
+    let order = await recorded.values
+    XCTAssertEqual(order, [0, 1], "the slow mirror must still land first")
+  }
+
+  /// The promise resolves only once that call's own receiver work has run, so
+  /// awaiting a mutation means local and remote are both settled.
+  func testTheCallResolvesOnlyAfterItsOwnMirrorHasRun() async throws {
+    let recorded = Recorder()
+
+    _ = try await player.enqueueThenMirror({ 0 }, mirror: { value, _ in
+      await recorded.append(value)
+    }).await()
+
+    let order = await recorded.values
+    XCTAssertEqual(order, [0])
+  }
+
+  // MARK: - Generation
+
+  func testEachQueueMutationTakesTheNextGeneration() async throws {
+    let start = try await read { $0.queueMutationGeneration }
+
+    _ = try await player.setQueue(tracks: try tracks(3), startAtIndex: 0).await()
+    let afterSet = try await read { $0.queueMutationGeneration }
+    _ = try await player.addToQueue(tracks: try tracks(1), insertBefore: nil).await()
+    let afterAdd = try await read { $0.queueMutationGeneration }
+
+    XCTAssertEqual(afterSet, start &+ 1)
+    XCTAssertEqual(afterAdd, start &+ 2)
+  }
+
+  /// The generation a mirror captured is what tells it whether the queue it
+  /// was computed against is still the live one.
+  func testAMirrorSeesItsOwnGenerationSupersededByALaterMutation() async throws {
+    let captured = Recorder()
+    _ = player.enqueueThenMirror({ 0 }, mirror: { _, generation in
+      await captured.append(Int(generation))
+    })
+    _ = try await player.setQueue(tracks: try tracks(2), startAtIndex: 0).await()
+
+    let capturedValues = await captured.values
+    let mine = try XCTUnwrap(capturedValues.first)
+    let live = try await read { Int($0.queueMutationGeneration) }
+    XCTAssertGreaterThan(
+      live, mine, "a later mutation must leave the earlier generation behind")
+  }
+
+  /// A burst leaves the queue the last call asked for, and the ids stay
+  /// parallel to it.
+  func testABurstLeavesTheQueueTheLastCallAskedFor() async throws {
+    let start = try await read { $0.queueMutationGeneration }
+
+    _ = try player.setQueue(tracks: try tracks(3), startAtIndex: 0)
+    _ = try player.setQueue(tracks: try tracks(5), startAtIndex: 0)
+    let last = try player.setQueue(tracks: try tracks(2), startAtIndex: 0)
+    _ = try await last.await()
+
+    let state = try await read {
+      (count: $0.tracks.count, ids: $0.queueItemIds.count,
+       generation: $0.queueMutationGeneration)
+    }
+    XCTAssertEqual(state.count, 2, "the last call in the burst is the one that stands")
+    XCTAssertEqual(state.ids, state.count, "ids stay parallel to tracks through a burst")
+    XCTAssertEqual(state.generation, start &+ 3)
+  }
+
+  // MARK: - Helpers
+
+  private actor Recorder {
+    private(set) var values: [Int] = []
+    func append(_ value: Int) { values.append(value) }
+  }
+
+  private func tracks(_ count: Int) throws -> [TrackItem] {
+    try PlayerFixtures.localTracks(count: count, for: self)
+  }
+
+  private func read<T>(_ body: @escaping (TrackPlayer) -> T) async throws -> T {
+    let player = try XCTUnwrap(self.player)
+    return await player.onPlayerQueueValue { body(player) }
+  }
+}