Skip to content

Commit 5834cd2

Browse files
cliffhallclaude
andcommitted
test(web): address review — export settleTransitions, derive settle from HEADER_ANIM_MS, guard fake timers, correct comments
Review feedback on PR #1793: 1. Derive the settle window from the real animation duration: export `HEADER_ANIM_MS` from ViewHeader.tsx and compute `TRANSITION_SETTLE_MS = HEADER_ANIM_MS + 200` in the test, so bumping the header duration can't silently make the settle insufficient (the invariant is now structural, not a comment). 2. Move `settleTransitions` into the shared `renderWithMantine.tsx` helper (exported, optional `ms` arg) next to `renderWithMantineTransitions`, since AGENTS.md points every future caller at it — shared test scaffolding belongs in src/test/, not a single test file. AGENTS.md now references the helper. 3. Guard `settleTransitions` against `vi.useFakeTimers()`: it awaits a real setTimeout, so under fake timers it would hang to the test timeout. Throw a clear message instead. 4. Correct the diagnosis comments: the hazard isn't a Mantine timer surviving unmount (its effect cleanup cancels timers) — it's the React state update Mantine's inner rAF schedules outside `act`, resolving post-teardown. Also fix the stale setup.ts matchMedia comment: the reduce-motion stub does not disable transitions (Mantine defaults respectReducedMotion=false); env="test" is the actual #1760 protection. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
1 parent 13caa11 commit 5834cd2

5 files changed

