fix: resolve six WebKit Playwright regressions (task-339)

- Make tauriInvoke lazy: remove eager export const invoke capture,
  look up window.__TAURI__?.core?.invoke at call time so test stubs
  injected after page.goto() are picked up
- Add waitForLibraryReady helper (helpers.js): waits on
  Alpine.store('library').totalTracks > 0 then [data-track-id] attached,
  avoiding the intermittent WebKit visibility timeout
- Switch accessibility.spec.js ARIA Labels beforeEach to use
  waitForLibraryReady instead of waitForSelector visible
- Fix library-browser.spec.js column header selector
  (.column-header matched nothing; use [data-testid="library-header"]
  span.truncate) and correct Duration -> Time column label; add
  assertions for always-visible columns # and Title
- Regenerate stale WebKit visual baselines: context-menu-track (two
  new items), library-view-list, library-view-list-selected
- Update docs/testing.md: correct fast-mode test count (~650 -> ~566),
  document helpers.js functions with waitForLibraryReady callout

Author: pythoninthegrass

app/frontend/js/api/shared.js

@@ -2,14 +2,11 @@
  * Shared API utilities
  *
  * Common infrastructure used by all domain API modules:
- * ApiError class, HTTP request helper, and Tauri invoke reference.
+ * ApiError class, HTTP request helper, and Tauri invoke wrapper.
  */
 
 const API_BASE = 'http://127.0.0.1:8765/api';
 
-// Get Tauri invoke function if available
-export const invoke = window.__TAURI__?.core?.invoke;
-
 /**
  * Custom API error class
  */
