Make LibrariesScreen scan-complete test deterministic (stop racing real microtasks under waitFor) #512

Closed
opened 2026-07-20 22:57:25 +02:00 by timothy · 2 comments
Owner

Problem

web/src/screens/LibrariesScreen.test.tsx → "stops scan polling and refreshes sources once when scans complete" (line ~254) is CI-load-flaky. It mocks setInterval and manually fires the poll tick via runPollTick, but loadScanStatuses kicks off a Promise.all(...).then(...) chain that resolves on real microtasks outside the act() callback. The test therefore relies on two waitFor(..., { timeout: 5000 }) calls to let the progress bar clear and the follow-up loadSources() refetch land.

That is fine locally (the file runs in ~0.2s), but under a starved CI VM the whole test environment slows ~200× and the 5s budget is marginal. It timed out on PR #509 / run 918 — a CI-config + docs-only diff that cannot touch this screen — where the vitest summary showed environment 49.30s / import 16.42s. A single job rerun (undivided lane) passed. The test's own comments already document prior hardening attempts (#447, run 686), so bumping timeouts further is diminishing whack-a-mole.

Proposed fix

Remove the real-microtask dependence rather than out-wait it:

  • Drive the poll chain's promises to completion deterministically (await the same promise the handler starts, or vi.useFakeTimers() + await vi.runAllTimersAsync() / flush the microtask queue) so the progress-clear and loadSources() refetch are observed synchronously after the tick — no waitFor race.
  • Keep the existing assertions (progress label gone, exactly one extra /api/v1/media-sources fetch).

Notes

  • Low priority: #508 + server-management#639 attack this flake's root cause — the small-lane starvation that made CI VMs pathologically slow — so its frequency should drop even without this change. This is test-robustness hygiene, not a live bug.
  • Root cause of the flake is the test harness, not the component: LibrariesScreen behaves correctly; the test just observes an inherently-async chain without deterministically flushing it.

Done-when

  • The scan-complete test no longer depends on waitFor wall-clock timeouts to observe the poll chain
  • Test passes reliably (verify with a repeated-run loop locally)
  • adversarial review passed
## Problem `web/src/screens/LibrariesScreen.test.tsx` → *"stops scan polling and refreshes sources once when scans complete"* (line ~254) is CI-load-flaky. It mocks `setInterval` and manually fires the poll tick via `runPollTick`, but `loadScanStatuses` kicks off a `Promise.all(...).then(...)` chain that resolves on **real microtasks** outside the `act()` callback. The test therefore relies on two `waitFor(..., { timeout: 5000 })` calls to let the progress bar clear and the follow-up `loadSources()` refetch land. That is fine locally (the file runs in ~0.2s), but under a starved CI VM the whole test environment slows ~200× and the 5s budget is marginal. It timed out on **PR #509 / run 918** — a CI-config + docs-only diff that cannot touch this screen — where the vitest summary showed `environment 49.30s` / `import 16.42s`. A single job rerun (undivided lane) passed. The test's own comments already document prior hardening attempts (#447, run 686), so bumping timeouts further is diminishing whack-a-mole. ## Proposed fix Remove the real-microtask dependence rather than out-wait it: - Drive the poll chain's promises to completion deterministically (await the same promise the handler starts, or `vi.useFakeTimers()` + `await vi.runAllTimersAsync()` / flush the microtask queue) so the progress-clear and `loadSources()` refetch are observed synchronously after the tick — no `waitFor` race. - Keep the existing assertions (progress label gone, exactly one extra `/api/v1/media-sources` fetch). ## Notes - **Low priority**: #508 + server-management#639 attack this flake's *root cause* — the `small`-lane starvation that made CI VMs pathologically slow — so its frequency should drop even without this change. This is test-robustness hygiene, not a live bug. - Root cause of the flake is the test harness, not the component: `LibrariesScreen` behaves correctly; the test just observes an inherently-async chain without deterministically flushing it. ## Done-when - [x] The scan-complete test no longer depends on `waitFor` wall-clock timeouts to observe the poll chain - [x] Test passes reliably (verify with a repeated-run loop locally) - [x] adversarial review passed
timothy added the ci-cdpriority: low labels 2026-07-20 22:57:25 +02:00
timothy added the in-progress label 2026-07-22 16:57:37 +02:00
Author
Owner

Claiming, bundled with #553 this session (both small, independent ci-cd/test hygiene fixes). Approach: make the scan-complete poll chain flush deterministically (drive the promises the handler starts to completion / fake-timers runAllTimersAsync) instead of out-waiting real microtasks with waitFor timeouts.

