Skip to content

πŸ™Œ OpenHands: AI-Driven Development

test: run verified DOM-free suites in a Node project (#17556)

Denis Ermakov5ddcd7276ca8
diff --git a/.github/pr-assets/pr-17556-node-env-pilot-timings.png b/.github/pr-assets/pr-17556-node-env-pilot-timings.png
new file mode 100644
index 0000000000..1e97f0239b
Binary files /dev/null and b/.github/pr-assets/pr-17556-node-env-pilot-timings.png differ
diff --git a/__tests__/vite-config.test.ts b/__tests__/vite-config.test.ts
index daa800abc3..6aa10961ab 100644
--- a/__tests__/vite-config.test.ts
+++ b/__tests__/vite-config.test.ts
@@ -22,6 +22,56 @@ describe("vite optimizeDeps", () => {
});
});
+describe("vitest environment projects", () => {
+ const getProjects = async () => {
+ const config = await viteConfig({ mode: "test", command: "serve" });
+
+ return (config.test?.projects ?? []) as Array<{
+ test?: {
+ name?: string;
+ environment?: string;
+ setupFiles?: string[];
+ include?: string[];
+ exclude?: string[];
+ };
+ }>;
+ };
+
+ const findProject = (
+ projects: Awaited<ReturnType<typeof getProjects>>,
+ name: string,
+ ) => projects.find((project) => project.test?.name === name)?.test;
+
+ it("runs the DOM-free pilot suites in the Node environment without the jsdom setup", async () => {
+ const nodeProject = findProject(await getProjects(), "node");
+
+ expect(nodeProject?.environment).toBe("node");
+ // The pilot suites are pure functions: no DOM, no Web Storage, no MSW.
+ expect(nodeProject?.setupFiles).toEqual([]);
+ expect(nodeProject?.include).toEqual([
+ "__tests__/utils/file-language.test.ts",
+ "__tests__/utils/format-model-name.test.ts",
+ "__tests__/utils/parse-terminal-output.test.ts",
+ ]);
+ });
+
+ it("keeps every other suite in jsdom with the shared setup", async () => {
+ const jsdomProject = findProject(await getProjects(), "jsdom");
+
+ expect(jsdomProject?.environment).toBe("jsdom");
+ expect(jsdomProject?.setupFiles).toEqual(["vitest.setup.ts"]);
+ });
+
+ it("excludes the pilot suites from jsdom so they run exactly once", async () => {
+ const projects = await getProjects();
+ const nodeInclude = findProject(projects, "node")?.include ?? [];
+ const jsdomExclude = findProject(projects, "jsdom")?.exclude ?? [];
+
+ expect(nodeInclude.length).toBeGreaterThan(0);
+ expect(jsdomExclude).toEqual(expect.arrayContaining(nodeInclude));
+ });
+});
+
describe("vite path resolution", () => {
it("uses Vite's native tsconfig paths support", async () => {
const config = await viteConfig({ mode: "development", command: "serve" });
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 336cc6f517..56faebd18b 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -132,6 +132,75 @@ Useful targeted verification for the isolated dev launcher:
npm run test -- __tests__/api/agent-server-config.test.ts __tests__/scripts/dev-safe.test.ts
```
+### Unit test environments
+
+`npm test` runs Vitest as two projects, so each suite pays only for the
+environment it actually needs:
+
+| Project | Environment | Setup | Suites |
+| ------- | ----------- | ----------------- | ------------------------------------------------------------------------ |
+| `jsdom` | `jsdom` | `vitest.setup.ts` | everything else (the default) |
+| `node` | `node` | none | the DOM-free suites listed in `NODE_ENV_PILOT_TESTS` in `vite.config.ts` |
+
+Both projects run in a single `npm test`, and the Node list is excluded from
+the jsdom project, so every suite runs exactly once. Vitest prefixes each
+result with its project name (`|node|` / `|jsdom|`) when a test fails or when
+you pass `--reporter=verbose`.
+
+The Node project exists because jsdom is not free: it costs roughly a second of
+environment setup per run, plus the whole of `vitest.setup.ts` (Testing Library
+cleanup, MSW, jest-dom, DOM global stubs). Suites that only call pure functions
+need none of it.
+
+#### Adding a suite to the Node project
+
+A suite qualifies only if **all** of the following hold. Check the suite and
+everything it imports, transitively β€” an import that touches the DOM at module
+scope is enough to disqualify it.
+
+- No DOM: no `document`, `window`, `HTMLElement`, `navigator`, or
+ `@testing-library/*` rendering.
+- No Web Storage or browser-owned globals: no `localStorage`,
+ `sessionStorage`, `location`, `matchMedia`, `requestAnimationFrame`.
+- No React component rendering or hook execution.
+- No MSW / network interception: nothing that relies on the `server` started
+ in `vitest.setup.ts`.
+- Nothing from `vitest.setup.ts` at all β€” the Node project loads no setup
+ file, so a suite that depends on one of its stubs (for example the
+ `VITE_SESSION_API_KEY` env stub) belongs in jsdom.
+
+Then add the suite's path to `NODE_ENV_PILOT_TESTS` in `vite.config.ts` and run
+it. Passing under the Node project is the confirmation; a `ReferenceError`
+naming a browser global means the suite belongs in jsdom.
+
+Keep the list explicit rather than glob-based: a glob would silently adopt new
+suites that have never been checked against the rules above.
+
+An individual suite can also opt into Node with a `// @vitest-environment node`
+docblock, which several `__tests__/scripts/` suites already do. That still
+loads `vitest.setup.ts`; the Node project is for suites that need no setup at
+all.
+
+#### Rolling back
+
+The pilot is contained in one config block and unwinds in stages:
+
+- **One suite misbehaves** β€” remove its path from `NODE_ENV_PILOT_TESTS`. It
+ returns to the jsdom project automatically, because that project excludes
+ exactly this list.
+- **Revert the split entirely** β€” empty `NODE_ENV_PILOT_TESTS`, then replace
+ `test.projects` with the previous flat options:
+
+ ```ts
+ environment: "jsdom",
+ setupFiles: ["vitest.setup.ts"],
+ exclude: [...configDefaults.exclude, "tests"],
+ ```
+
+No test file changes are needed either way: the pilot suites are unmodified and
+pass in both environments. The expectations in `__tests__/vite-config.test.ts`
+describe the split, so remove them in the same commit as a full revert.
+
### Mutation testing
Stryker checks whether the Vitest suite detects deliberate changes to the
diff --git a/vite.config.ts b/vite.config.ts
index 5864997813..00f0ae9022 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -25,6 +25,18 @@ const LIB_EXTERNALS = [
];
const APP_CHUNK_MAX_BYTES = 450 * 1024;
+// Suites verified to be DOM-free: they import pure functions only, touch no
+// DOM, Web Storage, timers or network, and therefore need neither the jsdom
+// environment nor the shared `vitest.setup.ts`. They run in a separate Node
+// project instead, which is measurably faster. See docs/DEVELOPMENT.md β†’
+// "Unit test environments" for the classification rules a suite must meet
+// before it is added here, and for how to roll the pilot back.
+const NODE_ENV_PILOT_TESTS = [
+ "__tests__/utils/file-language.test.ts",
+ "__tests__/utils/format-model-name.test.ts",
+ "__tests__/utils/parse-terminal-output.test.ts",
+];
+
const normalizeBasePath = (value?: string) => {
const raw = value?.trim();
if (!raw || raw === "/") return "/";
@@ -471,9 +483,34 @@ export default defineConfig(({ mode }) => {
},
clearScreen: false,
test: {
- environment: "jsdom",
- setupFiles: ["vitest.setup.ts"],
- exclude: [...configDefaults.exclude, "tests"],
+ projects: [
+ {
+ extends: true,
+ test: {
+ name: "jsdom",
+ environment: "jsdom",
+ setupFiles: ["vitest.setup.ts"],
+ // The pilot suites are excluded here so they run exactly once,
+ // in the Node project below.
+ exclude: [
+ ...configDefaults.exclude,
+ "tests",
+ ...NODE_ENV_PILOT_TESTS,
+ ],
+ },
+ },
+ {
+ extends: true,
+ test: {
+ name: "node",
+ environment: "node",
+ include: [...NODE_ENV_PILOT_TESTS],
+ // These suites exercise pure functions, so they need none of the
+ // jsdom / Testing Library / MSW wiring in vitest.setup.ts.
+ setupFiles: [],
+ },
+ },
+ ],
// The full suite runs many DOM-heavy tests in parallel, which can
// push individual `userEvent`-driven tests past Vitest's 5000ms
// default on busy machines (the skills-settings and i18n