react-native-queue-player 1.1.2 → 2.0.0

package/ios/Tests/MutationDeferralTests.swift

@@ -0,0 +1,220 @@
+import AVFoundation
+import XCTest
+@testable import QueuePlayer
+
+/// A queue mutation that touches neither leg waits for a crossfade to settle
+/// rather than cutting it short; one that touches a leg cannot wait.
+final class MutationDeferralTests: XCTestCase {
+
+  private var player: TrackPlayer!
+
+  override func setUp() async throws {
+    try await super.setUp()
+    player = TrackPlayer()
+  }
+
+  override func tearDown() async throws {
+    player = nil
+    try await super.tearDown()
+  }
+
+  func testAMutationClearOfBothLegsIsHeldBack() async throws {
+    try await seed(fading: true, attaching: [0, 1])
+
+    let deferred = try await onQueue { $0.deferEngineWork(touching: [7]) }
+
+    XCTAssertTrue(deferred)
+    let held = try await read { $0.engineReconcileDeferred }
+    XCTAssertTrue(held)
+  }
+
+  /// The prerolled standby leg counts: removing it out from under the arm
+  /// chain leaves the fade running into a track the queue no longer has.
+  func testAMutationTouchingTheStandbyLegIsNotHeldBack() async throws {
+    _ = try await seed(fading: true, attaching: [0, 1])
+
+    let deferred = try await onQueue { $0.deferEngineWork(touching: [1]) }
+
+    XCTAssertFalse(deferred)
+    let held = try await read { $0.engineReconcileDeferred }
+    XCTAssertFalse(held)
+  }
+
+  func testAMutationTouchingTheLeadingLegIsNotHeldBack() async throws {
+    _ = try await seed(fading: true, attaching: [0, 1])
+
+    let deferred = try await onQueue { $0.deferEngineWork(touching: [0]) }
+
+    XCTAssertFalse(deferred)
+  }
+
+  /// With no fade to protect there is nothing to wait for.
+  func testNothingIsHeldBackWhenNoFadeIsPending() async throws {
+    _ = try await seed(fading: false, attaching: [0])
+
+    let deferred = try await onQueue { $0.deferEngineWork(touching: [7]) }
+
+    XCTAssertFalse(deferred)
+  }
+
+  /// One flag, however many mutations: the reconcile re-derives what the
+  /// engine should hold from the model, so the order they arrived in and how
+  /// many there were do not matter.
+  func testSeveralHeldBackMutationsFlushAsOne() async throws {
+    let engine = try await seed(fading: true, attaching: [0, 1])
+    _ = try await onQueue { $0.deferEngineWork(touching: [6]) }
+    _ = try await onQueue { $0.deferEngineWork(touching: [7]) }
+    _ = try await onQueue { $0.deferEngineWork(touching: [8]) }
+
+    XCTAssertEqual(
+      engine.setItemsCount, 0, "nothing reaches the engine while the fade runs")
+
+    engine.fadePending = false
+    await onQueue { $0.flushDeferredEngineWork() }
+
+    let stillHeld = try await read { $0.engineReconcileDeferred }
+    XCTAssertFalse(stillHeld)
+    XCTAssertEqual(
+      engine.setItemsCount, 1, "the engine is reconciled once, not once per mutation")
+  }
+
+  func testFlushingWithNothingHeldBackLeavesTheEngineAlone() async throws {
+    let engine = try await seed(fading: false, attaching: [0])
+
+    await onQueue { $0.flushDeferredEngineWork() }
+
+    XCTAssertEqual(engine.setItemsCount, 0)
+  }
+
+  /// The new engine is installed from the queue model, which already carries
+  /// every mutation, so nothing is owed to it.
+  func testAnEngineSwapDropsWhatWasHeldBack() async throws {
+    _ = try await seed(fading: true, attaching: [0, 1])
+    _ = try await onQueue { $0.deferEngineWork(touching: [7]) }
+
+    await onQueue {
+      $0.applyEngineSwapForMode(PlaybackMode(kind: .gapless, crossfadeDurationMs: nil))
+    }
+
+    let held = try await read { $0.engineReconcileDeferred }
+    XCTAssertFalse(held)
+  }
+
+  // MARK: - The model stays authoritative
+
+  /// Holding the engine back does not hold the queue back: the model is
+  /// updated and the consumer is told at once either way.
+  func testADeferredRemoveStillChangesTheQueueAndReportsIt() async throws {
+    let engine = try await seed(fading: true, attaching: [0, 1])
+    var removeReports = 0
+    let unsubscribe = try player.onQueueChange { _, _, reason in
+      if reason == .remove { removeReports += 1 }
+    }
+    defer { unsubscribe() }
+
+    _ = try await player.removeFromQueue(indices: [7]).await()
+
+    let state = try await read { ($0.tracks.count, $0.queueItemIds.count) }
+    XCTAssertEqual(state.0, 11, "the queue model drops the track at once")
+    XCTAssertEqual(state.1, 11, "ids stay parallel to it")
+    XCTAssertEqual(removeReports, 1, "the consumer is told once")
+    XCTAssertTrue(engine.removed.isEmpty, "the engine is left alone until the fade settles")
+    let held = try await read { $0.engineReconcileDeferred }
+    XCTAssertTrue(held)
+  }
+
+  /// The same for a move, which reorders the model without touching a leg.
+  func testADeferredMoveStillReordersTheQueueAndReportsIt() async throws {
+    _ = try await seed(fading: true, attaching: [0, 1])
+    var moveReports = 0
+    let unsubscribe = try player.onQueueChange { _, _, reason in
+      if reason == .move { moveReports += 1 }
+    }
+    defer { unsubscribe() }
+    let idsBefore = try await read { $0.queueItemIds }
+
+    _ = try await player.moveInQueue(fromIndex: 8, toIndex: 6).await()
+
+    let idsAfter = try await read { $0.queueItemIds }
+    XCTAssertEqual(idsAfter[6], idsBefore[8], "the model is reordered at once")
+    XCTAssertEqual(moveReports, 1, "a deferred move is still reported")
+  }
+
+  // MARK: - Helpers
+
+  @discardableResult
+  private func seed(fading: Bool, attaching: [Int]) async throws -> DeferralEngineStub {
+    let player = try XCTUnwrap(self.player)
+    let engine = DeferralEngineStub()
+    await player.onPlayerQueue {
+      let ids = player.queueState.replaceAll(
+        (0 ..< 12).map {
+          PlayerFixtures.track(id: "t\($0)", url: "http://127.0.0.1:1/\($0).m4a")
+        })
+      engine.fadePending = fading
+      engine.attached = attaching.map { ids[$0] }
+      player.currentTrackIndex = 0
+      player.engine = engine
+    }
+    return engine
+  }
+
+  private func onQueue<T>(_ body: @escaping (TrackPlayer) -> T) async throws -> T {
+    let player = try XCTUnwrap(self.player)
+    return await player.onPlayerQueueValue { body(player) }
+  }
+
+  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 {
+    try await onQueue(body)
+  }
+}
+
+/// Reports a fade and a chosen set of attached identities, and records what
+/// the queue asks of it.
+private final class DeferralEngineStub: PlaybackEngine {
+  var fadePending = false
+  var attached: [String] = []
+  private(set) var removed: [AVPlayerItem] = []
+  private(set) var setItemsCount = 0
+
+  var isFadePendingOrActive: Bool { fadePending }
+  var attachedQueueItemIds: [String] { attached }
+
+  func setItems(_ items: [AVPlayerItem], startIndex: Int, startPositionSeconds: TimeInterval) {
+    setItemsCount += 1
+  }
+  func remove(_ item: AVPlayerItem) { removed.append(item) }
+  @discardableResult
+  func insertItems(_ items: [AVPlayerItem], after: AVPlayerItem?) -> Bool { true }
+  func setAudioMixProvider(_ provider: AudioMixProvider?) {}
+  func refreshAllItemMixes() {}
+  func release() {}
+  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 { 0 }
+  var currentPositionSeconds: TimeInterval { 0 }
+  var currentDurationSeconds: TimeInterval { 0 }
+  var bufferedPositionSeconds: TimeInterval { 0 }
+  var isPlaying: Bool { false }
+  var timeControlStatus: AVPlayer.TimeControlStatus { .paused }
+  var currentMediaItem: AVPlayerItem? { nil }
+  var allMediaItems: [AVPlayerItem] { [] }
+  var delegate: PlaybackEngineDelegate?
+}

