@catalystiq/test-kit 0.3.0 → 0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # @catalystiq/test-kit
 
-Shared test helpers: one package, added to part by part. Pin an exact version (`"@catalystiq/test-kit": "0.3.0"`);
+Shared test helpers: one package, added to part by part. Pin an exact version (`"@catalystiq/test-kit": "0.3.1"`);
 Dependabot raises it.
 
 | Part | Import | What |

package/dist/setup/README.md

@@ -32,7 +32,7 @@ A file that needs a DOM says so on its first line: `// @vitest-environment jsdom
 | Production databases | A Postgres URL in the environment whose host is on your production list (a host, a subdomain of it, or a compute endpoint id `ep-…` with or without `-pooler`) is refused before any test runs, and again before the tests (your own setup file may set the URL). |
 | `.env*` files | A Postgres URL in the environment that names the same database as any `.env*` file at the root is refused: those hold a developer's own connections. Every `postgres://` text counts, comments included, except lines keyed by `testDatabaseEnv`. |
 | React warnings | A React or Radix warning (`console.error` / `console.warn`) fails the test, also when the test muted the console (`vi.spyOn(console, 'error').mockImplementation(() => {})`, `console.error = vi.fn()`, `console.error = () => {}`). |
-| DOM files | Under jsdom: a `matchMedia` stub, `localStorage` / `sessionStorage` re-bound on Node 26, Testing Library's `cleanup` after each test, and jest-dom's matchers when installed. |
+| DOM files | Under jsdom: a `matchMedia` stub, `localStorage` / `sessionStorage` re-bound on Node 26, Testing Library's `cleanup` after each test (imported by the setup; with `domCleanup: 'deferred'`, after the first test instead, so a file can put React's devtools hook in place before react-dom loads), and jest-dom's matchers when installed. |
 
 ## Allowing a React warning
 

package/dist/setup/config.d.ts

@@ -18,6 +18,16 @@ export interface TestKitOptions {
     testDatabaseEnv?: string[];
     /** The React-warning allow-list file, relative to `root` (see the README). */
     reactWarningAllowList?: string;
+    /**
+     * When a jsdom file's Testing Library `cleanup` is imported. `'setup'` (the default): by the setup, once per file.
+     * `'deferred'`: after the file's first test, once, so the setup loads no react-dom before the test file, for a file that puts React's
+     * devtools hook in place in `vi.hoisted` (React finds the hook only if it is there before react-dom loads). Deferred,
+     * cleanup uses the instance first imported after a test; a file that resets modules or mocks Testing Library without
+     * a `cleanup` gets none; and under `globals: true`, Testing Library's own `beforeAll` (which marks the environment as
+     * React's `act` environment) is not registered for a file that does not import it, so such a file sets
+     * `IS_REACT_ACT_ENVIRONMENT` itself.
+     */
+    domCleanup?: 'setup' | 'deferred';
 }
 /** What the workers receive. */
 export interface TestKitProvided {
@@ -31,6 +41,7 @@ export interface TestKitProvided {
         pattern: string;
         file?: string;
     }>;
+    domCleanup: 'setup' | 'deferred';
 }
 declare module 'vitest' {
     interface ProvidedContext {

package/dist/setup/config.js

@@ -40,6 +40,10 @@ export function provideFor(options = {}) {
         ...(options.productionDatabaseHostsFile ? readHostsFile(at(options.productionDatabaseHostsFile)) : []),
     ];
     const allowList = options.reactWarningAllowList ? readAllowList(at(options.reactWarningAllowList)) : null;
+    const domCleanup = options.domCleanup ?? 'setup';
+    if (domCleanup !== 'setup' && domCleanup !== 'deferred') {
+        throw new Error(`test-kit: domCleanup must be 'setup' or 'deferred', not ${JSON.stringify(domCleanup)}`);
+    }
     return {
         allowHosts: options.allowHosts ?? [],
         allowDatabaseHosts: options.allowDatabaseHosts ?? true,
@@ -48,6 +52,7 @@ export function provideFor(options = {}) {
         productionHosts,
         protectedPlaces: protectedPlaces(root, options.testDatabaseEnv ?? []),
         allowedWarnings: (allowList?.entries ?? []).map((e) => ({ pattern: e.pattern, ...(e.file ? { file: e.file } : {}) })),
+        domCleanup,
     };
 }
 /** The kit's part of a Vitest config. */

package/dist/setup/dom.d.ts

@@ -7,8 +7,12 @@ export declare function installMatchMedia(): void;
  */
 export declare function rebindStorage(): void;
 export interface DomOptions {
-    /** Unmount what Testing Library rendered after each test (it does so itself only under Vitest's globals). Default: true. */
-    cleanup?: boolean;
+    /**
+     * Unmount what Testing Library rendered after each test (it does so itself only under Vitest's globals). Default:
+     * true, importing Testing Library now. `'deferred'` imports it after the first test instead (once per file), so this
+     * setup loads no react-dom before the test file does (the config's `domCleanup`).
+     */
+    cleanup?: boolean | 'deferred';
     /** Load `@testing-library/jest-dom`'s matchers when it is installed. Default: true. */
     jestDom?: boolean;
 }

package/dist/setup/dom.js

@@ -62,7 +62,23 @@ export async function installDom(options = {}) {
     rebindStorage();
     if (options.jestDom ?? true)
         await optionalImport('@testing-library/jest-dom/vitest');
-    if (options.cleanup ?? true) {
+    if (options.cleanup === 'deferred') {
+        let rtl;
+        afterEach(async () => {
+            rtl ??= optionalImport('@testing-library/react');
+            const module = await rtl; // as in setup mode, only a missing module is ignored; any other failure fails the cleanup
+            let cleanup;
+            try {
+                cleanup = module?.cleanup;
+            }
+            catch {
+                // a mock of Testing Library without a cleanup export: nothing to unmount with
+            }
+            if (typeof cleanup === 'function')
+                cleanup();
+        });
+    }
+    else if (options.cleanup ?? true) {
         const rtl = await optionalImport('@testing-library/react');
         const cleanup = rtl?.cleanup;
         if (typeof cleanup === 'function')

package/dist/setup/setup-file.js

@@ -41,4 +41,4 @@ afterEach(() => {
     if (parts.length > 0)
         throw new Error(parts.join('\n\n'));
 });
-await installDom();
+await installDom({ cleanup: provided.domCleanup === 'deferred' ? 'deferred' : true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalystiq/test-kit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Shared test setup for Vitest, a fake MCP Apps host for jsdom and Playwright, the local Neon test-database run, and the local environment guard.",
   "type": "module",
   "license": "MIT",