react-native-queue-player 1.0.0

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerTransportTest.kt

@@ -0,0 +1,222 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertTrue
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * transport + playback-config tests for the
+ * Kotlin [TrackPlayer]. Exercises the player-local
+ * (non-queue-dependent) surface:
+ *
+ * - `play` / `pause` / `stop` — ExoPlayer bindings (empty-player
+ *   no-throw sanity only; real playback assertions land once
+ *   event wiring is in place).
+ * - `seekTo` — seconds→milliseconds + clamp semantics + non-finite
+ *   (NaN / Infinity) input sanitisation.
+ * - `setPlaybackSpeed` / `setVolume` + their readers — exercises
+ *   the production-path `*Internal` bodies so the `.toFloat()`
+ *   cast + pitch preservation aren't bypassed by direct ExoPlayer
+ *   writes.
+ * - `setRepeatMode` — state-only writer.
+ * - `getState` — `Player.STATE_*` → `PlayerState` translation
+ *   including the `playbackSuppressionReason` stall branch.
+ *
+ * Consistent: call the `Internal`
+ * overloads to avoid Nitro's Promise JNI surface (unavailable in
+ * the Robolectric runtime).
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class TrackPlayerTransportTest {
+
+  private lateinit var player: TrackPlayer
+
+  private fun context() = ApplicationProvider.getApplicationContext<android.content.Context>()
+
+  private lateinit var serviceHandle: PlaybackServiceTestHandle
+
+  @Before
+  fun setUp() {
+    player = TrackPlayer()
+    serviceHandle = bindPlaybackServiceForTest(player, context())
+    player.configureInternal(
+      PlayerConfig(httpHeaders = null, userAgent = null, autoRetries = null, retryBackoffMs = null, networkTimeoutMs = null, audioContentType = null, audioCategoryOptions = null, visualizationEnabled = null, clampSeekToBuffered = null, lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null, progressUpdateIntervalMs = null, backgroundProgressUpdateIntervalMs = null), context()
+    )
+  }
+
+  @After
+  fun tearDown() {
+    player.destroyInternal()
+    serviceHandle.destroy()
+  }
+
+  // --- getStateInternal translation
+
+  @Test
+  fun `getStateInternal returns NONE before configure`() {
+    val fresh = TrackPlayer()
+    assertEquals(PlayerState.NONE, fresh.getStateInternal())
+  }
+
+  @Test
+  fun `getStateInternal returns NONE on STATE_IDLE with empty queue`() {
+    // Fresh ExoPlayer, no tracks → NONE per iOS parity.
+    assertEquals(PlayerState.NONE, player.getStateInternal())
+  }
+
+  @Test
+  fun `getStateInternal returns PAUSED on STATE_IDLE when tracks loaded and currentTrackIndex set`() {
+    // Simulate populate tracks +
+    // currentTrackIndex while the ExoPlayer is still IDLE.
+    // iOS parity: paused-with-queue returns PAUSED, not NONE.
+    player.tracks = listOf(
+      TrackItem("t1", "https://example.com/1.m4a", null, null, null, null, null, null)
+    )
+    player.currentTrackIndex = 0
+
+    assertEquals(PlayerState.PAUSED, player.getStateInternal())
+  }
+
+  // --- seekToInternal clamping + non-finite sanitisation
+
+  @Test
+  fun `seekToInternal on a player with no item is a no-op`() {
+    // No MediaItem loaded → ExoPlayer.duration reads as TIME_UNSET.
+    // Should not throw.
+    player.seekToInternal(42.0)
+    assertEquals(PlayerState.NONE, player.getStateInternal())
+  }
+
+  @Test
+  fun `seekToInternal passes an early seek through before the item is loaded`() {
+    // Items present but unloaded → STATE_IDLE, so the seekability guard (which
+    // only no-ops a LOADED-and-unseekable track) doesn't fire and an early seek
+    // on eventually-seekable content still lands. The reset-to-start protection
+    // applies once the item is loaded (STATE_READY) and confirmed unseekable.
+    player.setQueueInternal(
+      (1..3).map { TrackItem("t$it", "https://example.com/$it.m4a", null, null, null, null, null, null) }
+    )
+    player.currentTrackIndex = 0
+
+    player.seekToInternal(42.0)
+
+    assertEquals(42_000L, player.player!!.currentPosition)
+  }
+
+  @Test
+  fun `seekToInternal clamps negative positions to zero`() {
+    player.seekToInternal(-5.0)
+    player.seekToInternal(-1e9)
+    assertEquals(PlayerState.NONE, player.getStateInternal())
+  }
+
+  @Test
+  fun `seekToInternal sanitises NaN to a no-op`() {
+    // Without the isFinite guard, (NaN * 1000.0).toLong() is 0 — a
+    // silent rewind, not what a NaN input should produce.
+    player.seekToInternal(Double.NaN)
+    assertEquals(0L, player.player!!.currentPosition)
+  }
+
+  @Test
+  fun `seekToInternal sanitises Infinity to a no-op`() {
+    // Without the isFinite guard, (Infinity * 1000.0).toLong() is
+    // Long.MAX_VALUE, which ExoPlayer treats as "seek past end".
+    player.seekToInternal(Double.POSITIVE_INFINITY)
+    player.seekToInternal(Double.NEGATIVE_INFINITY)
+    assertEquals(0L, player.player!!.currentPosition)
+  }
+
+  // --- setVolumeInternal / setPlaybackSpeedInternal
+
+  @Test
+  fun `setVolumeInternal round-trips through getVolume`() {
+    player.setVolumeInternal(1.0)
+    assertEquals(1.0, player.getVolume(), 0.001)
+
+    player.setVolumeInternal(0.25)
+    assertEquals(0.25, player.getVolume(), 0.001)
+
+    player.setVolumeInternal(0.0)
+    assertEquals(0.0, player.getVolume(), 0.001)
+  }
+
+  @Test
+  fun `setPlaybackSpeedInternal round-trips through getPlaybackSpeed and applies the pitch mode`() {
+    // Pitch is lib-owned, driven by the pitch-correction mode. Under the
+    // default voice mode the engine holds pitch at 1.0 while the speed
+    // changes (pitch preserved). The full none/voice/music mapping is
+    // covered by PitchCorrectionTest.
+    player.setPlaybackSpeedInternal(1.5)
+    assertEquals(1.5, player.getPlaybackSpeed(), 0.001)
+    assertEquals(1.0f, player.player!!.playbackParameters.pitch, 0.001f)
+
+    player.setPlaybackSpeedInternal(0.5)
+    assertEquals(0.5, player.getPlaybackSpeed(), 0.001)
+    assertEquals(
+      "voice mode holds pitch at 1.0 across speed changes",
+      1.0f, player.player!!.playbackParameters.pitch, 0.001f
+    )
+  }
+
+  @Test
+  fun `getPlaybackSpeed returns 1_0 when no player is configured`() {
+    val fresh = TrackPlayer()
+    assertEquals(1.0, fresh.getPlaybackSpeed(), 0.001)
+  }
+
+  @Test
+  fun `getVolume returns 1_0 when no player is configured`() {
+    val fresh = TrackPlayer()
+    assertEquals(1.0, fresh.getVolume(), 0.001)
+  }
+
+  // --- setRepeatMode (state-only writer)
+
+  @Test
+  fun `setRepeatMode stores the mode for skip logic to read`() {
+    assertEquals(RepeatMode.OFF, player.repeatModeState)
+
+    player.repeatModeState = RepeatMode.QUEUE
+    assertEquals(RepeatMode.QUEUE, player.repeatModeState)
+
+    player.repeatModeState = RepeatMode.TRACK
+    assertEquals(RepeatMode.TRACK, player.repeatModeState)
+  }
+
+  // shuffleQueue() is covered end-to-end via the demo suite
+  // shuffle.ts steps and by exercising shuffleQueueInternal in the
+  // sibling tests below.
+
+  // --- basic play/pause/stop no-op
+
+  @Test
+  fun `play on an empty player does not throw`() {
+    player.player!!.play()
+    assertNotNull(player.player)
+  }
+
+  @Test
+  fun `pause on an empty player does not throw`() {
+    player.player!!.pause()
+    assertNotNull(player.player)
+  }
+
+  @Test
+  fun `stop body (pause + seekTo 0) does not throw on empty player`() {
+    val p = player.player!!
+    p.pause()
+    p.seekTo(0L)
+    assertTrue("currentPosition stays at 0 with no item", p.currentPosition == 0L)
+  }
+}