package/ios/Tests/NowPlayingInfoTests.swift

@@ -22,6 +22,9 @@ final class NowPlayingInfoTests: XCTestCase {
 
   override func tearDown() {
     nowPlaying.clear()
+    // Drain before dropping the subject: writes are enqueued, so one left in
+    // flight would land during the next test and clobber its seeded state.
+    _ = nowPlayingInfoAfterWritesLand()
     nowPlaying = nil
     MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
     super.tearDown()
@@ -29,31 +32,34 @@ final class NowPlayingInfoTests: XCTestCase {
 
   // MARK: - refreshAll
 
-  func testRefreshAllClearsDictWhenSnapshotProviderReturnsNil() {
-    MPNowPlayingInfoCenter.default().nowPlayingInfo = ["pre": "existing"]
-    nowPlaying.snapshotProvider = nil
-    nowPlaying.refreshAll()
-    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+  func testRefreshAllPublishesTheSnapshotSuppliedToEachCall() {
+    let track = makeTrack(title: "T")
+    nowPlaying.refreshAll(
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1))
+    nowPlaying.refreshAll(
+      NowPlayingInfo.Snapshot(
+        track: track, elapsedSeconds: 40, durationSeconds: 90, rate: 0))
+    let info = nowPlayingInfoAfterWritesLand()
+    XCTAssertEqual(info?[MPNowPlayingInfoPropertyElapsedPlaybackTime] as? Double, 40)
+    XCTAssertEqual(info?[MPNowPlayingInfoPropertyPlaybackRate] as? Double, 0)
+    XCTAssertEqual(info?[MPMediaItemPropertyPlaybackDuration] as? Double, 90)
   }
 
   func testRefreshAllClearsDictWhenSnapshotHasNoTrack() {
     MPNowPlayingInfoCenter.default().nowPlayingInfo = ["pre": "existing"]
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: nil, elapsedSeconds: 0, durationSeconds: 0, rate: 0)
-    }
-    nowPlaying.refreshAll()
-    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+        track: nil, elapsedSeconds: 0, durationSeconds: 0, rate: 0))
+    XCTAssertNil(nowPlayingInfoAfterWritesLand())
   }
 
   func testRefreshAllPopulatesTitleArtistAlbum() {
     let track = makeTrack(title: "Song", artist: "Artist", album: "Album")
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 12, durationSeconds: 180, rate: 1)
-    }
-    nowPlaying.refreshAll()
-    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+        track: track, elapsedSeconds: 12, durationSeconds: 180, rate: 1))
+    let info = nowPlayingInfoAfterWritesLand()
     XCTAssertEqual(info?[MPMediaItemPropertyTitle] as? String, "Song")
     XCTAssertEqual(info?[MPMediaItemPropertyArtist] as? String, "Artist")
     XCTAssertEqual(info?[MPMediaItemPropertyAlbumTitle] as? String, "Album")
