@catalystiq/test-kit 0.0.0-stage → 0.2.0

package/dist/setup/react-warnings.js

@@ -0,0 +1,168 @@
+/**
+ * REACT WARNINGS FAIL THE TEST. A warning React (or Radix) prints, an update outside `act()`, a duplicate key, invalid
+ * DOM nesting, used to vanish into a muted console. The guard screens every `console.error` / `console.warn` call against
+ * {@link REACT_WARNING_PATTERNS} and fails the test after it ends.
+ *
+ * It survives a test that mutes the console itself, three ways at once:
+ * - the console's `error` / `warn` are the guard's own screening functions, so an unmuted call is screened as it is made;
+ * - `globalThis.console` is a proxy that sees a test install a spy or a plain function on `error` / `warn`
+ *   (`vi.spyOn(console, 'error').mockImplementation(() => {})`, `console.error = vi.fn()`, `console.error = () => {}`)
+ *   and wraps it, so the arguments are screened before the test's implementation swallows them;
+ * - after each test the calls a console mock recorded are read again, the net under a `mockReset()`.
+ *
+ * A test that means to provoke a warning says so with {@link allowReactWarnings}; the allowance ends with the test. A
+ * repo-wide list (`react-warnings.allow.json`, see `allow-list.ts`) holds the warnings a repo has not fixed yet.
+ */
+import { expect, vi } from 'vitest';
+/** React's and Radix's warning texts (format strings: React 19 logs `console.error(format, ...args)`). */
+export const REACT_WARNING_PATTERNS = [
+    /not wrapped in act\(/,
+    /Encountered two children with the same key/,
+    /Each child in a list should have a unique "key" prop/,
+    /cannot be a descendant of <|cannot contain a nested <|cannot be a child of <|validateDOMNesting/,
+    /In HTML, .* cannot be a (?:child|descendant) of/,
+    /A component is changing an? (?:un)?controlled input/,
+    /Cannot update a component .* while rendering a different component/,
+    /Can't perform a React state update on/,
+    /React does not recognize the .* prop on a DOM element/,
+    /Received `.*` for a non-boolean attribute/,
+    /Invalid DOM property `/,
+    /Unknown event handler property `/,
+    /Function components cannot be given refs/,
+    /Maximum update depth exceeded/,
+    /A tree hydrated but some attributes of the server rendered HTML didn't match/,
+    /`DialogContent` requires a `DialogTitle`/,
+    /Missing `Description` or `aria-describedby=\{undefined\}`/,
+];
+const STATE = Symbol.for('catalystiq.test-kit.react-warnings');
+// Sets, not marker properties: a Vitest spy copies its original's own properties, so a marker on the guard's screening
+// function would make a spy of it look already wrapped.
+const SCREENING = new WeakSet();
+const WRAPPED_MOCKS = new WeakSet();
+function state() {
+    const g = globalThis;
+    g[STATE] ??= { caught: new Set(), allowed: [], repoAllowed: [], scannedUpTo: new WeakMap(), installed: false };
+    return g[STATE];
+}
+function argText(value) {
+    if (value instanceof Error)
+        return value.message;
+    if (typeof value === 'string')
+        return value;
+    try {
+        return String(value);
+    }
+    catch {
+        return '';
+    }
+}
+/** True when these console arguments are a React (or Radix) warning. */
+export function isReactWarning(args) {
+    const text = args.map(argText).join(' ');
+    return REACT_WARNING_PATTERNS.some((pattern) => pattern.test(text));
+}
+function currentTestPath() {
+    try {
+        return expect.getState().testPath ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/** Records the call when it is a React warning neither the test nor the repo allowed. */
+export function screenConsoleCall(level, args) {
+    if (!isReactWarning(args))
+        return;
+    const text = args.map(argText).join(' ');
+    const s = state();
+    if (s.allowed.some((pattern) => pattern.test(text)))
+        return;
+    const path = currentTestPath();
+    if (s.repoAllowed.some((entry) => entry.pattern.test(text) && (!entry.file || path.includes(entry.file))))
+        return;
+    s.caught.add(`console.${level}: ${text.slice(0, 800)}`);
+}
+function screened(level, next) {
+    const fn = function screenedConsole(...args) {
+        screenConsoleCall(level, args);
+        return next?.apply(this, args);
+    };
+    SCREENING.add(fn);
+    return fn;
+}
+/** Makes a console mock screen its arguments whatever implementation a test later gives it. Idempotent. */
+export function screenConsoleMock(level, mock) {
+    if (!vi.isMockFunction(mock))
+        return;
+    const marked = mock;
+    if (WRAPPED_MOCKS.has(mock))
+        return;
+    WRAPPED_MOCKS.add(mock);
+    const setImpl = marked.mockImplementation.bind(mock);
+    const setImplOnce = marked.mockImplementationOnce.bind(mock);
+    marked.mockImplementation = (next) => setImpl(screened(level, next));
+    marked.mockImplementationOnce = (next) => setImplOnce(screened(level, next));
+}
+/** Reads the calls a console mock recorded since the last scan. */
+export function scanConsoleCalls(level, mock) {
+    if (!vi.isMockFunction(mock))
+        return;
+    const s = state();
+    const calls = mock.mock.calls;
+    const from = s.scannedUpTo.get(mock) ?? 0;
+    const start = calls.length < from ? 0 : from;
+    for (const args of calls.slice(start))
+        screenConsoleCall(level, args);
+    s.scannedUpTo.set(mock, calls.length);
+}
+function isLevel(prop) {
+    return prop === 'error' || prop === 'warn';
+}
+/** What a test put on `console.error` / `console.warn`, made to screen. */
+function adopt(level, value) {
+    if (typeof value !== 'function')
+        return value;
+    if (SCREENING.has(value))
+        return value;
+    if (vi.isMockFunction(value)) {
+        screenConsoleMock(level, value);
+        return value;
+    }
+    return screened(level, value);
+}
+/** Installs the screening console once per test context, with the repo's own allowed warnings. */
+export function installReactWarningGuard(repoAllowed = []) {
+    const s = state();
+    s.repoAllowed = [...repoAllowed];
+    if (s.installed)
+        return;
+    s.installed = true;
+    const real = globalThis.console;
+    real.error = screened('error', real.error.bind(real));
+    real.warn = screened('warn', real.warn.bind(real));
+    globalThis.console = new Proxy(real, {
+        set(target, prop, value) {
+            return Reflect.set(target, prop, isLevel(prop) ? adopt(prop, value) : value);
+        },
+        defineProperty(target, prop, descriptor) {
+            if (isLevel(prop) && 'value' in descriptor) {
+                return Reflect.defineProperty(target, prop, { ...descriptor, value: adopt(prop, descriptor.value) });
+            }
+            return Reflect.defineProperty(target, prop, descriptor);
+        },
+    });
+}
+/** Lets the current test provoke warnings matching `pattern`. */
+export function allowReactWarnings(pattern) {
+    state().allowed.push(pattern);
+}
+/** The warnings caught since the last take (after a final scan of any console mock), cleared; allowances reset. */
+export function takeReactWarnings() {
+    scanConsoleCalls('error', console.error);
+    scanConsoleCalls('warn', console.warn);
+    const s = state();
+    const list = [...s.caught];
+    s.caught.clear();
+    s.allowed = [];
+    return list;
+}

package/dist/setup/server-only-stub.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/setup/server-only-stub.js

@@ -0,0 +1,2 @@
+// `server-only` throws when it is bundled for a browser. A test runs server code in Node, so it resolves here instead.
+export {};

package/dist/setup/setup-file.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/setup/setup-file.js

@@ -0,0 +1,44 @@
+/**
+ * The kit's worker setup file: `setupFiles[0]` of a config built by `testKitConfig`. In order, for every test file:
+ * strip credentials, refuse a production or `.env*` database, block the network, screen React warnings, and under jsdom
+ * install the DOM helpers. After each test it fails the test on a caught React warning or a refused request.
+ */
+import { afterEach, beforeAll, inject } from 'vitest';
+import { stripCredentials } from "./credentials.js";
+import { assertSafeDatabaseEnv, databaseHostsIn } from "./database.js";
+import { installDom } from "./dom.js";
+import { allowNetworkHosts, installNetworkGuard, takeNetworkViolations } from "./network.js";
+import { installReactWarningGuard, takeReactWarnings } from "./react-warnings.js";
+const provided = inject('testKit');
+if (!provided) {
+    throw new Error('test-kit: this setup file needs the options testKitConfig() provides; build the config with it.');
+}
+stripCredentials(process.env, { keep: provided.keepEnv, extra: provided.stripEnv });
+const rules = { productionHosts: provided.productionHosts, protectedPlaces: provided.protectedPlaces };
+assertSafeDatabaseEnv(process.env, rules);
+installNetworkGuard([...provided.allowHosts, ...(provided.allowDatabaseHosts ? databaseHostsIn(process.env) : [])]);
+installReactWarningGuard(provided.allowedWarnings.map((e) => ({ pattern: new RegExp(e.pattern), ...(e.file ? { file: e.file } : {}) })));
+// A repo's own setup file, which runs after this one, may set the test database URL: ask again before the tests.
+beforeAll(() => {
+    assertSafeDatabaseEnv(process.env, rules);
+    if (provided.allowDatabaseHosts)
+        allowNetworkHosts(...databaseHostsIn(process.env));
+});
+// Registered before the DOM cleanup, so it runs after it (Vitest runs afterEach hooks last-registered first): a warning
+// the unmount prints still fails the test.
+afterEach(() => {
+    const warnings = takeReactWarnings();
+    const refused = takeNetworkViolations();
+    const parts = [];
+    if (warnings.length > 0) {
+        parts.push('React warned during this test (or just before it, from work an earlier test left running). Fix it, or allow it ' +
+            "in this test with allowReactWarnings(/pattern/) from '@catalystiq/test-kit/setup'.\n\n" +
+            warnings.join('\n\n'));
+    }
+    if (refused.length > 0) {
+        parts.push('This test tried to reach the network outside its allow-list (test-kit network guard):\n' + refused.join('\n'));
+    }
+    if (parts.length > 0)
+        throw new Error(parts.join('\n\n'));
+});
+await installDom();

package/package.json

@@ -1,6 +1,109 @@
 {
   "name": "@catalystiq/test-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Shared test setup for Vitest, a fake MCP Apps host for jsdom and Playwright, and the local Neon test-database run.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getcatalystiq/test-kit.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    "./setup": {
+      "types": "./dist/setup/index.d.ts",
+      "import": "./dist/setup/index.js"
+    },
+    "./setup/config": {
+      "types": "./dist/setup/config.d.ts",
+      "import": "./dist/setup/config.js",
+      "default": "./dist/setup/config.js"
+    },
+    "./setup/dom": {
+      "types": "./dist/setup/dom.d.ts",
+      "import": "./dist/setup/dom.js"
+    },
+    "./setup/vitest-setup": "./dist/setup/setup-file.js",
+    "./mcp-apps-host": {
+      "types": "./dist/mcp-apps-host/index.d.ts",
+      "import": "./dist/mcp-apps-host/index.js"
+    },
+    "./mcp-apps-host/playwright": {
+      "types": "./dist/mcp-apps-host/playwright.d.ts",
+      "import": "./dist/mcp-apps-host/playwright.js"
+    },
+    "./neon-test-db": {
+      "types": "./dist/neon-test-db/neon-test-db.d.mts",
+      "import": "./dist/neon-test-db/neon-test-db.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "tk-check-bundle": "dist/bin/check-bundle.js",
+    "tk-check-allowlist": "dist/bin/check-allowlist.js",
+    "tk-neon-test-db": "dist/neon-test-db/neon-test-db.mjs"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && node scripts/copy-docs.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:browser": "playwright test && TK_BROWSER=1 vitest run test/browser-host-rules.test.ts",
+    "prepublishOnly": "npm run typecheck && npm run build",
+    "smoke:package": "npm run build && node scripts/smoke-package.mjs"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.50",
+    "@testing-library/jest-dom": ">=6",
+    "@testing-library/react": ">=16",
+    "vitest": "^4.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
+    "@testing-library/jest-dom": {
+      "optional": true
+    },
+    "@testing-library/react": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.5",
+    "@modelcontextprotocol/client": "2.4.0",
+    "@modelcontextprotocol/core": "2.4.0",
+    "@modelcontextprotocol/ext-apps": "2.0.4",
+    "@modelcontextprotocol/server": "2.4.0",
+    "@playwright/test": "1.65.0",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/jest-dom": "7.0.1",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "22.20.5",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "esbuild": "0.28.2",
+    "eslint": "9.39.5",
+    "jsdom": "30.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.72.1",
+    "vitest": "4.1.12",
+    "zod": "4.6.7"
+  }
+}