@@ -65,6 +62,7 @@ export async function request(endpoint, options = {}) {
  * @returns {Promise<any>} Command result
  */
 export async function tauriInvoke(cmd, params = {}) {
+  const invoke = window.__TAURI__?.core?.invoke;
   if (!invoke) return null;
   try {
     return await invoke(cmd, params);

app/frontend/tests/accessibility.spec.js

@@ -1,5 +1,5 @@
 import { test, expect } from '@playwright/test';
-import { waitForAlpine } from './fixtures/helpers.js';
+import { waitForAlpine, waitForLibraryReady } from './fixtures/helpers.js';
 import { createLibraryState, setupLibraryMocks } from './fixtures/mock-library.js';
 import { createPlaylistState, setupPlaylistMocks } from './fixtures/mock-playlists.js';
 
@@ -25,7 +25,7 @@ test.describe('Accessibility: ARIA Labels', () => {
 
     await page.goto('/');
     await waitForAlpine(page);
-    await page.waitForSelector('[data-track-id]', { state: 'visible' });
+    await waitForLibraryReady(page);
   });
 
   test.describe('Player Controls', () => {

app/frontend/tests/fixtures/helpers.js

@@ -172,3 +172,15 @@ export async function getQueueItems(page) {
   return queueStore.items;
 }
 
+/**
+ * Wait for the library store to have tracks and a track row to be attached
+ * @param {import('@playwright/test').Page} page
+ */
+export async function waitForLibraryReady(page) {
+  await page.waitForFunction(() => {
+    const lib = window.Alpine?.store?.('library');
+    return lib && lib.totalTracks > 0;
+  });
+  await page.waitForSelector('[data-track-id]', { state: 'attached' });
+}
+

app/frontend/tests/library-browser.spec.js

@@ -25,17 +25,19 @@ test.describe('Library Browser', () => {
   test('should display track metadata columns', async ({ page }) => {
     await page.waitForSelector('[data-track-id]', { state: 'visible' });
 
-    // Verify column headers are present
-    const headers = page.locator('.column-header, [class*="sort-header"]');
+    // Verify column headers are present — header cells render as span.truncate inside library-header
+    const headers = page.locator('[data-testid="library-header"] span.truncate');
     const headerTexts = await headers.allTextContents();
 
-    // Should have at least these columns
-    const expectedColumns = ['#', 'Title', 'Artist', 'Album', 'Duration'];
-    expectedColumns.forEach((col) => {
-      const hasColumn = headerTexts.some((text) => text.includes(col));
-      if (!hasColumn) {
-        // Column might be represented differently, check track data instead
-        console.log(`Column "${col}" not found in headers, but may be present in rows`);
+    // Always-visible columns (canHide: false)
+    expect(headerTexts).toContain('#');
+    expect(headerTexts).toContain('Title');
+
+    // Hideable columns — present by default but may be toggled off
+    const hideableColumns = ['Artist', 'Album', 'Time'];
+    hideableColumns.forEach((col) => {
+      if (!headerTexts.some((text) => text.includes(col))) {
+        console.log(`Column "${col}" not visible (may be hidden via column settings)`);
       }
     });
   });

backlog/tasks/task-339 - Fix-six-WebKit-Playwright-regressions-lazy-tauriInvoke-library-ready-wait-stale-visual-baselines.md

@@ -0,0 +1,136 @@
+---
+id: TASK-339
+title: >-
+  Fix six WebKit Playwright regressions: lazy tauriInvoke, library-ready wait,
+  stale visual baselines
+status: Done
+assignee: []
+created_date: '2026-04-29 20:59'
+updated_date: '2026-04-30 19:06'
+labels:
+  - bug
+  - tests
+  - webkit
+  - regression
+dependencies: []
+references:
+  - app/frontend/js/api/shared.js
+  - app/frontend/js/components/settings-view.js
+  - app/frontend/tests/accessibility.spec.js
+  - app/frontend/tests/settings.spec.js
+  - app/frontend/tests/visual-regression.spec.js
+  - app/frontend/tests/fixtures/helpers.js
+  - app/frontend/views/library.html
+  - app/frontend/js/mixins/context-menu-actions.js
+priority: high
+ordinal: 2750
+---
+
+## Description
+
+<!-- SECTION:DESCRIPTION:BEGIN -->
+Six WebKit Playwright tests are failing. They split into three distinct root causes — fix each.
+
+## Failure 1 — `accessibility.spec.js:48` › "previous button has accessible name"
+
+`beforeEach` at line 28 times out on `await page.waitForSelector('[data-track-id]', { state: 'visible' })`. Playwright finds 44 elements but the first one isn't deemed visible (intermittent on WebKit only). The test itself only inspects `[data-testid="player-prev"]` — it doesn't actually need a track row laid out, only the library data to have arrived.
+
+## Failures 2 & 3 — `settings.spec.js:718, 839` › Log Export tests
+
+Same root cause for both: `app/frontend/js/api/shared.js:11` captures `invoke` at module-load time:
+```js
+export const invoke = window.__TAURI__?.core?.invoke;
+```
+Tests stub `window.__TAURI__` *after* `page.goto('/')`, so the cached `invoke` reference is permanently `undefined`. `tauriInvoke()` short-circuits to `null` and the test's `core.invoke` mock is never called.
+
+Result for test 2 ("loading state"): success path runs synchronously (no 500 ms delay) — `isExportingLogs` flips false within one microtask, so `toBeDisabled()` never observes the disabled state.
+
+Result for test 3 ("error toast"): the failure-injecting mock is dead code; `tauriInvoke` returns `null`, success toast `'Diagnostics exported successfully'` is shown instead of `'Failed to export diagnostics'`.
+
+This regression was introduced by commit `4ba8be8` (gnhf #3 / tauriInvoke extraction). `tauriConfirm` two functions down already does the right thing (lazy lookup); `tauriInvoke` should match.
+
+`exportLogs()` is at `app/frontend/js/components/settings-view.js:403-431` and uses `tauriInvoke('export_diagnostics', ...)`. The toast string at line 427 is exactly `'Failed to export diagnostics'` — no mismatch there.
+
+## Failures 4, 5, 6 — `visual-regression.spec.js:59, 70, 126`
+
+Stale local visual baselines. Snapshots at `app/frontend/tests/visual-regression.spec.js-snapshots/` are `.gitignore`d (per-developer) and the suite is `test.skip`-ped under `CI=true` (see `visual-regression.spec.js:7-8`).
+
+- **`context-menu-track.png` (test 6):** baseline is 331 px tall, current render is 405 px. The 74 px delta = exactly two new menu items at ~37 px each. Items added by intentional commits `83e6cdc` ("Go to Artist") and `e93eaba` ("Go to Album") in `app/frontend/js/mixins/context-menu-actions.js:108-116`.
+- **`library-view-list*.png` (tests 4, 5):** ~3% pixel diff (~27,700 px). The paginated-loading rewrite (`cb6876d`) and FOUC fix (`f8f2e1c`) added a `transform: translateY(...)` virtual-scroll wrapper at `app/frontend/views/library.html:207`; consistent with subpixel AA shifts on transformed text across many rows.
+
+These are intentional UI changes, not regressions — baselines just need to be regenerated locally.
+
+## Critical files
+
+- `app/frontend/js/api/shared.js` — line 11 export and `tauriInvoke` body at lines 67-75
+- `app/frontend/tests/fixtures/helpers.js` — append a `waitForLibraryReady` helper
+- `app/frontend/tests/accessibility.spec.js` — line 2 import, line 28 wait
+- `app/frontend/tests/visual-regression.spec.js-snapshots/*-webkit-darwin.png` — regenerate
+
+## Recommended fixes
+
+### Fix A — Make `tauriInvoke` lazy (resolves tests 2 & 3)
+
+In `app/frontend/js/api/shared.js`:
+- Drop the `export const invoke = window.__TAURI__?.core?.invoke;` line. Verified via grep that nothing imports it directly: `player.js` does its own `window.__TAURI__?.core` destructure; everything else goes through `tauriInvoke`.
+- Inline the lookup inside `tauriInvoke`:
+  ```js
+  export async function tauriInvoke(cmd, params = {}) {
+    const invoke = window.__TAURI__?.core?.invoke;
+    if (!invoke) return null;
+    try {
+      return await invoke(cmd, params);
+    } catch (error) {
+      console.error(`[api.tauriInvoke] Tauri error (${cmd}):`, error);
+      throw new ApiError(500, error.toString());
+    }
+  }
+  ```
+
+### Fix B — Wait on library-ready signal, not DOM visibility (resolves test 1)
+
+In `app/frontend/tests/fixtures/helpers.js`, append:
+```js
+export async function waitForLibraryReady(page) {
+  await page.waitForFunction(() => {
+    const lib = window.Alpine?.store?.('library');
+    return lib && lib.totalTracks > 0;
+  });
+  await page.waitForSelector('[data-track-id]', { state: 'attached' });
+}
+```
+
+In `app/frontend/tests/accessibility.spec.js`:
+- Import `waitForLibraryReady` alongside `waitForAlpine` (line 2).
+- Replace line 28 `await page.waitForSelector('[data-track-id]', { state: 'visible' });` with `await waitForLibraryReady(page);`.
+
+Leave `visual-regression.spec.js:50` alone — those tests legitimately need rows visually laid out before screenshotting.
+
+### Fix C — Refresh local visual baselines (resolves tests 4, 5, 6)
+
+After Fix A lands, regenerate the WebKit baselines:
+```bash
+cd app/frontend && npx playwright test visual-regression.spec.js --update-snapshots --project=webkit
+```
+Spot-check the regenerated PNGs:
+- `context-menu-track-webkit-darwin.png` shows the full menu including "Go to Artist" and "Go to Album"
+- `library-view-list*-webkit-darwin.png` show the current paginated-list layout
+Anything else odd in the screenshots is a separate regression to investigate.
+
+## Out of scope
+
+- Do NOT change `player.js` Tauri destructure — it has its own no-op fallback and isn't broken by tests.
+- Do NOT touch `visual-regression.spec.js:50` — only the failing assertions are downstream of that wait.
+- Don't try to make the WebKit subpixel AA diff disappear by removing the virtual-scroll transform — the transform is load-bearing for performance.
+<!-- SECTION:DESCRIPTION:END -->
+
+## Acceptance Criteria
+<!-- AC:BEGIN -->
+- [x] #1 `tauriInvoke` in `app/frontend/js/api/shared.js` looks up `window.__TAURI__?.core?.invoke` at call time, not at module load
+- [x] #2 The unused `export const invoke = ...` declaration in `shared.js` is removed
+- [x] #3 `waitForLibraryReady(page)` helper exists in `app/frontend/tests/fixtures/helpers.js` and waits on `Alpine.store('library').totalTracks > 0` then `[data-track-id]` attached
+- [x] #4 `accessibility.spec.js` `beforeEach` uses `waitForLibraryReady` instead of waiting for `[data-track-id]` visibility
+- [x] #5 Local WebKit visual baselines regenerated for `context-menu-track`, `library-view-list`, and `library-view-list-selected`
+- [x] #6 `npx playwright test --project=webkit accessibility.spec.js settings.spec.js visual-regression.spec.js` passes for the six previously-failing tests
+- [x] #7 No new test failures introduced in `settings.spec.js` or `accessibility.spec.js` (run the full files on webkit to confirm)
+<!-- AC:END -->

docs/testing.md

@@ -10,7 +10,7 @@ MT uses a three-tier testing strategy:
 |-------|-----------|-------|---------|
 | **Rust Backend** | `cargo test` | ~596 | Unit tests for audio, database, and IPC logic |
 | **Vitest Unit** | Vitest | ~391 | Frontend store logic, property-based tests |
-| **Playwright E2E** | Playwright | ~650 | Integration and end-to-end user flows |
+| **Playwright E2E** | Playwright | ~566 | Integration and end-to-end user flows |
 
 ## Running Tests
 
@@ -97,7 +97,7 @@ Tests are controlled by the `E2E_MODE` environment variable:
 
 | Mode | Browsers | @tauri tests | Tests | Duration |
 |------|----------|--------------|-------|----------|
-| `fast` (default) | WebKit only | Skipped | ~650 | ~1m |
+| `fast` (default) | WebKit only | Skipped | ~566 | ~1.5m |
 | `full` | All 3 | Skipped | ~1950 | ~3m |
 | `tauri` | All 3 | Included | ~2000+ | ~4m |
 
@@ -141,6 +141,14 @@ Available fixtures:
 - `mock-library.js`: Library API (`/api/library`, track CRUD)
 - `mock-playlists.js`: Playlist API (`/api/playlists`, playlist CRUD)
 
+Available helpers (`fixtures/helpers.js`):
+
+- `waitForAlpine(page)` — wait for Alpine to initialise
+- `waitForLibraryReady(page)` — wait for `Alpine.store('library').totalTracks > 0`, then `[data-track-id]` attached; use this instead of `waitForSelector('[data-track-id]', { state: 'visible' })` to avoid intermittent WebKit timeouts
+- `getAlpineStore(page, name)` / `setAlpineStoreProperty` / `callAlpineStoreMethod` — read or mutate Alpine store state
+- `waitForPlaying(page)` / `waitForPaused(page)` — player state helpers
+- `clickTrackRow(page, index)` / `doubleClickTrackRow(page, index)` — interact with track rows
+
 ---
 
 ## Where to Write New Tests