Test Harness Workarounds

The suite carries a handful of shims that exist for one reason each: something the runner, its DOM, or a module does not implement. None of them is a design decision — they are the cost of running today's tests on today's tools, and every one is meant to be deleted rather than maintained.

The failure mode they share is silence. A shim whose cause is gone still passes: the stub is installed, nothing reads it, and no assertion notices. So a shim outlives its bug unless something tracks it, and the thing tracking it is this page — one row per shim, whatever else also lists it (an @TODO waiting on an unfiled issue is in the todos skill's list only so it gets filed, and is a row here too), each with the probe that decides whether it is still needed and the code its removal deletes. A row leaves when its probe passes and the suites that leaned on the shim stay green without it.

Every row's third column is written so nobody re-derives the reasoning: it names the probe and the signature that means the shim is still earning its place. Running the probe and comparing against that signature is the whole check — an error string, an absent global, a failing suite. A row whose probe cannot be run at all says so, because an unrunnable probe is a finding rather than a pass.

The blocker table

How a retirement runs

A row is not removed because a release note claims the gap is closed. It is removed when the shim is gone and the suites that leaned on it still pass, which is why every row carries a probe rather than a version alone.

flowchart LR
  B["Dependency bump lands"] --> P{"Probe passes"}
  P -->|no| K["Row stays untouched"]
  P -->|yes| D["Delete the shim"]
  D --> T{"Dependent suites green"}
  T -->|no| R["Restore it, correct the row's gap"]
  T -->|yes| X["Delete the row"]

The probes are cheap enough to run on the bump that plausibly moves one, so nothing here earns a scheduled pass of its own: the dependency update process owns the bumps, and a row whose dependency has not moved cannot have changed.

Two things the first pass through this table settled are worth stating, because both are the reason a row's signature is written down rather than reasoned out again. A shim can be half dead: sessionStorage reached the global perfectly well while localStorage never did, so half the storage shim was overwriting a working implementation. And a shim can outlive its bug in the runtime rather than in the library — happy-dom fires image load events and reports a readyState Phaser accepts, so the two spies that forced both were deleted while the canvas mock beside them stayed load-bearing. Neither was visible from the code; both took one probe.

What is not on this list

Not every piece of test scaffolding is a workaround, and treating them alike would make the table unfalsifiable:

• The harness itself — the in-memory Azure clients, the PGlite database, the session mock. They stand in for services that have no business running inside a unit test, and no upstream release retires them.
• Deliberate narrowing — toFake: ["Date"] fakes less than the default on purpose, because the wide default also freezes the monotonic clock a table write's rowKey depends on. That is a rule, not a gap.
• An origin nothing answers — the nuxt environment runs on http://nuxt.test, a .test host that never resolves, rather than Nuxt's default localhost:3000. It is a rule rather than a gap: msw intercepts beneath happy-dom's fetch, and a request it misses goes out to the real network, where the default origin is exactly where a developer's dev server listens — so a suite answered by the real router failed only while one was running, and passed the moment it was stopped or instrumented. On this origin a missed request fails at once with fetch failed, whatever the cause of the miss, and apps/web/vitest.config.test.ts pins that it does.
• Language ergonomics — takeOne exists for noUncheckedIndexedAccess across the whole repo, not for tests.

Key files