package/android/src/test/java/com/margelo/nitro/queueplayer/TransportStateTranslatorTest.kt

@@ -0,0 +1,287 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.Player
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/**
+ * pure Kotlin state-translation matrix for
+ * [TransportStateTranslator]. Replaces the implicit matrix
+ * scattered across [TrackPlayerTransportTest] with a dedicated
+ * per-branch test set so:
+ *
+ * 1. Every combination of `(playbackState, isPlaying,
+ *    playWhenReady, suppressionReason, hasTracks, cur)` that
+ *    affects the output is covered exactly once.
+ * 2. The translator runs without a live ExoPlayer, so a regression
+ *    fails at ~1ms per case rather than the ~100ms Robolectric
+ *    setup cost.
+ */
+class TransportStateTranslatorTest {
+
+  // Default to a tracks-loaded queue so tests that exercise the
+  // ExoPlayer-state branches don't have to repeat the queue-state
+  // arguments. Tests that target the no-tracks branch override
+  // both `hasTracks` and `currentTrackIndex` explicitly.
+  private fun translate(
+    playbackState: Int,
+    isPlaying: Boolean = false,
+    playWhenReady: Boolean = false,
+    suppressionReason: Int = Player.PLAYBACK_SUPPRESSION_REASON_NONE,
+    hasTracks: Boolean = true,
+    currentTrackIndex: Int = 0
+  ) = TransportStateTranslator.translate(
+    playbackState = playbackState,
+    isPlaying = isPlaying,
+    playWhenReady = playWhenReady,
+    playbackSuppressionReason = suppressionReason,
+    hasTracks = hasTracks,
+    currentTrackIndex = currentTrackIndex
+  )
+
+  // --- STATE_IDLE
+
+  @Test
+  fun `STATE_IDLE with no tracks returns NONE`() {
+    assertEquals(
+      PlayerState.NONE,
+      translate(
+        playbackState = Player.STATE_IDLE,
+        hasTracks = false,
+        currentTrackIndex = -1
+      )
+    )
+  }
+
+  @Test
+  fun `STATE_IDLE with tracks but cur less than 0 returns NONE`() {
+    // Add-into-empty-queue semantic: tracks populated but cur
+    // stays at -1 until consumer calls skipToIndex(0).
+    assertEquals(
+      PlayerState.NONE,
+      translate(
+        playbackState = Player.STATE_IDLE,
+        hasTracks = true,
+        currentTrackIndex = -1
+      )
+    )
+  }
+
+  @Test
+  fun `STATE_IDLE with tracks and cur greater than or equal to 0 returns PAUSED`() {
+    // iOS-parity: paused-with-queue-loaded is distinct from
+    // nothing-loaded.
+    assertEquals(
+      PlayerState.PAUSED,
+      translate(playbackState = Player.STATE_IDLE)
+    )
+  }
+
+  // --- STATE_BUFFERING
+
+  @Test
+  fun `STATE_BUFFERING returns BUFFERING`() {
+    assertEquals(
+      PlayerState.BUFFERING,
+      translate(playbackState = Player.STATE_BUFFERING)
+    )
+  }
+
+  @Test
+  fun `STATE_BUFFERING with tracks returns BUFFERING`() {
+    assertEquals(
+      PlayerState.BUFFERING,
+      translate(
+        playbackState = Player.STATE_BUFFERING,
+        hasTracks = true,
+        currentTrackIndex = 3
+      )
+    )
+  }
+
+  @Test
+  fun `STATE_BUFFERING with no tracks returns NONE`() {
+    // Lib canonical state: nothing loaded → NONE, regardless of
+    // ExoPlayer's residual playbackState.
+    assertEquals(
+      PlayerState.NONE,
+      translate(
+        playbackState = Player.STATE_BUFFERING,
+        hasTracks = false,
+        currentTrackIndex = -1
+      )
+    )
+  }
+
+  // --- STATE_READY
+
+  @Test
+  fun `STATE_READY isPlaying=true returns PLAYING`() {
+    assertEquals(
+      PlayerState.PLAYING,
+      translate(playbackState = Player.STATE_READY, isPlaying = true)
+    )
+  }
+
+  @Test
+  fun `STATE_READY not playing and no suppression returns PAUSED`() {
+    assertEquals(
+      PlayerState.PAUSED,
+      translate(
+        playbackState = Player.STATE_READY,
+        isPlaying = false,
+        playWhenReady = false
+      )
+    )
+  }
+
+  @Test
+  fun `STATE_READY playWhenReady + suppressed (transient focus loss) returns BUFFERING`() {
+    // Audio focus loss. iOS parity:
+    // AVPlayer.timeControlStatus.waitingToPlayAtSpecifiedRate.
+    // Must NOT read as PAUSED (consumers would interpret as
+    // user-intent pause).
+    assertEquals(
+      PlayerState.BUFFERING,
+      translate(
+        playbackState = Player.STATE_READY,
+        isPlaying = false,
+        playWhenReady = true,
+        suppressionReason =
+          Player.PLAYBACK_SUPPRESSION_REASON_TRANSIENT_AUDIO_FOCUS_LOSS
+      )
+    )
+  }
+
+  @Test
+  fun `STATE_READY playWhenReady + suppressed (unsuitable output) returns BUFFERING`() {
+    // Media3 1.2+ adds PLAYBACK_SUPPRESSION_REASON_UNSUITABLE_AUDIO_OUTPUT
+    // for e.g. BT codec mismatch on route change. Same translation
+    // as focus loss — the branch keys on the non-zero reason,
+    // not the specific value.
+    assertEquals(
+      PlayerState.BUFFERING,
+      translate(
+        playbackState = Player.STATE_READY,
+        isPlaying = false,
+        playWhenReady = true,
+        suppressionReason =
+          Player.PLAYBACK_SUPPRESSION_REASON_UNSUITABLE_AUDIO_OUTPUT
+      )
+    )
+  }
+
+  @Test
+  fun `STATE_READY playWhenReady but not suppressed falls through to PAUSED`() {
+    // Defensive branch: playWhenReady=true without suppression
+    // would normally imply isPlaying=true, but Media3's listener
+    // can fire onPlayWhenReadyChanged before onIsPlayingChanged.
+    // Brief PAUSED emit is acceptable; the next isPlaying fire
+    // catches up.
+    assertEquals(
+      PlayerState.PAUSED,
+      translate(
+        playbackState = Player.STATE_READY,
+        isPlaying = false,
+        playWhenReady = true,
+        suppressionReason = Player.PLAYBACK_SUPPRESSION_REASON_NONE
+      )
+    )
+  }
+
+  @Test
+  fun `STATE_READY not playWhenReady + suppressed returns PAUSED (not BUFFERING)`() {
+    // If the consumer has explicitly NOT requested playback, a
+    // suppression reason is informational — don't pretend we're
+    // buffering to start. This mirrors iOS which only maps the
+    // waiting-to-play condition when the consumer is actively
+    // asking for playback.
+    assertEquals(
+      PlayerState.PAUSED,
+      translate(
+        playbackState = Player.STATE_READY,
+        isPlaying = false,
+        playWhenReady = false,
+        suppressionReason =
+          Player.PLAYBACK_SUPPRESSION_REASON_TRANSIENT_AUDIO_FOCUS_LOSS
+      )
+    )
+  }
+
+  // --- STATE_ENDED
+
+  @Test
+  fun `STATE_ENDED returns ENDED`() {
+    assertEquals(
+      PlayerState.ENDED,
+      translate(playbackState = Player.STATE_ENDED)
+    )
+  }
+
+  @Test
+  fun `STATE_ENDED with tracks returns ENDED`() {
+    assertEquals(
+      PlayerState.ENDED,
+      translate(
+        playbackState = Player.STATE_ENDED,
+        hasTracks = true,
+        currentTrackIndex = 4
+      )
+    )
+  }
+
+  @Test
+  fun `STATE_ENDED with no tracks returns NONE`() {
+    // After `clearQueue` Media3 can briefly retain `STATE_ENDED`
+    // because `setMediaItems(emptyList())` doesn't synchronously
+    // transition the player to `STATE_IDLE`. The lib-facing
+    // contract is "nothing loaded → NONE", so the no-tracks
+    // guard pre-empts the raw playbackState read.
+    assertEquals(
+      PlayerState.NONE,
+      translate(
+        playbackState = Player.STATE_ENDED,
+        hasTracks = false,
+        currentTrackIndex = -1
+      )
+    )
+  }
+
+  // --- unknown state
+
+  @Test
+  fun `unknown playbackState with tracks falls back to NONE`() {
+    // Media3 may add future playback states. Defensive fallthrough
+    // keeps the state machine total — critical because a
+    // non-total state machine can starve the event stream.
+    assertEquals(
+      PlayerState.NONE,
+      translate(playbackState = -999)
+    )
+    assertEquals(
+      PlayerState.NONE,
+      translate(playbackState = 0)
+    )
+  }
+
+  // --- isPlaying wins over suppression
+
+  @Test
+  fun `STATE_READY isPlaying=true wins even when suppression is set`() {
+    // Media3 may briefly report isPlaying=true with a non-zero
+    // suppression reason during the cancel-of-suppression cycle.
+    // PLAYING is the correct user-facing state; isPlaying is the
+    // canonical truth-source for "audio is currently producing
+    // frames".
+    assertEquals(
+      PlayerState.PLAYING,
+      translate(
+        playbackState = Player.STATE_READY,
+        isPlaying = true,
+        playWhenReady = true,
+        suppressionReason =
+          Player.PLAYBACK_SUPPRESSION_REASON_TRANSIENT_AUDIO_FOCUS_LOSS
+      )
+    )
+  }
+}

