react-native-audio-browser 0.2.0-next.18 → 0.2.0-next.19

package/src/web/__tests__/lifecycle.test.ts

@@ -0,0 +1,345 @@
+/** @vitest-environment happy-dom */
+
+import { beforeEach, describe, expect, it } from 'vitest'
+import { LifecycleHarness, trackA, trackB } from './lifecycleHarness'
+
+/**
+ * What the web player actually emits, recorded rather than reasoned about.
+ *
+ * Two halves, deliberately kept apart:
+ *
+ * - **Characterization** records today's behaviour. These assertions describe
+ *   what happens, not what should — a change to any of them means the emission
+ *   lifecycle moved, which is worth a deliberate look even when the move is an
+ *   improvement.
+ * - **Parity** asserts what native emits for the same flow, derived from
+ *   `PlaybackStateMachine.kt` and `PlayerListener.kt`. A divergence that is
+ *   known but not yet closed belongs here as `it.fails`: the target is
+ *   documented, the suite stays green while the gap stands, and the test
+ *   starts failing the moment someone closes it — at which point flip it to a
+ *   plain `it`.
+ *
+ * Fidelity: the harness runs the real wiring — `setupPlayer`, the real
+ * listeners, state machine and emitters — against a modelled Shaka whose
+ * behaviours are each cited to shaka-player 4.16.15's source. Every sequence
+ * below was also recorded in a real browser (Cypress against the Next.js
+ * example) and matched. Two modelled behaviours were *corrected* by that run:
+ * Shaka's teardown fires `emptied`/`loadstart` rather than `pause`, and a load
+ * that does not stall emits no Shaka `buffering` event at all.
+ */
+
+let h: LifecycleHarness
+
+beforeEach(async () => {
+  h = new LifecycleHarness()
+  await h.setup()
+})
+
+describe('characterization — what the player emits today', () => {
+  it('load announces the active track, then hands off to Shaka', async () => {
+    h.browser.load(trackA)
+    await h.flush()
+
+    expect(h.recorded).toEqual([
+      'queue',
+      'activeTrack',
+      'nowPlaying',
+      'state:loading',
+      'playing:false|buffering:false',
+      'state:buffering'
+    ])
+  })
+
+  it('the rest of a first load, paused', async () => {
+    h.browser.load(trackA)
+    await h.flush()
+    h.clear()
+    await h.completeLoad()
+
+    expect(h.recorded).toEqual(['state:ready'])
+  })
+
+  it('the rest of a first load, playWhenReady', async () => {
+    h.browser.setPlayWhenReady(true)
+    h.browser.load(trackA)
+    await h.flush()
+    h.clear()
+    await h.completeLoad()
+
+    // no `ready`: suppressed while the intent is to play, as native does
+    expect(h.recorded).toEqual([
+      'state:playing',
+      'playing:true|buffering:false'
+    ])
+  })
+
+  it('switching tracks while playing', async () => {
+    h.browser.setPlayWhenReady(true)
+    h.browser.load(trackA)
+    await h.flush()
+    await h.completeLoad()
+    h.clear()
+
+    h.browser.load(trackB)
+    await h.flush()
+    await h.completeLoad()
+
+    // No `paused`: the teardown inside Shaka's load() fires `emptied` and
+    // `loadstart`, not `pause` — confirmed in a real browser.
+    expect(h.recorded).toEqual([
+      'queue',
+      'activeTrack',
+      'nowPlaying',
+      'state:loading',
+      'playing:true|buffering:true',
+      'state:buffering',
+      'state:playing',
+      'playing:true|buffering:false'
+    ])
+  })
+
+  it('pause then play', async () => {
+    h.browser.setPlayWhenReady(true)
+    h.browser.load(trackA)
+    await h.flush()
+    await h.completeLoad()
+    h.clear()
+
+    h.browser.pause()
+    await h.flush()
+    h.browser.play()
+    await h.flush()
+
+    expect(h.recorded).toEqual([
+      'playWhenReady:false',
+      'playing:false|buffering:false',
+      'state:paused',
+      'playWhenReady:true',
+      'playing:true|buffering:false',
+      'state:playing'
+    ])
+  })
+
+  it('mid-queue track end auto-advances', async () => {
+    h.browser.setQueue([trackA, trackB])
+    h.browser.setPlayWhenReady(true)
+    h.browser.skip(0)
+    await h.flush()
+    await h.completeLoad()
+    h.clear()
+
+    h.endTrack()
+    await h.flush()
+
+    // Neither `paused` nor `ended`: the element fires both when a track plays
+    // out, and both are suppressed so an advance looks like native's.
+    expect(h.recorded).toEqual([
+      'activeTrack',
+      'nowPlaying',
+      'state:loading',
+      'playing:true|buffering:true',
+      'state:buffering'
+    ])
+  })
+
+  it('last track end ends the queue', async () => {
+    h.browser.setQueue([trackA])
+    h.browser.setPlayWhenReady(true)
+    h.browser.skip(0)
+    await h.flush()
+    await h.completeLoad()
+    h.clear()
+
+    h.endTrack()
+    await h.flush()
+
+    // the real end does report `ended`; only the end-of-track `paused` is gone
+    expect(h.recorded).toEqual([
+      'playWhenReady:false',
+      'playing:false|buffering:false',
+      'state:ended',
+      'queueEnded'
+    ])
+  })
+
+  it('stop', async () => {
+    h.browser.setPlayWhenReady(true)
+    h.browser.load(trackA)
+    await h.flush()
+    await h.completeLoad()
+    h.clear()
+
+    h.browser.stop()
+    await h.flush()
+
+    expect(h.recorded).toEqual([
+      'playWhenReady:false',
+      'playing:false|buffering:false',
+      'state:stopped'
+    ])
+  })
+
+  it('a load Shaka rejects', async () => {
+    h.failLoad()
+    h.browser.load(trackA)
+    await h.flush()
+
+    // the code is whatever the rejection carried; -1 is the normalizer's
+    // fallback for a plain Error
+    expect(h.recorded).toEqual([
+      'queue',
+      'activeTrack',
+      'nowPlaying',
+      'state:loading',
+      'playing:false|buffering:false',
+      'state:buffering',
+      'state:error',
+      'error:-1'
+    ])
+  })
+
+  it('a track with no src', async () => {
+    h.browser.load({ id: 'x', title: 'No src' })
+    await h.flush()
+
+    expect(h.recorded).toEqual([
+      'queue',
+      'activeTrack',
+      'nowPlaying',
+      'state:loading',
+      'playing:false|buffering:false',
+      'state:error',
+      'error:invalid_track'
+    ])
+  })
+})
+
+describe('parity — what native emits for the same flow', () => {
+  /**
+   * Android fires the active-track callback from `onMediaItemTransition`
+   * (PlayerListener.kt:106) and maps the same event to LOADING in `onEvents`
+   * (:216-224), which ExoPlayer runs after the individual callbacks.
+   */
+  it('announces the active track before reporting loading', async () => {
+    h.browser.load(trackA)
+    await h.flush()
+
+    const active = h.recorded.indexOf('activeTrack')
+    const loading = h.recorded.indexOf('state:loading')
+    expect(active).toBeGreaterThanOrEqual(0)
+    expect(loading).toBeGreaterThan(active)
+  })
+
+  /**
+   * Android always passes through STATE_BUFFERING after prepare. Shaka only
+   * fires its own `buffering` event when a load actually stalls, so a load
+   * served from cache used to skip the state entirely. `Player`'s `loading`
+   * listener now dispatches `waiting` alongside `trackLoading` so every load
+   * passes through it, as native's does.
+   */
+  it('reports buffering between loading and playing', async () => {
+    h.browser.setPlayWhenReady(true)
+    h.browser.load(trackA)
+    await h.flush()
+    await h.completeLoad()
+
+    expect(h.recorded).toContain('state:buffering')
+  })
+
+  /**
+   * Android suppresses READY while playWhenReady — "READY is a transient
+   * before PLAYING — suppress it so consumers don't flash a settled/non-loading
+   * state mid-startup" (PlaybackStateMachine.kt, STATE_READY branch). The web
+   * machine now takes `playWhenReady` on the two edges that produce `ready` and
+   * suppresses it the same way.
+   *
+   * The web-only hazard that comes with it: a browser can refuse `play()`.
+   * `Player.onPlayRejected` clears the intent on anything but an `AbortError`,
+   * so a blocked autoplay settles instead of stranding on `buffering`.
+   */
+  it('does not report ready mid-startup while playWhenReady', async () => {
+    h.browser.setPlayWhenReady(true)
+    h.browser.load(trackA)
+    await h.flush()
+    h.clear()
+    await h.completeLoad()
+
+    expect(h.recorded).not.toContain('state:ready')
+  })
+
+  /**
+   * Android never reports ENDED between tracks: STATE_ENDED is only reached at
+   * the end of the playlist, and a mid-playlist advance stays READY/BUFFERING.
+   * Web loads one track at a time, so the element's own `ended` used to surface
+   * and drop `PlayingState.playing` to false between every pair of tracks.
+   * `QueuePlayer.applyState` now advances without emitting it; the true queue
+   * end still reports `ended`.
+   */
+  it('does not report ended when the queue advances', async () => {
+    h.browser.setQueue([trackA, trackB])
+    h.browser.setPlayWhenReady(true)
+    h.browser.skip(0)
+    await h.flush()
+    await h.completeLoad()
+    h.clear()
+
+    h.endTrack()
+    await h.flush()
+
+    expect(h.recorded).not.toContain('state:ended')
+    expect(h.recorded).not.toContain('playing:false|buffering:false')
+  })
+
+  /**
+   * Android's transition cuts the outgoing item and reports LOADING, with no
+   * PAUSED in between — and web matches. The teardown inside Shaka's load()
+   * fires `emptied` and `loadstart`, never `pause`, even mid-playback.
+   * Confirmed in a real browser; reading the HTML load algorithm had suggested
+   * otherwise.
+   */
+  it('does not report paused when switching tracks', async () => {
+    h.browser.setPlayWhenReady(true)
+    h.browser.load(trackA)
+    await h.flush()
+    await h.completeLoad()
+    h.clear()
+
+    h.browser.load(trackB)
+    await h.flush()
+
+    expect(h.recorded).not.toContain('state:paused')
+  })
+
+  /**
+   * A track playing out fires `pause` before `ended` on the element, so web
+   * used to report `paused` at the end of every track where native reports
+   * nothing. The pause listener now ignores a pause raised once `ended` is
+   * already true.
+   */
+  it('does not report paused when a track plays out', async () => {
+    h.browser.setQueue([trackA, trackB])
+    h.browser.setPlayWhenReady(true)
+    h.browser.skip(0)
+    await h.flush()
+    await h.completeLoad()
+    h.clear()
+
+    h.endTrack()
+    await h.flush()
+
+    expect(h.recorded).not.toContain('state:paused')
+  })
+
+  /**
+   * Android reports LOADING off the media-item transition, before any network
+   * work, so the URL-resolution window has a state. Web now does the same: the
+   * announcement and `trackLoading` both happen when `load()` is called, so the
+   * pair keeps native's order and the window is no longer silent. Shaka's own
+   * `loading` arrives later and the state setter drops it as a no-op.
+   */
+  it('reports loading while the url is still resolving', async () => {
+    h.browser.load(trackA)
+
+    expect(h.browser.getPlayback().state).toBe('loading')
+  })
+})

