test(web): disposable render helper and lint rule for browser tests#22187

Web browser tests managed React roots, act and globals by hand in beforeEach/afterEach. The first version of this PR replaced that with a helper that pushed screens onto a module-level array for an afterEach to drain. State could still leak between tests, and whatever pattern is in the tree is the one agents copy. This version gives every browser test a resource it owns and disposes.

The pattern

apps/web/test/render.tsx exports:

• render(ui, { container?, router? }) returns a Screen: container-scoped locators, container, router, rerender, unmount, and Symbol.asyncDispose. Disposing it unmounts the root and removes the container. Unmounting also unsubscribes the router from its history. router defaults to "/"; pass false to render without one. If the first render throws, the helper cleans up before rethrowing.
• act(cb) turns on IS_REACT_ACT_ENVIRONMENT only while cb runs and restores the previous value afterwards, so updates driven by userEvent, timers or the network never trigger act warnings.
• fakeTimers(config?) and stubGlobal(name, value) return Disposables. Vitest spies are already disposable, so using _spy = vi.spyOn(...) works.

For a fixture that needs several of these at once, use AsyncDisposableStack and hand ownership to the returned screen with stack.move() (see RightPanelTabs.keyboard and colorPickers).

src/testRender.browser.test.tsx checks that disposal unmounts the tree, removes the container and empties the router history's subscribers. It also checks that a render that throws leaves nothing in document.body, that the act environment is off outside the helper, and that stubGlobal restores the global.

Toolchain. TypeScript and Chromium already supported using and AsyncDisposableStack. The types only reached apps/web through a /// <reference lib="esnext.disposable" /> in @types/node, so apps/web/tsconfig.json now lists ESNext.Disposable explicitly. That is the only config change.

Why no lifecycle hooks

A hook runs for every test in its scope, so whatever it sets up is shared, and its cleanup only runs if the hook itself is correct. With using, a test acquires exactly what it changes, and disposal runs when the block exits, pass or fail, in reverse order. Each test reads top to bottom with nothing hidden.

vi.mock factories are hoisted and can only read module-level state. Files that need this keep it in vi.hoisted state and reset it with a setup() call on the first line of each test, so every test still starts from a known state.

Lint rule

t3code/require-disposable-render applies to apps/web/**/*.test.tsx and reports:

• imports from react-dom/client
• act (or unstable_act) imported from react
• assignments to IS_REACT_ACT_ENVIRONMENT, and vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", …)
• beforeEach/afterEach/beforeAll/afterAll in *.browser.test.tsx

It is set to warn so main stays green. It currently reports 635 warnings in 132 files. Change it to error in vite.config.ts once vp lint reports no t3code(require-disposable-render) warnings. The comment next to the override says the same. AGENTS.md (Verifying) documents the convention with the example above.

Migrated

These nine files have no lifecycle hooks, no module-level screens or containers, and no cleanup(): BranchToolbar.panel, GitActionsControl, RightPanelTabs.keyboard, MessagesTimeline, WelcomeWizard.import, PreviewView, PullRequestDetailPanel, PullRequestSummaryTab and colorPickers. All of them became independent without a hook:

• Tests that rendered twice now use screen.rerender. Tests that need a fresh mount use a block-scoped await using.
• MessagesTimeline builds each thread key from a fresh random id instead of a module counter.
• PullRequestSummaryTab scopes its localStorage clearing to the two filter tests with using.
• RightPanelTabs.keyboard now renders with router: false, as it did on main. Behind the test router, the Escape focus-return test failed in about 1 of 3 runs when all nine files ran together. It passed 5 of 5 on the previous head. It has passed every run since this change.

vitest-browser-react is removed again. render is about 40 lines on react-dom/client, and owning the root is what makes disposal exact.

Verification

• The nine files plus the helper test (189 tests) ran with --reporter=verbose. The last four runs in a row passed, with 0 "not wrapped in act" warnings, 0 act-environment warnings and 0 router warnings in each. The full web suite was not run.
• t3code/require-disposable-render has fixture tests (11 cases).
• apps/web and oxlint-plugin-t3code typecheck. vp lint and vp fmt --check are clean on the changed files.

Remaining 133 files

133 browser test files still use the old pattern (132 of them trip the rule). The plan:

1. Migrate by directory in PRs of about 15 to 20 files, each verified the same way: three consecutive runs and zero React warnings.
2. Each PR lowers the warning count. Nothing new can add warnings, because review and the lint output flag them.
3. When the count reaches zero, change the rule to error in the same PR.

Model: Claude Opus 5.5 (claude-opus-5-5) in Claude Code, inside T3 Code.

🤖 Generated with Claude Code

Scope and approval

Maintainer-driven test infrastructure change, no product runtime impact. Approved by @juliusmarminge (maintainer) in the coordinating T3 thread on 2026-10-20: the disposable await using render convention was requested after rejecting the earlier shared-array/afterEach helper, the foundation was approved with "Test foundation seems fine. Go update all the other react tests with it", and the full stack (foundation plus slices #22267 to #22276) was approved to merge with "merge the full testing stack now". No linked issue; this is internal test tooling.