@@ -61,12 +67,10 @@ final class NowPlayingInfoTests: XCTestCase {
 
   func testRefreshAllEmptyStringCoercesNilTitleArtistAlbum() {
     let track = makeTrack(title: nil, artist: nil, album: nil)
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0)
-    }
-    nowPlaying.refreshAll()
-    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0))
+    let info = nowPlayingInfoAfterWritesLand()
     XCTAssertEqual(info?[MPMediaItemPropertyTitle] as? String, "")
     XCTAssertEqual(info?[MPMediaItemPropertyArtist] as? String, "")
     XCTAssertEqual(info?[MPMediaItemPropertyAlbumTitle] as? String, "")
@@ -77,12 +81,10 @@ final class NowPlayingInfoTests: XCTestCase {
     let omitted: [Double] = [0, -1, .nan, .infinity, -.infinity]
     for d in omitted {
       MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
-      nowPlaying.snapshotProvider = {
+      nowPlaying.refreshAll(
         NowPlayingInfo.Snapshot(
-          track: track, elapsedSeconds: 0, durationSeconds: d, rate: 0)
-      }
-      nowPlaying.refreshAll()
-      let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+          track: track, elapsedSeconds: 0, durationSeconds: d, rate: 0))
+      let info = nowPlayingInfoAfterWritesLand()
       XCTAssertNil(info?[MPMediaItemPropertyPlaybackDuration],
                    "duration must be omitted for value \(d)")
     }
@@ -90,23 +92,19 @@ final class NowPlayingInfoTests: XCTestCase {
 
   func testRefreshAllSetsDurationWhenFinitePositive() {
     let track = makeTrack(title: "T")
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 0, durationSeconds: 240, rate: 1)
-    }
-    nowPlaying.refreshAll()
-    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+        track: track, elapsedSeconds: 0, durationSeconds: 240, rate: 1))
+    let info = nowPlayingInfoAfterWritesLand()
     XCTAssertEqual(info?[MPMediaItemPropertyPlaybackDuration] as? Double, 240)
   }
 
   func testRefreshAllSetsAudioMediaType() {
     let track = makeTrack()
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 0, durationSeconds: 0, rate: 0)
-    }
-    nowPlaying.refreshAll()
-    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+        track: track, elapsedSeconds: 0, durationSeconds: 0, rate: 0))
+    let info = nowPlayingInfoAfterWritesLand()
     XCTAssertEqual(
       info?[MPNowPlayingInfoPropertyMediaType] as? UInt,
       MPNowPlayingInfoMediaType.audio.rawValue
@@ -115,12 +113,10 @@ final class NowPlayingInfoTests: XCTestCase {
 
   func testRefreshAllPlacesArtworkPlaceholder() {
     let track = makeTrack(title: "T")
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0)
-    }
-    nowPlaying.refreshAll()
-    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0))
+    let info = nowPlayingInfoAfterWritesLand()
     XCTAssertNotNil(info?[MPMediaItemPropertyArtwork])
     XCTAssertTrue(info?[MPMediaItemPropertyArtwork] is MPMediaItemArtwork)
   }