package/src/web/__tests__/lifecycleHarness.ts

@@ -0,0 +1,351 @@
+import { vi } from 'vitest'
+import type { Track } from '../../types'
+import { NativeAudioBrowser } from '../NativeAudioBrowser'
+
+/**
+ * A recording harness for the web player's event lifecycle.
+ *
+ * Unlike the other web tests, this does **not** stub `this.player` /
+ * `this.element` — it runs the real `setupPlayer()`, so the real listeners,
+ * state machine and emitters are all wired up. Only the two *sources* are
+ * modelled: Shaka, via the mock installed below, and the media element's own
+ * events, which the harness fires explicitly.
+ *
+ * The model is not a browser. Every behaviour it reproduces is one verified in
+ * `shaka-player` 4.16.15's source, cited at the point it is modelled, so the
+ * recordings are only as true as those citations. A real-browser run is still
+ * the final word — see `lifecycle.test.ts` for which recordings are waiting on
+ * one.
+ */
+
+/** Events the harness records, in emission order. */
+export type Recorded = string
+
+export class FakeShakaPlayer {
+  private listeners = new Map<string, ((event: unknown) => void)[]>()
+  private assetUri: string | undefined
+  /** Set by the harness so `unload()` can reproduce the element teardown. */
+  onTeardown: (() => void) | undefined
+  private pendingLoad: (() => void) | undefined
+  private rejectLoad: ((reason: unknown) => void) | undefined
+  private failNextLoad = false
+  /** Every URL `load()` was called with, in order. */
+  readonly loadedUrls: string[] = []
+
+  static isBrowserSupported(): boolean {
+    return true
+  }
+
+  attach(): Promise<void> {
+    return Promise.resolve()
+  }
+
+  getNetworkingEngine(): { registerRequestFilter: () => void } {
+    return { registerRequestFilter: () => {} }
+  }
+
+  addEventListener(type: string, cb: (event: unknown) => void): void {
+    const existing = this.listeners.get(type) ?? []
+    existing.push(cb)
+    this.listeners.set(type, existing)
+  }
+
+  emit(type: string, detail?: unknown): void {
+    for (const cb of this.listeners.get(type) ?? []) cb({ type, detail })
+  }
+
+  /**
+   * Mirrors `shaka.Player.load` (player.js:1717+) in the two respects that
+   * matter to our listeners:
+   *
+   * 1. it unloads the previous asset first when one is loaded —
+   *    `if (this.assetUri_) { await this.unload(false) }` at :1757-1762;
+   * 2. it dispatches `loading` *after* that, at :1807, behind several awaits —
+   *    which is why the event never arrives synchronously.
+   */
+  async load(uri: string): Promise<void> {
+    this.loadedUrls.push(uri)
+    if (this.assetUri !== undefined) await this.unload()
+    this.assetUri = uri
+    this.emit('loading')
+    if (this.failNextLoad) throw new Error('401')
+    // Shaka's load() promise settles once the media is ready, i.e. after the
+    // buffering/loaded events — `finishLoad()` drives that.
+    await new Promise<void>((resolve, reject) => {
+      this.pendingLoad = resolve
+      this.rejectLoad = reject
+    })
+  }
+
+  finishLoad(): void {
+    const resolve = this.pendingLoad
+    this.pendingLoad = undefined
+    this.rejectLoad = undefined
+    resolve?.()
+  }
+
+  failLoads(): void {
+    this.failNextLoad = true
+  }
+
+  succeedLoads(): void {
+    this.failNextLoad = false
+  }
+
+  /** Raise a Shaka error, as a mid-playback failure would. */
+  raiseError(): void {
+    this.emit('error', { code: 3016, message: 'playback failed' })
+  }
+
+  /**
+   * Mirrors `unload()` (player.js:1445+). For `src=` content it clears the
+   * element and re-runs its load algorithm (:1603-1610 via
+   * `Dom.clearSourceFromVideo`).
+   *
+   * Verified in a real browser: that teardown fires `emptied` and `loadstart`
+   * — **not** `pause`, even with the element mid-playback. Reading the HTML
+   * load algorithm suggested otherwise; the browser disagreed. Nothing here
+   * dispatches an element event as a result.
+   */
+  async unload(): Promise<void> {
+    // Real Shaka aborts an in-flight load() when unload() is called, rejecting
+    // it with LOAD_INTERRUPTED (7000). Modelled because a caller that unloads
+    // eagerly must invalidate that load first, or its rejection surfaces as a
+    // playback error.
+    const reject = this.rejectLoad
+    this.rejectLoad = undefined
+    this.pendingLoad = undefined
+    reject?.({ code: 7000, message: 'LOAD_INTERRUPTED' })
+
+    this.assetUri = undefined
+    this.onTeardown?.()
+    return Promise.resolve()
+  }
+
+  retryStreaming(): void {}
+}
+
+vi.mock('shaka-player/dist/shaka-player.compiled', () => ({
+  default: {
+    polyfill: { installAll: () => {} },
+    Player: FakeShakaPlayer
+  }
+}))
+
+export class LifecycleHarness {
+  readonly browser = new NativeAudioBrowser()
+  readonly recorded: Recorded[] = []
+  private element!: HTMLMediaElement
+  private shaka!: FakeShakaPlayer
+  private elementPlaying = false
+
+  async setup(): Promise<void> {
+    // `setupPlayer` attaches the Shaka instance to `window` under __DEV__,
+    // which the bundler defines and the test environment does not.
+    ;(globalThis as unknown as { __DEV__: boolean }).__DEV__ = false
+
+    await this.browser.setupPlayer({})
+
+    const browser = this.browser as unknown as {
+      element: HTMLMediaElement
+      player: FakeShakaPlayer
+    }
+    this.element = browser.element
+    this.shaka = browser.player
+
+    // happy-dom's media element has no TimeRanges; `getProgress()` reads it.
+    Object.defineProperty(this.element, 'buffered', {
+      value: { length: 0, end: () => 0 },
+      configurable: true
+    })
+    Object.defineProperty(this.element, 'duration', {
+      value: 100,
+      configurable: true
+    })
+    Object.defineProperty(this.element, 'ended', {
+      value: false,
+      configurable: true
+    })
+    Object.defineProperty(this.element, 'currentTime', {
+      value: 0,
+      writable: true,
+      configurable: true
+    })
+    Object.defineProperty(this.element, 'seekable', {
+      value: { length: 0, end: () => 0 },
+      configurable: true
+    })
+    // happy-dom's play()/pause() do not fire media events, so the harness
+    // fires them where a browser would.
+    this.element.play = () => {
+      this.startedPlaying()
+      return Promise.resolve()
+    }
+    this.element.pause = () => {
+      this.pausedByCommand()
+    }
+
+    // No element event on teardown — see FakeShakaPlayer.unload(). It does
+    // reset the position though: clearing `src` and re-running the element's
+    // load algorithm puts `currentTime` back to 0, which is why a resume has
+    // to be remembered before the teardown rather than read after it.
+    this.shaka.onTeardown = () => {
+      this.elementPlaying = false
+      this.setPosition(0)
+    }
+
+    this.record()
+  }
+
+  private record(): void {
+    const push = (label: string) => this.recorded.push(label)
+    this.browser.onPlaybackChanged = (p) => push(`state:${p.state}`)
+    this.browser.onPlaybackActiveTrackChanged = () => push('activeTrack')
+    this.browser.onNowPlayingChanged = () => push('nowPlaying')
+    this.browser.onPlaybackQueueChanged = () => push('queue')
+    this.browser.onPlaybackQueueEnded = () => push('queueEnded')
+    this.browser.onPlaybackError = (e) =>
+      push(e.error ? `error:${e.error.code}` : 'errorCleared')
+    this.browser.onPlaybackPlayingState = (s) =>
+      push(`playing:${s.playing}|buffering:${s.buffering}`)
+    this.browser.onPlaybackPlayWhenReadyChanged = (e) =>
+      push(`playWhenReady:${e.playWhenReady}`)
+  }
+
+  clear(): void {
+    this.recorded.length = 0
+  }
+
+  private fireElement(type: string): void {
+    this.element.dispatchEvent(new Event(type))
+  }
+
+  private startedPlaying(): void {
+    this.elementPlaying = true
+    this.fireElement('playing')
+  }
+
+  private pausedByCommand(): void {
+    if (!this.elementPlaying) return
+    this.elementPlaying = false
+    this.fireElement('pause')
+  }
+
+  /**
+   * The rest of a successful Shaka load: `loaded`, then the `load()` promise
+   * settles, which is what lets the library's own `playWhenReady` handling
+   * start playback.
+   *
+   * Verified in a real browser: a load that does not stall emits **no**
+   * `buffering` event, so the PlaybackState goes `loading → ready → playing`
+   * with no `buffering` in it. Use {@link rebuffer} for the stalling case.
+   */
+  async completeLoad(): Promise<void> {
+    this.shaka.emit('loaded')
+    this.shaka.finishLoad()
+    await this.flush()
+  }
+
+  /** A mid-playback stall, which is where Shaka's `buffering` event does fire. */
+  async rebuffer(): Promise<void> {
+    this.shaka.emit('buffering', { buffering: true })
+    await this.flush()
+    this.shaka.emit('buffering', { buffering: false })
+    await this.flush()
+  }
+
+  /** Shaka rejecting the load, as a 401 would. */
+  failLoad(): void {
+    this.shaka.failLoads()
+  }
+
+  /** Stop rejecting loads, so a retry can succeed. */
+  succeedLoads(): void {
+    this.shaka.succeedLoads()
+  }
+
+  /** Resolves Shaka's pending load() without emitting its events. */
+  finishLoadOnly(): void {
+    this.shaka.finishLoad()
+  }
+
+  /** A mid-playback failure, rather than one raised by the load itself. */
+  raiseError(): void {
+    this.shaka.raiseError()
+  }
+
+  /** Every URL handed to Shaka's `load()`, in order. */
+  get loadedUrls(): string[] {
+    return this.shaka.loadedUrls
+  }
+
+  setPosition(seconds: number): void {
+    Object.defineProperty(this.element, 'currentTime', {
+      value: seconds,
+      writable: true,
+      configurable: true
+    })
+  }
+
+  get currentTime(): number {
+    return this.element.currentTime
+  }
+
+  /**
+   * A track playing out. Verified in a real browser: the element fires `pause`
+   * and then `ended`. `ended` is already true on the element by then — it is
+   * the ended-playback condition that triggers both — which is what the pause
+   * listener keys off to tell this apart from a real pause.
+   */
+  endTrack(): void {
+    this.elementPlaying = false
+    Object.defineProperty(this.element, 'ended', {
+      value: true,
+      configurable: true
+    })
+    this.fireElement('pause')
+    this.fireElement('ended')
+  }
+
+  flush(): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, 0))
+  }
+}
+
+/**
+ * A `media.resolve` whose every call hangs until released, so two loads can be
+ * interleaved deliberately — the only way to exercise what happens to a load
+ * that a newer one supersedes mid-resolution.
+ */
+export function deferredResolver(): {
+  configuration: { media: { resolve: () => Promise<{ path: string }> } }
+  /** Releases the nth call (1-based) with its own distinct URL. */
+  release: (n: number) => void
+  calls: () => number
+} {
+  const pending: Array<(value: { path: string }) => void> = []
+  return {
+    configuration: {
+      media: {
+        resolve: () =>
+          new Promise<{ path: string }>((resolve) => {
+            pending.push(resolve)
+          })
+      }
+    },
+    release: (n) =>
+      pending[n - 1]?.({ path: `https://cdn.example.com/${n}.mp3` }),
+    calls: () => pending.length
+  }
+}
+
+export const trackA: Track = {
+  id: 'a',
+  title: 'Track A',
+  src: 'https://media.example.com/a.mp3'
+}
+export const trackB: Track = {
+  id: 'b',
+  title: 'Track B',
+  src: 'https://media.example.com/b.mp3'
+}