Skip to content

Commit fc32b6f

Browse files
test(web): warn on hand-managed React roots in web tests
t3code/require-disposable-render flags react-dom/client, act from react and writes to IS_REACT_ACT_ENVIRONMENT in apps/web tests, and lifecycle hooks in browser tests. It warns until the remaining files move to the disposable render helper. AGENTS.md documents the convention. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent ef249dd commit fc32b6f

5 files changed

Lines changed: 158 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,18 @@ An empty database is a bad test. Seed your worktree's `.t3` with a copy of real
100100
- **Do not run repo-wide checks.** No `vp check`, no `vp run -r test`, no `vp run -r typecheck` unless I ask. CI owns the full suite.
101101
- Backend behavior changes ship with focused tests for that behavior.
102102
- The server is event-sourced, and side effects run after the command commits. In tests, drain the effect worker (`OrchestrationEffectWorkerV2.drain`) or await the specific persisted event or `Deferred` that marks the milestone. Never wait on sleeps or polling. A test that needs a timeout to pass is wrong.
103+
- Web component tests are `*.browser.test.tsx` and render through `apps/web/test/render.tsx`. Acquire everything a test changes with `using`/`await using` so disposal undoes it even when the test fails; no `beforeEach`/`afterEach`, no module-level screens. Shared mock state that `vi.mock` factories read gets reset by a `setup()` call at the top of the test. `t3code/require-disposable-render` flags the old patterns.
104+
105+
```tsx
106+
it("saves on Enter", async () => {
107+
const onSave = vi.fn();
108+
using _now = vi.spyOn(Date, "now").mockReturnValue(0);
109+
await using screen = await render(<TitleEditor onSave={onSave} />, { router: "/threads/1" });
110+
await userEvent.type(screen.getByRole("textbox"), "Title{Enter}");
111+
expect(onSave).toHaveBeenCalledWith("Title");
112+
});
113+
```
114+
103115
- Upon request, user-visible frontend changes should get one integrated pass in a real client: `test-t3-app` for web, `test-t3-mobile` for mobile. The primary agent does this once after integrating. Subagents do not launch their own dev servers. Ask permission before doing computer use or spinning up browsers.
104116

105117
For authorized mobile verification, a missing or outdated native client is a build step, not a blocker. Run `node scripts/mobile-native-client.ts ensure <ios|android> <device-id>` on the simulator host before starting Metro. It checks the local Expo fingerprint and builds/installs when needed. See `test-t3-mobile` for the full workflow.

‎oxlint-plugin-t3code/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import noUnscopedHas from "./rules/no-unscoped-has.ts";
2121
import preferCatchTags from "./rules/prefer-catch-tags.ts";
2222
import preferEffectFn from "./rules/prefer-effect-fn.ts";
2323
import requireCenteredScrollGutter from "./rules/require-centered-scroll-gutter.ts";
24+
import requireDisposableRender from "./rules/require-disposable-render.ts";
2425
import requireSuppressionReason from "./rules/require-suppression-reason.ts";
2526