@@ -129,12 +125,10 @@ final class NowPlayingInfoTests: XCTestCase {
     let track = makeTrack(title: "T")
     let bad: [Double] = [.nan, .infinity, -.infinity, -5]
     for e in bad {
-      nowPlaying.snapshotProvider = {
+      nowPlaying.refreshAll(
         NowPlayingInfo.Snapshot(
-          track: track, elapsedSeconds: e, durationSeconds: 60, rate: 1)
-      }
-      nowPlaying.refreshAll()
-      let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+          track: track, elapsedSeconds: e, durationSeconds: 60, rate: 1))
+      let info = nowPlayingInfoAfterWritesLand()
       XCTAssertEqual(
         info?[MPNowPlayingInfoPropertyElapsedPlaybackTime] as? Double, 0,
         "elapsed must be 0 for value \(e)")
@@ -145,12 +139,10 @@ final class NowPlayingInfoTests: XCTestCase {
     let track = makeTrack(title: "T")
     let bad: [Float] = [.nan, .infinity, -.infinity]
     for r in bad {
-      nowPlaying.snapshotProvider = {
+      nowPlaying.refreshAll(
         NowPlayingInfo.Snapshot(
-          track: track, elapsedSeconds: 0, durationSeconds: 60, rate: r)
-      }
-      nowPlaying.refreshAll()
-      let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+          track: track, elapsedSeconds: 0, durationSeconds: 60, rate: r))
+      let info = nowPlayingInfoAfterWritesLand()
       XCTAssertEqual(
         info?[MPNowPlayingInfoPropertyPlaybackRate] as? Double, 0,
         "rate must be 0 for value \(r)")
@@ -161,12 +153,10 @@ final class NowPlayingInfoTests: XCTestCase {
 
   func testRefreshPositionAndRateNoOpWhenSnapshotHasNoTrack() {
     MPNowPlayingInfoCenter.default().nowPlayingInfo = ["pre": "value"]
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshPositionAndRate(
       NowPlayingInfo.Snapshot(
-        track: nil, elapsedSeconds: 5, durationSeconds: 60, rate: 1)
-    }
-    nowPlaying.refreshPositionAndRate()
-    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+        track: nil, elapsedSeconds: 5, durationSeconds: 60, rate: 1))
+    let info = nowPlayingInfoAfterWritesLand()
     XCTAssertEqual(info?["pre"] as? String, "value")
     XCTAssertNil(info?[MPNowPlayingInfoPropertyElapsedPlaybackTime])
   }
@@ -174,51 +164,39 @@ final class NowPlayingInfoTests: XCTestCase {
   func testRefreshPositionAndRateNoOpWhenDictNeverPopulated() {
     let track = makeTrack(title: "T")
     MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshPositionAndRate(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1)
-    }
-    nowPlaying.refreshPositionAndRate()
-    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1))
+    XCTAssertNil(nowPlayingInfoAfterWritesLand())
   }
 
   func testRefreshPositionAndRateNoOpAfterRefreshAllCleared() {
     let track = makeTrack(title: "T")
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1)
-    }
-    nowPlaying.refreshAll()
-    XCTAssertNotNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1))
+    XCTAssertNotNil(nowPlayingInfoAfterWritesLand())
 
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: nil, elapsedSeconds: 0, durationSeconds: 0, rate: 0)
-    }
-    nowPlaying.refreshAll()
-    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+        track: nil, elapsedSeconds: 0, durationSeconds: 0, rate: 0))
+    XCTAssertNil(nowPlayingInfoAfterWritesLand())
 
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshPositionAndRate(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 30, durationSeconds: 60, rate: 1)
-    }
-    nowPlaying.refreshPositionAndRate()
-    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+        track: track, elapsedSeconds: 30, durationSeconds: 60, rate: 1))
+    XCTAssertNil(nowPlayingInfoAfterWritesLand())
   }
 
   func testRefreshPositionAndRateUpdatesElapsedAndRate() {
     let track = makeTrack(title: "T")
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1)
-    }
-    nowPlaying.refreshAll()
-    nowPlaying.snapshotProvider = {
+        track: track, elapsedSeconds: 5, durationSeconds: 60, rate: 1))
+    nowPlaying.refreshPositionAndRate(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 30, durationSeconds: 60, rate: 0)
-    }
-    nowPlaying.refreshPositionAndRate()
-    let info = MPNowPlayingInfoCenter.default().nowPlayingInfo
+        track: track, elapsedSeconds: 30, durationSeconds: 60, rate: 0))
+    let info = nowPlayingInfoAfterWritesLand()
     XCTAssertEqual(info?[MPNowPlayingInfoPropertyElapsedPlaybackTime] as? Double, 30)
     XCTAssertEqual(info?[MPNowPlayingInfoPropertyPlaybackRate] as? Double, 0)
     XCTAssertEqual(info?[MPMediaItemPropertyTitle] as? String, "T")
