π 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.pngnew file mode 100644index 0000000000..1e97f0239bBinary files /dev/null and b/.github/pr-assets/pr-17556-node-env-pilot-timings.png differdiff --git a/__tests__/vite-config.test.ts b/__tests__/vite-config.test.tsindex 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.mdindex 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 testingStryker checks whether the Vitest suite detects deliberate changes to thediff --git a/vite.config.ts b/vite.config.tsindex 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