react-native-queue-player 1.2.0 → 2.0.1

package/ios/Tests/TrackPlayer+TestHops.swift

@@ -0,0 +1,14 @@
+@testable import QueuePlayer
+
+extension TrackPlayer {
+  /// Runs `body` on `playerQueue` and hands its value back — the read side of
+  /// the tests' player-state assertions. The library has no async getter that
+  /// needs this; its own hops are `onPlayerQueue` and `onPlayerQueueSync`.
+  func onPlayerQueueValue<T>(_ body: @escaping () -> T) async -> T {
+    await withCheckedContinuation { (cont: CheckedContinuation<T, Never>) in
+      playerQueue.async {
+        cont.resume(returning: body())
+      }
+    }
+  }
+}

package/ios/Tests/TrackPlayerCallOrderTests.swift

@@ -0,0 +1,93 @@
+import XCTest
+@testable import QueuePlayer
+
+/// Queue mutations reach the player in the order JS called them.
+///
+/// Each method is issued and a probe is enqueued immediately afterwards, the
+/// way a transport call issued on the next line would be. The probe runs on
+/// `playerQueue` behind whatever the method enqueued, so what it observes is
+/// what that next call would act on.
+final class TrackPlayerCallOrderTests: 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()
+  }
+
+  func testSetQueueIsVisibleToWorkEnqueuedAfterIt() async throws {
+    let tracks = try PlayerFixtures.localTracks(count: 3, for: self)
+
+    _ = try player.setQueue(tracks: tracks, startAtIndex: 1)
+    let seen = try await probe { (count: $0.tracks.count, index: $0.currentTrackIndex) }
+
+    XCTAssertEqual(seen.count, 3)
+    XCTAssertEqual(seen.index, 1)
+  }
+
+  func testAddToQueueIsVisibleToWorkEnqueuedAfterIt() async throws {
+    _ = try await player.setQueue(tracks: PlayerFixtures.localTracks(count: 3, for: self), startAtIndex: 0).await()
+
+    _ = try player.addToQueue(tracks: PlayerFixtures.localTracks(count: 2, for: self), insertBefore: nil)
+    let count = try await probe { $0.tracks.count }
+
+    XCTAssertEqual(count, 5)
+  }
+
+  /// The immediate-next slot is the insert `AVQueuePlayer` prerolls, so it is
+  /// the one whose commit is most at risk of being deferred.
+  func testAnImmediateNextInsertIsVisibleToWorkEnqueuedAfterIt() async throws {
+    _ = try await player.setQueue(tracks: PlayerFixtures.localTracks(count: 3, for: self), startAtIndex: 0).await()
+
+    _ = try player.addToQueue(tracks: PlayerFixtures.localTracks(count: 1, for: self), insertBefore: 1)
+    let count = try await probe { $0.tracks.count }
+
+    XCTAssertEqual(count, 4)
+  }
+
+  func testRemoveFromQueueIsVisibleToWorkEnqueuedAfterIt() async throws {
+    _ = try await player.setQueue(tracks: PlayerFixtures.localTracks(count: 4, for: self), startAtIndex: 0).await()
+
+    _ = try player.removeFromQueue(indices: [2, 3])
+    let count = try await probe { $0.tracks.count }
+
+    XCTAssertEqual(count, 2)
+  }
+
+  func testMoveInQueueIsVisibleToWorkEnqueuedAfterIt() async throws {
+    _ = try await player.setQueue(tracks: PlayerFixtures.localTracks(count: 3, for: self), startAtIndex: 0).await()
+
+    _ = try player.moveInQueue(fromIndex: 2, toIndex: 1)
+    let idAtOne = try await probe { $0.tracks[1].id }
+
+    XCTAssertEqual(idAtOne, "t2")
+  }
+
+  /// A start index of NaN reaches `Int(_:)` unless it is guarded in `Double`
+  /// space, where the conversion is undefined behaviour.
+  func testANonFiniteStartIndexResolvesToTheQueueHead() async throws {
+    _ = try player.setQueue(tracks: PlayerFixtures.localTracks(count: 3, for: self), startAtIndex: Double.nan)
+    let index = try await probe { $0.currentTrackIndex }
+
+    XCTAssertEqual(index, 0)
+  }
+
+  // MARK: - Helpers
+
+  /// Enqueue a read behind whatever the call under test just enqueued.
+  private func probe<T>(_ body: @escaping (TrackPlayer) -> T) async throws -> T {
+    let player = try XCTUnwrap(self.player)
+    return await player.onPlayerQueueValue { body(player) }
+  }
+
+}

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,206 @@
+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: - A drain that is really a failure
+
+  /// A drain that follows the current track's reported failure stays where it
+  /// is rather than wrapping.
+  func testADrainAfterTheCurrentTrackFailedDoesNotAdvanceTheQueue() async throws {
+    try await seedQueue(count: 3, at: 2, repeatMode: .queue)
+    await onQueue { $0.reportedFailureQueueItemIds = [$0.queueItemIds[2]] }
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let state = try await read { (index: $0.currentTrackIndex, ended: $0.reachedQueueEnd) }
+    XCTAssertEqual(state.index, 2, "the queue stays on the track whose failure was reported")
+    XCTAssertFalse(state.ended, "a reported failure is not the end of the queue either")
+  }
+
+  /// The crossfade engine's own end signal reaches the same decision.
+  func testAnEngineEndReportAfterTheCurrentTrackFailedDoesNotAdvanceTheQueue() async throws {
+    try await installCrossfade()
+    try await seedQueue(count: 3, at: 2, repeatMode: .queue)
+    await onQueue { $0.reportedFailureQueueItemIds = [$0.queueItemIds[2]] }
+    let engine = try await read { $0.engine }
+    let reporting = try XCTUnwrap(engine)
+
+    await onQueue { $0.enginePlaybackEnded(reporting) }
+
+    let index = try await read { $0.currentTrackIndex }
+    XCTAssertEqual(index, 2)
+  }
+
+  /// A report against a track the playhead has left does not hold a genuine
+  /// end of queue open.
+  func testADrainAfterADifferentTrackFailedStillEndsTheQueue() async throws {
+    try await seedQueue(count: 3, at: 2, repeatMode: .off)
+    await onQueue { $0.reportedFailureQueueItemIds = [$0.queueItemIds[0]] }
+
+    await onQueue { $0.applyEndVerdict() }
+
+    let ended = try await read { $0.reachedQueueEnd }
+    XCTAssertTrue(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)
+  }
+
+}