package/android/src/test/java/com/margelo/nitro/queueplayer/VisualizationGateTest.kt

@@ -0,0 +1,96 @@
+package com.margelo.nitro.queueplayer
+
+import org.junit.After
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+/**
+ * Unit coverage for [VisualizationGate] — the process-wide
+ * `AtomicBoolean` flag written by `TrackPlayer.configureInternal`
+ * from `PlayerConfig.visualizationEnabled` and read by the engines'
+ * field-init renderers-factory branch + `Visualizer.subscribe`'s
+ * disabled gate.
+ *
+ * Tests run in JVM (not Robolectric — the gate is a pure Kotlin
+ * object, no Android dependency), but live alongside the Robolectric
+ * suite so the gradle `testDebugUnitTest` task picks them up.
+ */
+class VisualizationGateTest {
+
+  @After
+  fun tearDown() {
+    // Restore the default true so subsequent tests see the documented
+    // initial state. The gate is process-wide, so leakage between
+    // tests would otherwise be possible.
+    VisualizationGate.setEnabled(true)
+  }
+
+  @Test
+  fun `default state is enabled`() {
+    // Set explicitly because a prior test in the same JVM might have
+    // mutated it. The teardown above restores after, but the assertion
+    // here is "enabled is the documented default".
+    VisualizationGate.setEnabled(true)
+    assertTrue(VisualizationGate.isEnabled())
+  }
+
+  @Test
+  fun `setEnabled mirrors through isEnabled`() {
+    VisualizationGate.setEnabled(false)
+    assertFalse(VisualizationGate.isEnabled())
+    VisualizationGate.setEnabled(true)
+    assertTrue(VisualizationGate.isEnabled())
+  }
+
+  @Test
+  fun `idempotent re-write is harmless`() {
+    VisualizationGate.setEnabled(true)
+    VisualizationGate.setEnabled(true)
+    assertTrue(VisualizationGate.isEnabled())
+    VisualizationGate.setEnabled(false)
+    VisualizationGate.setEnabled(false)
+    assertFalse(VisualizationGate.isEnabled())
+  }
+
+  @Test
+  fun `concurrent reads observe writer values without tearing`() {
+    // The gate is read from the audio render thread (engine field-init
+    // → renderers factory branch) + the JS bridge thread (subscribe).
+    // Writes happen on main from configure. AtomicBoolean serialises
+    // both. Spin 8 readers + 1 writer alternating true/false; collect
+    // every observed read; assert no torn read returned a non-Boolean
+    // value, and that the final state matches the writer's last
+    // pinned write.
+    val observed = java.util.concurrent.ConcurrentLinkedQueue<Boolean>()
+    val readers = (0 until 8).map {
+      Thread {
+        for (i in 0 until 500) {
+          observed.add(VisualizationGate.isEnabled())
+        }
+      }
+    }
+    val writer = Thread {
+      for (i in 0 until 500) {
+        VisualizationGate.setEnabled(i % 2 == 0)
+      }
+      // Pin the final state to a known value so the post-join
+      // assertion can compare deterministically.
+      VisualizationGate.setEnabled(true)
+    }
+    readers.forEach { it.start() }
+    writer.start()
+    readers.forEach { it.join() }
+    writer.join()
+    // Every observed value must be a valid Boolean (not some torn
+    // intermediate). With AtomicBoolean this is trivially true on
+    // any sane JVM, but the assertion catches a future regression
+    // that swaps to a non-volatile primitive.
+    val invalid = observed.filterNot { it == true || it == false }
+    assertTrue("torn reads observed: $invalid", invalid.isEmpty())
+    assertTrue(
+      "expected final state true after writer pin, got false",
+      VisualizationGate.isEnabled(),
+    )
+  }
+}