Claiming, bundled with #553 this session (both small, independent ci-cd/test hygiene fixes). Approach: make the scan-complete poll chain flush deterministically (drive the promises the handler starts to completion / fake-timers `runAllTimersAsync`) instead of out-waiting real microtasks with `waitFor` timeouts.
Author
Owner

Closing record

Outcome: Shipped via PR #558 (merged to main). LibrariesScreen.test.tsx's "stops scan polling…" test no longer depends on waitFor wall-clock timeouts. runPollTick now, inside act(async …), awaits the promises the interval handler returns and then drains one setTimeout(0) macrotask — so the progress-clear setState and the fire-and-forget loadSources() refetch have both settled before the assertions run.
Root cause: Test harness, not the component. The old test discarded the promise loadScanStatuses returns, so its Promise.all(...).then(...) chain (progress-clear + a fire-and-forget loadSources() refetch that isn't part of the returned promise) resolved on real microtasks after act() had already resolved. The two waitFor({ timeout: 5000 }) calls out-waited that race — fine locally (~0.2s) but marginal on a starved CI VM (~200× slower), so it flaked on PR #509/run 918. LibrariesScreen itself was always correct.
Decisions/conventions changed: None. Reinforces the existing spa-conventions.md §9 temporal-semantics rule (flush async chains deterministically; never observe an inherently-async chain by out-waiting it).
Reusable knowledge: A single await new Promise(r => setTimeout(r, 0)) after awaiting the handler's own promise deterministically drains the entire microtask queue (incl. transitively-scheduled fire-and-forget chains) — by spec a macrotask runs only after all microtasks settle — provided setTimeout is left un-mocked (here only setInterval was mocked). Assertions preserved verbatim (progress 75% gone; exactly one extra /media-sources fetch).
Verification: LibrariesScreen suite green 15/15 consecutive runs; npm run lint + npm run build clean; no production code changed. Cold-read adversarial review of the diff (pure web-test leaf → cross-model review skipped per process.independent-review-rubric, stated). CI green after the ci-runner .127 disk fix (server-management#654).
Deferred: None. (#508 + server-management#639 separately attack the underlying small-lane starvation that made the VM slow enough to expose this.)
Docs updated: None required — a test-determinism fix touching one test file, no convention/route/endpoint/decision change.

## Closing record **Outcome:** Shipped via PR #558 (merged to `main`). `LibrariesScreen.test.tsx`'s "stops scan polling…" test no longer depends on `waitFor` wall-clock timeouts. `runPollTick` now, inside `act(async …)`, awaits the promises the interval handler returns and then drains one `setTimeout(0)` macrotask — so the progress-clear `setState` and the fire-and-forget `loadSources()` refetch have both settled before the assertions run. **Root cause:** Test harness, not the component. The old test discarded the promise `loadScanStatuses` returns, so its `Promise.all(...).then(...)` chain (progress-clear + a fire-and-forget `loadSources()` refetch that isn't part of the returned promise) resolved on real microtasks *after* `act()` had already resolved. The two `waitFor({ timeout: 5000 })` calls out-waited that race — fine locally (~0.2s) but marginal on a starved CI VM (~200× slower), so it flaked on PR #509/run 918. `LibrariesScreen` itself was always correct. **Decisions/conventions changed:** None. Reinforces the existing `spa-conventions.md` §9 temporal-semantics rule (flush async chains deterministically; never observe an inherently-async chain by out-waiting it). **Reusable knowledge:** A single `await new Promise(r => setTimeout(r, 0))` after awaiting the handler's own promise deterministically drains the *entire* microtask queue (incl. transitively-scheduled fire-and-forget chains) — by spec a macrotask runs only after all microtasks settle — provided `setTimeout` is left un-mocked (here only `setInterval` was mocked). Assertions preserved verbatim (progress `75%` gone; exactly one extra `/media-sources` fetch). **Verification:** `LibrariesScreen` suite green **15/15 consecutive runs**; `npm run lint` + `npm run build` clean; no production code changed. Cold-read adversarial review of the diff (pure web-test leaf → cross-model review skipped per `process.independent-review-rubric`, stated). CI green after the ci-runner .127 disk fix (server-management#654). **Deferred:** None. (#508 + server-management#639 separately attack the underlying `small`-lane starvation that made the VM slow enough to expose this.) **Docs updated:** None required — a test-determinism fix touching one test file, no convention/route/endpoint/decision change.
timothy removed the in-progress label 2026-07-22 18:02:59 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#512