2627
export default definePlugin({
@@ -49,6 +50,7 @@ export default definePlugin({
4950
"prefer-catch-tags": preferCatchTags,
5051
"prefer-effect-fn": preferEffectFn,
5152
"require-centered-scroll-gutter": requireCenteredScrollGutter,
53+
"require-disposable-render": requireDisposableRender,
5254
"require-suppression-reason": requireSuppressionReason,
5355
},
5456
});
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
import { describe } from "@effect/vitest";
2+
3+
import { createOxlintRuleHarness } from "../test/utils.ts";
4+
5+
const browserTest = createOxlintRuleHarness("t3code/require-disposable-render", {
6+
filename: "Widget.browser.test.tsx",
7+
});
8+
const unitTest = createOxlintRuleHarness("t3code/require-disposable-render", {
9+
filename: "widget.test.tsx",
10+
});
11+
12+
describe("t3code/require-disposable-render", () => {
13+
browserTest.valid(
14+
"allows the disposable helper",
15+
[
16+
'import { act, render } from "../test/render";',
17+
'import { useState } from "react";',
18+
'it("renders", async () => {',
19+
" await using screen = await render(null);",
20+
" await act(() => screen.rerender(null));",
21+
"});",
22+
].join("\n"),
23+
);
24+
browserTest.invalid("rejects react-dom/client", 'import { createRoot } from "react-dom/client";');
25+
browserTest.invalid("rejects act from react", 'import { act } from "react";');
26+
browserTest.invalid(
27+
"rejects a renamed act from react",
28+
'import { act as reactAct } from "react";',
29+
);
30+
browserTest.invalid(
31+
"rejects setting the act environment",
32+
"globalThis.IS_REACT_ACT_ENVIRONMENT = true;",
33+
);
34+
browserTest.invalid(
35+
"rejects setting the act environment by computed key",
36+
'window["IS_REACT_ACT_ENVIRONMENT"] = true;',
37+
);
38+
browserTest.invalid(
39+
"rejects stubbing the act environment",
40+
'vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);',
41+
);
42+
browserTest.invalid("rejects afterEach", "afterEach(async () => {});");
43+
browserTest.invalid("rejects beforeAll", "beforeAll(() => {});");
44+
unitTest.valid("allows lifecycle hooks outside browser tests", "beforeEach(() => {});");
45+
unitTest.invalid("still rejects react-dom/client in unit tests", 'import "react-dom/client";');
46+
});
Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
import { defineRule, type ESTree } from "@oxlint/plugins";
2+
import * as Option from "effect/Option";
3+
4+
import { getPropertyName, unwrapExpression } from "../utils.ts";
5+
6+
const BROWSER_TEST_FILE = /\.browser\.test\.[cm]?[jt]sx?$/u;
7+
const LIFECYCLE_HOOKS = new Set(["afterAll", "afterEach", "beforeAll", "beforeEach"]);
8+
const REACT_ACT_EXPORTS = new Set(["act", "unstable_act"]);
9+
const ACT_ENVIRONMENT = "IS_REACT_ACT_ENVIRONMENT";
10+
const HELPER = "Render with `await using screen = await render(...)` from apps/web/test/render.tsx";
11+
12+
const MESSAGES = {
13+
reactDomClient: `${HELPER}; it owns the React root and unmounts it on dispose.`,
14+
reactAct: `${HELPER} and import \`act\` from there; it enables React's act environment only while act runs.`,
15+
actEnvironment: `${HELPER}; its act() sets ${ACT_ENVIRONMENT} for exactly as long as it runs.`,
16+
lifecycleHook:
17+
"Browser tests acquire what they need with `using`/`await using` instead of lifecycle hooks, so nothing outlives the test that created it.",
18+
};
19+
20+
const stringValue = (node: ESTree.Node | null | undefined) =>
21+
node?.type === "Literal" && typeof node.value === "string" ? node.value : undefined;
22+
23+
const namesActEnvironment = (node: unknown) => {
24+
const target = unwrapExpression(node);
25+
if (Option.isNone(target)) return false;
26+
if (target.value.type === "Identifier") return target.value.name === ACT_ENVIRONMENT;
27+
if (target.value.type !== "MemberExpression") return false;
28+
const property = target.value.computed
29+
? Option.fromNullishOr(stringValue(target.value.property))
30+
: getPropertyName(target.value.property);
31+
return Option.getOrUndefined(property) === ACT_ENVIRONMENT;
32+
};
33+
34+
export default defineRule({
35+
meta: {
36+
type: "problem",
37+
docs: {
38+
description:
39+
"Require web component tests to render through the disposable test helper instead of managing React roots, act, or lifecycle hooks by hand.",
40+
},
41+
},
42+
create(context) {
43+
const isBrowserTest = BROWSER_TEST_FILE.test(context.filename);
44+
45+
return {
46+
ImportDeclaration(node) {
47+
if (node.source.value === "react-dom/client") {
48+
context.report({ node: node.source, message: MESSAGES.reactDomClient });
49+
return;
50+
}
51+
if (node.source.value !== "react") return;
52+
for (const specifier of node.specifiers) {
53+
if (specifier.type !== "ImportSpecifier") continue;
54+
const imported =
55+
specifier.imported.type === "Identifier"
56+
? specifier.imported.name
57+
: specifier.imported.value;
58+
if (REACT_ACT_EXPORTS.has(imported)) {
59+
context.report({ node: specifier, message: MESSAGES.reactAct });
60+
}
61+
}
62+
},
63+
AssignmentExpression(node) {
64+
if (namesActEnvironment(node.left)) {
65+
context.report({ node: node.left, message: MESSAGES.actEnvironment });
66+
}
67+
},
68+
CallExpression(node) {
69+
const callee = unwrapExpression(node.callee);
70+
if (Option.isNone(callee)) return;
71+
if (callee.value.type === "MemberExpression") {
72+
// vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true) leaves the flag on for the whole test.
73+
const method = getPropertyName(callee.value.property);
74+
if (
75+
Option.getOrUndefined(method) === "stubGlobal" &&
76+
stringValue(node.arguments[0] as ESTree.Node | undefined) === ACT_ENVIRONMENT
77+
) {
78+
context.report({ node, message: MESSAGES.actEnvironment });
79+
}
80+
return;
81+
}
82+
if (
83+
isBrowserTest &&
84+
callee.value.type === "Identifier" &&
85+
LIFECYCLE_HOOKS.has(callee.value.name)
86+
) {
87+
context.report({ node: node.callee, message: MESSAGES.lifecycleHook });
88+
}
89+
},
90+
};
91+
},
92+
});

‎vite.config.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,12 @@ export default defineConfig({
187187
],
188188
rules: { "t3code/prefer-effect-fn": "off" },
189189
},
190+
{
191+
// Warns while the remaining web component tests move to apps/web/test/render.tsx.
192+
// Raise to "error" once `vp lint` reports no t3code(require-disposable-render) warnings.
193+
files: ["apps/web/**/*.test.tsx"],
194+
rules: { "t3code/require-disposable-render": "warn" },
195+
},
190196
{
191197
files: ["apps/**/src/**", "packages/**/src/**"],
192198
excludeFiles: DOM_TEST_ENVIRONMENT_ALLOWLIST,

0 commit comments

Comments
 (0)