From c54da03bd71df47479fc7ebaf39045ac73d4801c Mon Sep 17 00:00:00 2001 From: Bogdan Chadkin Date: Fri, 13 Nov 2026 23:05:44 +0100 Subject: [PATCH] Cover native playback recovery and document iPhone validation --- CONTRIBUTING.md | 4 +- README.md | 2 +- docs/iphone-validation.md | 28 +++++++ tests/audio-transport.test.ts | 64 ++++++++++++++++ tests/browser/downloads.test.cjs | 119 ++++++++++++++++++++++++++++- tests/browser/pwa-updates.test.cjs | 107 +++++++++++++++++++++++++- 6 files changed, 317 insertions(+), 7 deletions(-) create mode 100644 docs/iphone-validation.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a254727..33a1d22 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -115,6 +115,8 @@ Select suites for the behavior being changed: `cache-downloads.test.cjs` exercises native OPFS close/publication boundaries and restart-from-scratch behavior by importing the owning modules. Run it against the app **dev** server; Downloads, Settings, and navigation checks can run against production preview. +`downloads.test.cjs` also decodes a small WAV fixture through the real audio element: cached seeking, durable pause/resume across reload without autoplay, browser-network-offline playback/seek, and explicit retry after a native pause. The shell reload itself is online so the suite also works against dev; offline app-shell navigation/update is covered by the production worker suites. Set `BROWSER=webkit` to run this same suite with an externally installed WebKit runtime; failures/unavailable prerequisites are not passes. Neither automation engine establishes physical iPhone background behavior. Use the [physical iPhone protocol](docs/iphone-validation.md) for Safari and installed mode. + Run the website suite against the website server, not the app: ```sh @@ -137,7 +139,7 @@ This suite owns its server and temporary `/webapp/` production builds; no previe NODE_PATH=/path/to/external/node_modules node --test tests/browser/pwa-updates.test.cjs ``` -It uses real generated workers, pre-hash fixture-only document markers, and native events/UI approval. It checks fresh installation, two-tab consent, C/D discovery in an unreloaded B document, offline application, failed-precache recovery, and preexisting waiting updates without clearing storage between versions. Temporary builds, contexts, browser, and server are cleaned up; root/website outputs are untouched. Logs include document tokens, preserved URLs, worker hashes, and native transitions. +It uses real generated workers, pre-hash fixture-only document markers, and native events/UI approval. It checks fresh installation, two-tab consent, C/D discovery in an unreloaded B document, offline application, failed-precache recovery, preexisting waiting updates, and local queue/resume preservation without autoplay after an approved update, without clearing storage between versions. Temporary builds, contexts, browser, and server are cleaned up; root/website outputs are untouched. Logs include document tokens, preserved URLs, worker hashes, and native transitions. Old-plugin migration is explicitly skipped unless `PWA_OLD_DIST` points to an untouched production artifact built at `/webapp/`. To reproduce the original baseline without changing this checkout: diff --git a/README.md b/README.md index d9c4f33..c9b6638 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,7 @@ You can use Libras in your browser or install it as a standalone web app: - **Android:** Choose **Install app / Add to home screen** from the browser menu. - **Desktop:** Use the browser's install option, where available. -Installation options vary by browser and device. Offline storage and background playback have not yet been verified on iOS. +Installation options vary by browser and device. Offline storage and background playback have not yet been verified on iOS. Physical iPhone validation is **NOT PERFORMED / PENDING DEVICE ACCESS**; see the [Safari and installed-mode validation protocol](docs/iphone-validation.md). ## Listen offline diff --git a/docs/iphone-validation.md b/docs/iphone-validation.md new file mode 100644 index 0000000..8ef8b87 --- /dev/null +++ b/docs/iphone-validation.md @@ -0,0 +1,28 @@ +# Physical iPhone playback and recovery validation + +**Result: NOT PERFORMED / PENDING DEVICE ACCESS.** No physical iPhone is available in the automated environment. Desktop Chromium or automated WebKit results do not establish iPhone background playback, lock-screen integration, or installed-mode behavior. + +Run this protocol separately in Safari and Add to Home Screen installed mode, on the same tested HTTPS origin. Use a disposable account and retain sanitized observations; never include credentials or credential-bearing media URLs. + +## Record + +- Date/tester, device model, iOS build, Safari version, browser or installed mode. +- App commit/build, origin/base path, server/version and CORS setup. +- Raw audio codec/container and duration; transcoded format and server settings. +- For each step: PASS / FAIL / NOT RUN, actual behavior, timestamps, sanitized logs, and reproduction steps. Do not replace this pending result without device evidence. + +## Protocol (both modes) + +1. Connect to a reachable HTTPS/CORS-enabled server. Play supported raw audio, then a source requiring transcoding fallback. Verify pause, resume, seek forward/backward and track changes. Record any activation-required error and explicit Play retry. +2. Check Media Session title/artwork, lock-screen play/pause/next/previous, screen lock and background playback. Navigate within the app and return from another app; confirm queue/position and that audio is not duplicated. +3. Interrupt with a call/alarm/another audio app. Switch speaker/headphones/Bluetooth output, disconnect the output, then return to the foreground and retry explicitly if required. Record OS-specific pause/resume behavior rather than assuming automatic recovery. +4. Download music to completion. Choose Work offline and airplane mode. Play and seek cached audio, including after pausing/resuming. Confirm uncached queue entries remain visible/removable and unavailable, without silently rewriting the queue. +5. Pause at a known position, background/close and relaunch. Verify saved selection/position, **no autoplay**, then explicit Play offline. Repeat in installed mode. Distinguish normal relaunch from OS termination/eviction; storage and the last uncheckpointed edit are not guaranteed after eviction. +6. Interrupt an active queued download by Work offline, network loss, and app termination (separate trials). Reconnect explicitly. Queued jobs restart from scratch; failed jobs require Retry. Verify playable completed files, correct byte totals, and no phantom completed records or corrupt audio. +7. Lose the network during remote playback/load/seek. Verify honest failure/interruption and explicit recovery after reconnect. Confirm cached playback still works and reconnection never replaces the local queue. Test explicit Load/Save server queue separately; load must not autoplay. +8. With an update waiting, decline/dismiss first: no reload. Approve Update now: only this approving document reloads, route and durable local queue/position survive, playback does not autoplay. Repeat with an already-installed update while offline and a second unapproved tab. +9. Open the same account in another tab: activation is blocked. Close the owner, choose Retry, and verify local queue/resume. Disconnect without deletion: credentials disappear but offline music remains. Reconnect, cancel/Escape local removal, then confirm deletion: this account's bytes disappear and active cached audio unloads; other accounts/server data remain unchanged. + +## Evidence and limitations + +Attach one result table per mode and raw/transcoded source, with failures and unrun steps explicit. Include sanitized console/service-worker observations where available, output-device details, time spent backgrounded/locked, and any OS eviction or termination. A successful short run is not a guarantee of indefinite iOS background execution or durable storage retention. diff --git a/tests/audio-transport.test.ts b/tests/audio-transport.test.ts index bd0352e..70b1b81 100644 --- a/tests/audio-transport.test.ts +++ b/tests/audio-transport.test.ts @@ -170,6 +170,70 @@ describe("AudioTransport without a mounted component", () => { expect(release).toHaveBeenCalledOnce(); }); + it("ignores a delayed play rejection after interruption and retries only explicitly", async () => { + const { transport, audio, track, getSource, release } = setup(); + const playing = deferred(); + audio.play.mockReturnValueOnce(playing.promise); + const pending = transport.play(track); + await vi.waitFor(() => expect(audio.play).toHaveBeenCalledOnce()); + transport.pause(); + playing.reject(new DOMException("Interrupted", "AbortError")); + await pending; + expect(transport.status).toBe("ready"); + expect(transport.error).toBeUndefined(); + expect(transport.playing).toBe(false); + expect(release).toHaveBeenCalledOnce(); + expect(getSource).toHaveBeenCalledOnce(); + await transport.resume(); + expect(transport.playing).toBe(true); + expect(getSource).toHaveBeenCalledTimes(2); + transport.dispose(); + expect(release).toHaveBeenCalledTimes(2); + }); + + it("cancels a seek waiting for metadata and ignores late metadata and errors", async () => { + const { transport, audio, track, getSource, release } = setup(); + getSource.mockResolvedValue({ url: "blob:stream", seekMode: "buffered", release }); + await transport.play(track); + audio.readyState = 0; + const seeking = transport.seek(75); + await vi.waitFor(() => expect(audio.src).toBe("blob:stream")); + expect(transport.status).toBe("seeking"); + transport.pause(); + await seeking; + audio.dispatchEvent(new Event("loadedmetadata")); + audio.dispatchEvent(new Event("error")); + expect(transport.position).toBe(75); + expect(transport.status).toBe("ready"); + expect(transport.playing).toBe(false); + expect(audio.src).toBe(""); + expect(release).toHaveBeenCalledTimes(2); + audio.readyState = 1; + await transport.resume(); + expect(audio.currentTime).toBe(75); + expect(transport.playing).toBe(true); + transport.dispose(); + expect(release).toHaveBeenCalledTimes(3); + }); + + it("does not let a failed retired seek poison a replacement track", async () => { + const { transport, audio, track, getSource, release } = setup(); + getSource.mockResolvedValueOnce({ url: "blob:stream", seekMode: "buffered", release }); + await transport.play(track); + const source = deferred(); + getSource.mockReturnValueOnce(source.promise); + const seeking = transport.seek(90); + const signal = getSource.mock.calls[1]![0].signal; + await transport.play({ ...track, metadata: { title: "Replacement" } }); + source.reject(new Error("Retired account failed")); + await seeking; + expect(signal.aborted).toBe(true); + expect(transport.metadata?.title).toBe("Replacement"); + expect(transport.error).toBeUndefined(); + expect(transport.playing).toBe(true); + expect(audio.src).toBe("blob:track"); + }); + it("does not restart if an idle notification disposes the transport during replacement", async () => { const { transport, track, getSource, onstatechange } = setup(); await transport.play(track); diff --git a/tests/browser/downloads.test.cjs b/tests/browser/downloads.test.cjs index 93dfb07..fc5f9da 100644 --- a/tests/browser/downloads.test.cjs +++ b/tests/browser/downloads.test.cjs @@ -1,7 +1,7 @@ // Real app/engines/OPFS, with only the Subsonic transport intercepted. const assert = require("node:assert/strict"); const { test } = require("node:test"); -const { chromium } = require("playwright"); +const { chromium, webkit } = require("playwright"); const fs = require("node:fs/promises"); const path = require("node:path"); @@ -15,6 +15,7 @@ const tracks = Array.from({ length: 6 }, (_, i) => ({ album: album.name, artists: [artist], contentType: "audio/mpeg", + duration: 60, ...(i === 0 ? { coverArt: "cover" } : {}), })); @@ -32,12 +33,21 @@ const otherTracks = [ ]; test("Downloads redesign preserves real transfer states and offline files", async (t) => { - const browser = await chromium.launch({ headless: true }); + const browserType = process.env.BROWSER === "webkit" ? webkit : chromium; + const browser = await browserType.launch({ headless: true }); + console.log(`Playback/download recovery: ${browserType.name()} ${browser.version()}`); const page = await browser.newPage({ viewport: { width: 1280, height: 900 }, reducedMotion: "reduce", }); await page.addInitScript(() => { + const NativeAudio = window.Audio; + window.Audio = class extends NativeAudio { + constructor(...args) { + super(...args); + window.testAudio = this; + } + }; const play = HTMLMediaElement.prototype.play; HTMLMediaElement.prototype.play = function (...args) { window.testAudio = this; @@ -463,6 +473,111 @@ test("Downloads redesign preserves real transfer states and offline files", asyn assert.equal(await page.getByRole("button", { name: /^Retry download of 6/ }).count(), 0); }); + await t.test( + "decoded cached audio seeks offline and restores local resume without autoplay", + async () => { + await navigate("/library"); + await playCached(); + await page.waitForFunction(() => window.testAudio.currentTime > 0); + assert.equal(await page.evaluate(() => window.testAudio.duration), 60); + await page + .locator(".app-sidebar") + .getByRole("button", { name: "Work offline", exact: true }) + .click(); + const before = requests; + // Native input event drives the real Playback/transport seek, not a parallel model. + await page + .getByRole("slider", { name: "Playback position" }) + .filter({ visible: true }) + .evaluate((input) => { + input.value = "23"; + input.dispatchEvent(new Event("input", { bubbles: true })); + }); + await page.waitForFunction(() => window.testAudio.currentTime >= 23); + await page + .locator(".mini-player") + .getByRole("button", { name: "Pause", exact: true }) + .click(); + const savedQueue = await page.locator("#player-dialog .track-row .label").allTextContents(); + const savedPosition = await page + .getByRole("slider", { name: "Playback position" }) + .filter({ visible: true }) + .inputValue(); + // Observe the actual queue checkpoint before simulating termination/reload. + await page.waitForFunction(async (position) => { + const accounts = await ( + await navigator.storage.getDirectory() + ).getDirectoryHandle("accounts"); + for await (const [, directory] of accounts.entries()) { + const file = await (await directory.getFileHandle("queue.json")).getFile(); + if (Math.abs(JSON.parse(await file.text()).position - Number(position)) < 1) + return true; + } + return false; + }, savedPosition); + // Reload the shell online (also supports the dev server); Work offline persists. + // Native network-offline playback is checked below after hydration. + await page.reload(); + await page.getByRole("radio", { name: "Downloaded", exact: true }).waitFor(); + assert.equal(await page.evaluate(() => window.testAudio.paused), true); + assert.equal(await page.evaluate(() => window.testAudio.currentSrc), ""); + assert.deepEqual( + await page.locator("#player-dialog .track-row .label").allTextContents(), + savedQueue, + ); + assert.ok( + Math.abs( + Number( + await page + .getByRole("slider", { name: "Playback position" }) + .filter({ visible: true }) + .inputValue(), + ) - Number(savedPosition), + ) < 1, + ); + await page.context().setOffline(true); + await page + .locator(".mini-player") + .getByRole("button", { name: "Play", exact: true }) + .click(); + await page.waitForFunction( + () => + !window.testAudio.paused && + window.testAudio.currentTime >= 23 && + window.testAudio.currentSrc.startsWith("blob:"), + ); + await page + .getByRole("slider", { name: "Playback position" }) + .filter({ visible: true }) + .evaluate((input) => { + input.value = "35"; + input.dispatchEvent(new Event("input", { bubbles: true })); + }); + await page.waitForFunction(() => window.testAudio.currentTime >= 35); + // A native pause models foreground interruption only, not iOS/OS integration. + await page.evaluate(() => window.testAudio.pause()); + await page + .locator(".mini-player") + .getByRole("button", { name: "Play", exact: true }) + .click(); + await page.waitForFunction(() => !window.testAudio.paused); + assert.equal(requests, before, "cached seek/reload/retry must not contact the server"); + await page.context().setOffline(false); + await page + .locator(".mini-player") + .getByRole("button", { name: "Pause", exact: true }) + .click(); + await page + .locator(".app-sidebar") + .getByRole("button", { name: "Connect", exact: true }) + .click(); + await page + .locator(".app-sidebar") + .getByRole("button", { name: "Work offline", exact: true }) + .waitFor(); + }, + ); + await t.test("unchecked disconnect retains cached playback and offline downloads", async () => { await navigate("/library"); await playCached(); diff --git a/tests/browser/pwa-updates.test.cjs b/tests/browser/pwa-updates.test.cjs index e4ca6b8..eb257c3 100644 --- a/tests/browser/pwa-updates.test.cjs +++ b/tests/browser/pwa-updates.test.cjs @@ -11,7 +11,9 @@ const { setTimeout: pollDelay } = require("node:timers/promises"); const { chromium } = require("playwright"); const root = path.resolve(__dirname, "../.."); -const route = "/webapp/?/settings#settings-heading"; +// First-run documents now start on Connect; use a route that survives reload +// without requiring remembered credentials or a persistent account fixture. +const route = "/webapp/?/connect#connection-help"; const action = (page) => page.locator(".app-sidebar").getByRole("button", { name: "Update Libras", exact: true }); const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex"); @@ -172,7 +174,7 @@ async function loaded(page, marker) { (expected) => document.querySelector('meta[name="pwa-test-build"]')?.content === expected, marker, ); - await page.locator("#settings-heading").waitFor(); + await page.locator(".app-sidebar").waitFor(); } async function identity(page) { @@ -308,7 +310,7 @@ test("production PWA updates on one origin", { timeout: 240_000 }, async (t) => const harness = await newPage(context); pages.push(harness); await harness.page.goto(server.origin + route); - await harness.page.locator("#settings-heading").waitFor(); + await harness.page.locator(".app-sidebar").waitFor(); await controlled(harness.page); return harness; }; @@ -364,6 +366,105 @@ test("production PWA updates on one origin", { timeout: 240_000 }, async (t) => assert.equal(log.navigations.length, 1); }); + await scenario( + "approved update preserves local queue/resume without autoplay", + async ({ open, t }) => { + const h = await open(); + const { page } = h; + const artist = { id: "artist", name: "Update artist" }; + const album = { id: "album", name: "Update album", artists: [artist] }; + const song = { + id: "song", + title: "Update song", + albumId: album.id, + artists: [artist], + duration: 60, + }; + const exchanges = []; + await page.route("https://music.example.test/rest/**", async (request) => { + const url = new URL(request.request().url()); + const method = url.pathname.split("/").pop().replace(".view", ""); + let fields = {}; + if (method === "ping") + fields = { + openSubsonic: true, + version: "1.16.1", + type: "test-server", + serverVersion: "1", + }; + else if (method === "getIndexes") fields = { indexes: { lastModified: 1 } }; + else if (method === "getPlaylists") fields = { playlists: { playlist: [] } }; + else if (method === "search3") { + const slice = (values, name) => + values.slice( + Number(url.searchParams.get(`${name}Offset`) ?? 0), + Number(url.searchParams.get(`${name}Offset`) ?? 0) + + Number(url.searchParams.get(`${name}Count`) ?? 500), + ); + fields = { + searchResult3: { + artist: slice([artist], "artist"), + album: slice([album], "album"), + song: slice([song], "song"), + }, + }; + } else if (method === "getPlayQueue") { + exchanges.push(method); + fields = { + playQueue: { + entry: [song, { id: "missing" }, song], + current: song.id, + position: 23000, + }, + }; + } else throw new Error(`Unexpected endpoint: ${method}`); + await request.fulfill({ + contentType: "application/json", + body: JSON.stringify({ "subsonic-response": { status: "ok", ...fields } }), + }); + }); + await page.getByLabel("Host", { exact: true }).fill("https://music.example.test"); + await page.getByLabel("Username", { exact: true }).fill("listener"); + await page.getByLabel("Password", { exact: true }).fill("fictional-password"); + await page.getByRole("button", { name: "Connect", exact: true }).click(); + await page.getByRole("radio", { name: "All music", exact: true }).check(); + await page.getByRole("link", { name: artist.name, exact: true }).waitFor(); + await page.getByRole("button", { name: "Queue", exact: true }).click(); + const player = page.locator("#player-dialog"); + await player.getByRole("button", { name: "Load server queue", exact: true }).click(); + await page + .getByRole("dialog", { name: "Replace this device’s queue?", exact: true }) + .getByRole("button", { name: "Load server queue", exact: true }) + .click(); + await player.getByRole("status").filter({ hasText: "Server queue loaded" }).waitFor(); + const labels = await player.locator(".track-row .label").allTextContents(); + await page.getByRole("button", { name: "Close player", exact: true }).click(); + await page.getByRole("link", { name: "Settings", exact: true }).click(); + const original = await identity(page); + server.select(builds.C); + await checkForUpdate(page); + await waiting(page); + assert.deepEqual( + await identity(page), + original, + "waiting update must not reload without approval", + ); + await approve(h, "C", t); + await page.getByRole("button", { name: "Queue", exact: true }).click(); + assert.deepEqual(await player.locator(".track-row .label").allTextContents(), labels); + assert.equal( + await player.getByRole("slider", { name: "Playback position" }).inputValue(), + "23", + ); + assert.equal(await player.getByRole("button", { name: "Pause", exact: true }).count(), 0); + assert.deepEqual( + exchanges, + ["getPlayQueue"], + "update/reload must not exchange server queues", + ); + }, + ); + await scenario( "old-plugin A upgrades to native B without storage clearing", async ({ open, t }) => {