Lines changed: 62 additions & 37 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ gh project item-edit --project-id PVT_kwDOCt2Azc4BJVxt --id "$ITEM_ID" --field-i
205205
- **Test placement: side-by-side by default, `src/test/` only for what can't be co-located.** These look like competing conventions but aren't — the split is: *tests live beside their source, **except** tests for the repo-root `core/` package (which lives outside `clients/web/`) and shared test scaffolding — both of which live under `src/test/`, with `core/` tests mirroring the `core/` layout and integration tests under `src/test/integration/`.*
206206
- **Side-by-side (`<Name>.test.tsx` next to the source) — the default for web's own `src/` code.** Components, hooks, `lib/`, `utils/`. This is the overwhelming majority; a web-owned test living under `src/test/` instead of beside its source is a bug (fixed one such straggler, `downloadFile.test.ts`, in #1776).
207207
- **`src/test/` — the three things that *cannot* be co-located:** (1) tests of the repo-root **`core/`** package (`src/test/core/…`, mirroring the `core/` folder layout — `core/` physically lives at `/core` outside `clients/web/`, is consumed via the `@inspector/core` alias, and has no test harness of its own, so co-locating would pollute the shared isomorphic package with web-only test infra); (2) the **`integration`** vitest project (`src/test/integration/…`, node env, 30s — placement *is* the manifest, see above); (3) **shared test infrastructure** (`renderWithMantine.tsx`, `setup.ts`, `fixtures/`, `scrollAreaStoryAssertions.ts`) — not tests *of* a source file, so nothing to sit beside.
208-
- Use `renderWithMantine` from `src/test/renderWithMantine.tsx` to render components — it wraps in `MantineProvider` with the project theme. It sets `env="test"` so Mantine renders transitions synchronously (no internal `setTimeout`); this prevents a `Transition`/`Modal` timer from firing after happy-dom tears down `window` at end-of-run and failing the whole run with an uncaught `ReferenceError: window is not defined` (#1760). **Always render through `renderWithMantine`; do not hand-roll a bare `MantineProvider` in a test** (that reintroduces the leak class). To exercise a **forced color scheme** (e.g. the `useComputedColorScheme` dark branch) pass the `colorScheme` option — `renderWithMantine(ui, { colorScheme: "dark" })` — instead of hand-rolling a `defaultColorScheme="dark"` provider (#1786). Only when a test must assert *mid-flight* transition state (e.g. a `data-anim="out"` cell during an exit crossfade) use `renderWithMantineTransitions` (real transitions) — and that test MUST drive **every** transition it opens to completion so no rAF→`setTimeout` chain is still pending at teardown, else it reintroduces the #1760 leak. Waiting for one cell to unmount does **not** settle a concurrent *enter* (a completed enter leaves no DOM signal to `waitFor`); flush any such straggler against the still-mounted tree before the test ends (see `settleTransitions` in `ViewHeader.test.tsx`, #1786).
208+
- Use `renderWithMantine` from `src/test/renderWithMantine.tsx` to render components — it wraps in `MantineProvider` with the project theme. It sets `env="test"` so Mantine renders transitions synchronously (no internal `setTimeout`); this prevents a `Transition`/`Modal` timer from firing after happy-dom tears down `window` at end-of-run and failing the whole run with an uncaught `ReferenceError: window is not defined` (#1760). **Always render through `renderWithMantine`; do not hand-roll a bare `MantineProvider` in a test** (that reintroduces the leak class). To exercise a **forced color scheme** (e.g. the `useComputedColorScheme` dark branch) pass the `colorScheme` option — `renderWithMantine(ui, { colorScheme: "dark" })` — instead of hand-rolling a `defaultColorScheme="dark"` provider (#1786). Only when a test must assert *mid-flight* transition state (e.g. a `data-anim="out"` cell during an exit crossfade) use `renderWithMantineTransitions` (real transitions) — and that test MUST drive **every** transition it opens to completion so no rAF→`setTimeout` chain is still pending at teardown, else it reintroduces the #1760 leak. Waiting for one cell to unmount does **not** settle a concurrent *enter* (a completed enter leaves no DOM signal to `waitFor`); flush any such straggler against the still-mounted tree before the test ends by calling the exported `settleTransitions(ms)` helper from `renderWithMantine.tsx` (#1786 — it awaits a real timer inside `act`, so it must not be called under `vi.useFakeTimers()`).
209209

210210
### Responding to Code Reviews
211211
- When asked to respond to a code review of a PR,

‎clients/web/src/components/groups/ViewHeader/ViewHeader.test.tsx‎

Lines changed: 12 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -5,29 +5,19 @@ import {
55
renderWithMantine,
66
renderWithMantineTransitions,
77
screen,
8+
settleTransitions,
89
waitFor,
910
} from "../../../test/renderWithMantine";
10-
import { ViewHeader } from "./ViewHeader";
11-
12-
// The header Transitions run for HEADER_ANIM_MS (300ms); this exceeds that plus
13-
// the two-frame rAF scheduling slack so a real-timer transition is guaranteed
14-
// to have reached its terminal ("entered"/"exited") state after the wait.
15-
const TRANSITION_SETTLE_MS = 500;
11+
import { HEADER_ANIM_MS, ViewHeader } from "./ViewHeader";
1612

1713
// The `renderWithMantineTransitions` tests use real (env="default") Mantine
18-
// transitions to observe mid-flight "in"/"out" cells. A `Transition` schedules a
19-
// rAF→`setTimeout` chain; a straggler that fires after happy-dom tears down
20-
// `window` throws `ReferenceError: window is not defined` from react-dom and
21-
// fails the whole run even when every assertion passed (#1760). Waiting for one
22-
// cell to unmount doesn't settle the *sibling* enter cells (a completed enter
23-
// leaves no DOM signal to `waitFor`). Drain every pending timer here — while the
24-
// tree is still mounted, so the settling setState targets a live component —
25-
// before the global cleanup() unmounts (#1786).
26-
async function settleTransitions() {
27-
await act(async () => {
28-
await new Promise((resolve) => setTimeout(resolve, TRANSITION_SETTLE_MS));
29-
});
30-
}
14+
// transitions to observe mid-flight "in"/"out" cells. Waiting for one cell to
15+
// unmount doesn't settle the *sibling* enter cells (a completed enter leaves no
16+
// DOM signal to `waitFor`), so those tests call `settleTransitions(...)` to
17+
// flush the in-flight animation before teardown (#1786). Derive the window from
18+
// the component's real duration plus rAF scheduling slack, so bumping
19+
// HEADER_ANIM_MS can't silently make the settle insufficient.
20+
const TRANSITION_SETTLE_MS = HEADER_ANIM_MS + 200;
3121

3222
// Mock @mantine/hooks so we can control useMediaQuery results per test.
3323
const mediaQueryMock = vi.hoisted(() => ({ value: false }));
@@ -281,7 +271,7 @@ describe("ViewHeader", () => {
281271

282272
// The title's *enter* runs concurrently and leaves no unmount to await;
283273
// settle it so no timer fires post-teardown (#1786).
284-
await settleTransitions();
274+
await settleTransitions(TRANSITION_SETTLE_MS);
285275
});
286276

287277
it("glows a tab added after the connect grace window, not during it (#1450)", () => {
@@ -377,7 +367,7 @@ describe("ViewHeader", () => {
377367

378368
// The title's concurrent *enter* leaves no unmount to await; settle it so
379369
// no timer fires post-teardown (#1786).
380-
await settleTransitions();
370+
await settleTransitions(TRANSITION_SETTLE_MS);
381371
});
382372

383373
it("renders the dark-scheme icon/logo branch under a dark color scheme", () => {
@@ -427,7 +417,7 @@ describe("ViewHeader", () => {
427417
// Both the title's exit and the server name's enter are still in flight
428418
// (the enter leaves no unmount to await); settle them so no timer fires
429419
// post-teardown (#1786).
430-
await settleTransitions();
420+
await settleTransitions(TRANSITION_SETTLE_MS);
431421
});
432422

433423
it("disarms the tab glow when the connection drops after the grace window", () => {

‎clients/web/src/components/groups/ViewHeader/ViewHeader.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ export type ViewHeaderProps = ConnectedProps | UnconnectedProps;
5959
// Disconnect controls (right) all fade + slide-down, staggered by half this
6060
// duration. The motion itself is CSS (`.header-anim`); keep the 300ms /
6161
// 150ms-stagger there in sync with this value.
62-
const HEADER_ANIM_MS = 300;
62+
export const HEADER_ANIM_MS = 300;
6363
// Grace window after a connection is established before the new-tab glow arms
6464
// (#1450). Primitive lists (prompts/resources/tasks) are fetched asynchronously
6565
// just after the handshake, so their tabs appear a few renders into the

‎clients/web/src/test/renderWithMantine.tsx‎

Lines changed: 37 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import type { ReactElement, ReactNode } from "react";
2-
import { render, type RenderOptions } from "@testing-library/react";
2+
import { act, render, type RenderOptions } from "@testing-library/react";
33
import { MantineProvider, type MantineColorScheme } from "@mantine/core";
4+
import { vi } from "vitest";
45
import { theme } from "../theme/theme";
56

67
// Options accepted by both render helpers: the standard RTL options (minus
@@ -41,9 +42,8 @@ export function renderWithMantine(
4142
// (e.g. a `data-anim="out"` cell during an exit crossfade). Such a test MUST
4243
// drive every transition to completion so no rAF→`setTimeout` chain is still
4344
// pending at teardown; otherwise it reintroduces the #1760 leak. A settled enter
44-
// leaves no DOM signal to `waitFor`, so tests that open a transition they can't
45-
// observe closing should flush pending timers against the still-mounted tree
46-
// before ending (see `settleTransitions` in ViewHeader.test.tsx, #1786).
45+
// leaves no DOM signal to `waitFor`, so a test that opens a transition it can't
46+
// observe closing should call `settleTransitions()` before ending (#1786).
4747
export function renderWithMantineTransitions(
4848
ui: ReactElement,
4949
options?: MantineRenderOptions,
@@ -52,4 +52,37 @@ export function renderWithMantineTransitions(
5252
return render(ui, { wrapper: makeWrapper("default", colorScheme), ...rest });
5353
}
5454

55+
// Fallback settle window: Mantine's default header transitions run ~300ms, so
56+
// 500ms clears them plus the two-frame rAF scheduling slack. Callers that know
57+
// their component's animation duration should pass it (duration + slack) rather
58+
// than rely on this.
59+
const DEFAULT_SETTLE_MS = 500;
60+
61+
// Flush any in-flight `renderWithMantineTransitions` animation before the test
62+
// ends. Mantine's `useTransition` cancels its own timers on unmount (its
63+
// `useEffect` cleanup clears the rAF + `setTimeout`), so the hazard isn't a
64+
// timer surviving unmount — it's the React state update that Mantine's inner
65+
// rAF schedules *outside* `act` (`setStatus("entering"/"exiting")` → the
66+
// terminal `setStatus`). Left in flight, that work resolves after happy-dom
67+
// tears down `window` and throws `ReferenceError: window is not defined` from
68+
// react-dom's `dispatchSetState → resolveUpdatePriority`, failing the whole run
69+
// even when every assertion passed (#1760/#1786). This awaits a real timer
70+
// inside `act` so those queued rAF callbacks and the React updates they schedule
71+
// run and flush against the still-mounted tree — the ordering that keeps the
72+
// settling `setState` on a live component. Because it awaits a *real*
73+
// `setTimeout`, it deadlocks under fake timers, so guard against that with a
74+
// clear message rather than a 5s test-timeout hang.
75+
export async function settleTransitions(ms: number = DEFAULT_SETTLE_MS) {
76+
if (vi.isFakeTimers()) {
77+
throw new Error(
78+
"settleTransitions() awaits a real setTimeout and cannot run under " +
79+
"vi.useFakeTimers(); call vi.useRealTimers() first, or advance the " +
80+
"faked timers manually to settle the transition.",
81+
);
82+
}
83+
await act(async () => {
84+
await new Promise((resolve) => setTimeout(resolve, ms));
85+
});
86+
}
87+
5588
export * from "@testing-library/react";

‎clients/web/src/test/setup.ts‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -57,15 +57,17 @@ Object.defineProperty(globalThis, "fetch", {
5757
),
5858
});
5959

60-
// happy-dom doesn't implement `matchMedia`, so Mantine's `useReducedMotion`
61-
// resolves to "motion allowed" and every `Transition` (ScreenStage, Modal, …)
62-
// schedules real enter/exit `setTimeout`s. A timer that outlives its test fires
63-
// after the environment is torn down and throws `window is not defined` from
64-
// deep in react-dom — an unhandled error that fails the run even though every
65-
// test passed. Report `prefers-reduced-motion: reduce` so Mantine transitions
66-
// render instantly (no timers); all other queries stay `false`, matching the
67-
// prior (absent-matchMedia) behavior so `useMediaQuery`-driven layout is
68-
// unchanged. Tests that need specific media results still mock `@mantine/hooks`
60+
// happy-dom doesn't implement `matchMedia`, so anything reading it (Mantine's
61+
// `useReducedMotion`, `useMediaQuery`-driven layout) would otherwise throw.
62+
// Provide a stub. We report `prefers-reduced-motion: reduce` and keep all other
63+
// queries `false` (matching the prior absent-matchMedia layout behavior). Note
64+
// this does *not*, on its own, disable Mantine transitions: `useTransition`
65+
// only honors reduced motion when `theme.respectReducedMotion` is true, and
66+
// Mantine 8 defaults it to `false` (the project theme doesn't override it). The
67+
// actual protection against the #1760 post-teardown `window is not defined`
68+
// leak is `env="test"` in `renderWithMantine`, which forces transitions
69+
// synchronous regardless; this stub just keeps `matchMedia` callers from
70+
// blowing up. Tests that need specific media results still mock `@mantine/hooks`
6971
// or stub `matchMedia` themselves.
7072
Object.defineProperty(window, "matchMedia", {
7173
configurable: true,

0 commit comments

Comments
 (0)