@@ -228,12 +206,10 @@ final class NowPlayingInfoTests: XCTestCase {
 
   func testApplyArtworkUpdatesDictWhenPopulated() {
     let track = makeTrack(title: "T")
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0)
-    }
-    nowPlaying.refreshAll()
-    let placeholder = MPNowPlayingInfoCenter.default().nowPlayingInfo?[MPMediaItemPropertyArtwork]
+        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0))
+    let placeholder = nowPlayingInfoAfterWritesLand()?[MPMediaItemPropertyArtwork]
     let size = CGSize(width: 8, height: 8)
     let renderer = UIGraphicsImageRenderer(size: size)
     let custom = renderer.image { ctx in
@@ -241,8 +217,8 @@ final class NowPlayingInfoTests: XCTestCase {
       ctx.fill(CGRect(x: 0, y: 0, width: 8, height: 8))
     }
     nowPlaying.applyArtwork(custom)
-    let after = MPNowPlayingInfoCenter.default()
-      .nowPlayingInfo?[MPMediaItemPropertyArtwork] as? MPMediaItemArtwork
+    let after = nowPlayingInfoAfterWritesLand()?[
+      MPMediaItemPropertyArtwork] as? MPMediaItemArtwork
     XCTAssertNotNil(after)
     XCTAssertFalse((after as AnyObject) === (placeholder as AnyObject))
     let resolvedImage = after?.image(at: size)
@@ -256,21 +232,19 @@ final class NowPlayingInfoTests: XCTestCase {
     let renderer = UIGraphicsImageRenderer(size: CGSize(width: 8, height: 8))
     let custom = renderer.image { ctx in UIColor.red.setFill(); ctx.fill(CGRect(x: 0, y: 0, width: 8, height: 8)) }
     nowPlaying.applyArtwork(custom)
-    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+    XCTAssertNil(nowPlayingInfoAfterWritesLand())
   }
 
   // MARK: - clear
 
   func testClearNilsTheDict() {
     let track = makeTrack(title: "T")
-    nowPlaying.snapshotProvider = {
+    nowPlaying.refreshAll(
       NowPlayingInfo.Snapshot(
-        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0)
-    }
-    nowPlaying.refreshAll()
-    XCTAssertNotNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+        track: track, elapsedSeconds: 0, durationSeconds: 60, rate: 0))
+    XCTAssertNotNil(nowPlayingInfoAfterWritesLand())
     nowPlaying.clear()
-    XCTAssertNil(MPNowPlayingInfoCenter.default().nowPlayingInfo)
+    XCTAssertNil(nowPlayingInfoAfterWritesLand())
   }
 
   // MARK: - Helpers
@@ -286,7 +260,20 @@ final class NowPlayingInfoTests: XCTestCase {
   ) -> TrackItem {
     return TrackItem(
       id: id, url: url, title: title, artist: artist, album: album,
-      duration: duration, artworkUrl: artworkUrl, extras: nil
+      duration: duration, artworkUrl: artworkUrl, extras: nil,
+      replayGainTrackGain: nil, replayGainTrackPeak: nil,
+      replayGainAlbumGain: nil, replayGainAlbumPeak: nil
     )
   }
+
+  /// The Now Playing dictionary once the writes handed to main have landed.
+  /// `NowPlayingInfo` enqueues its writes rather than performing them inline,
+  /// so a read taken in the same turn still sees the previous value.
+  private func nowPlayingInfoAfterWritesLand() -> [String: Any]? {
+    let drained = expectation(description: "main queue drained")
+    DispatchQueue.main.async { drained.fulfill() }
+    wait(for: [drained], timeout: 2.0)
+    return MPNowPlayingInfoCenter.default().nowPlayingInfo
+  }
+
 }

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?
+}