@ctrl/dom-jest-environment 0.1.2 → 0.1.3

package/dist/index.js

@@ -1,276 +1 @@
-import { constants, createContext } from "node:vm";
-import { LegacyFakeTimers, ModernFakeTimers } from "@jest/fake-timers";
-import { ModuleMocker } from "jest-mock";
-import { installCommonGlobals } from "jest-util";
-import * as dom from "@ctrl/dom";
-import * as internal from "@ctrl/dom/internal";
-
-// src/failure-snapshot.ts
-/** The values of CTRL_DOM_DEBUG that turn agent mode on (agent-debug.ts, envDebugFormat). */
-function debugEnabled() {
-	const value = process.env.CTRL_DOM_DEBUG?.trim().toLowerCase();
-	return value === "aria" || value === "compact" || value === "html";
-}
-/** A `handleTestEvent` for the environment, or undefined when CTRL_DOM_DEBUG is off. */
-function failureSnapshotHandler(getDocument) {
-	if (!debugEnabled()) return void 0;
-	let agent = null;
-	return async (event) => {
-		if (event.name !== "test_start" && event.name !== "test_fn_failure") return;
-		agent ??= await import("@ctrl/dom/testing-library/agent");
-		const document = getDocument();
-		if (document == null) return;
-		if (event.name === "test_start") {
-			agent.resetFailureSnapshot(document);
-			return;
-		}
-		const error = event.error;
-		const message = error !== null && typeof error === "object" && typeof error.message === "string" ? error.message : "";
-		const snapshot = agent.captureFailureSnapshot(document);
-		if (snapshot !== null) agent.appendToErrorMessage(error, agent.formatFailureSnapshot(snapshot, message));
-	};
-}
-
-// src/index.ts
-/** The vm-global key the bridges and shims read. */
-const CTRL_DOM_MODULES = Symbol.for("ctrl-dom.dom.modules");
-const JSDOM_ABSENT_GLOBALS = /* @__PURE__ */ new Set([
-	"fetch",
-	"Request",
-	"Response"
-]);
-const NODE_GLOBAL_DENY = /* @__PURE__ */ new Set([
-	"GLOBAL",
-	"root",
-	"global",
-	"globalThis",
-	"Buffer",
-	"ArrayBuffer",
-	"Uint8Array",
-	"jest-symbol-do-not-touch",
-	"localStorage",
-	"sessionStorage"
-]);
-const LAZY_NODE_GLOBALS = /* @__PURE__ */ new Map([
-	["fetch", true],
-	["Request", false],
-	["Response", false],
-	["Headers", false],
-	["FormData", false],
-	["WebSocket", false],
-	["EventSource", false],
-	["MessageEvent", false],
-	["CloseEvent", false]
-]);
-let nodeGlobals = null;
-/** [name, descriptor] for Node's globals (descriptor null: lazy, see LAZY_NODE_GLOBALS). */
-function nodeGlobalDescriptors() {
-	return nodeGlobals ??= Object.getOwnPropertyNames(globalThis).filter((name) => !NODE_GLOBAL_DENY.has(name)).map((name) => [name, LAZY_NODE_GLOBALS.has(name) ? null : Object.getOwnPropertyDescriptor(globalThis, name)]);
-}
-/**
-* Copy Node's globals onto the test global the way jest-environment-node does: configurable ones
-* as getters that read the outer value on first use and replace themselves with a data property;
-* names the new realm already defines (Object, Array, ...) keep the realm's own.
-*/
-function installNodeGlobals(global, skip) {
-	const realmOwn = new Set(Object.getOwnPropertyNames(global));
-	const host = globalThis;
-	for (const [name, descriptor] of nodeGlobalDescriptors()) {
-		if (realmOwn.has(name) || skip.has(name)) continue;
-		const enumerable = descriptor === null ? LAZY_NODE_GLOBALS.get(name) : descriptor.enumerable;
-		if (descriptor === null || descriptor.configurable) {
-			const settle = (value) => Object.defineProperty(global, name, {
-				value,
-				writable: true,
-				enumerable,
-				configurable: true
-			});
-			Object.defineProperty(global, name, {
-				get() {
-					const value = host[name];
-					settle(value);
-					return value;
-				},
-				set: settle,
-				enumerable,
-				configurable: true
-			});
-		} else Object.defineProperty(global, name, descriptor);
-	}
-	global.global = global;
-	global.Buffer = Buffer;
-	global.ArrayBuffer = ArrayBuffer;
-	global.Uint8Array = Uint8Array;
-}
-/** Same default URL as jest-environment-jsdom. */
-const DEFAULT_URL = "http://localhost/";
-/**
-* Exceptions nobody handled (listener exceptions, reportError(), React's uncaught errors) are
-* re-emitted on the worker process, which jest-circus turns into a test failure — what
-* jest-environment-jsdom does with its window "error" listener.
-* https://html.spec.whatwg.org/#report-an-exception
-*/
-function reportToHost(error) {
-	process.emit("uncaughtException", error, "uncaughtException");
-}
-/**
-* jsdom's "Not implemented" diagnostics (navigation, window.alert, form submission, ...; only
-* under the jsdom profiles, @ctrl/dom window/not-implemented.ts), forwarded to the test file's
-* console as jest-environment-jsdom does: with jsdom 26 (`sendTo` omitting jsdom errors, then
-* its "jsdomError" listener) once, as the Error; with jsdom 27+ (`forwardTo`, then the same
-* listener) as `error.stack`, then as the Error.
-* https://github.com/jestjs/jest/blob/v30.4.1/packages/jest-environment-jsdom-abstract/src/index.ts
-*/
-function forwardNotImplemented(global) {
-	return (error, compat) => {
-		const console = global.console;
-		if (compat !== "jsdom-26") console.error(error.stack, error.detail);
-		console.error(error);
-	};
-}
-const ERROR_CONSTRUCTORS = [
-	"Error",
-	"TypeError",
-	"RangeError",
-	"SyntaxError",
-	"ReferenceError",
-	"EvalError",
-	"URIError"
-];
-/**
-* Our DOM runs in the worker's realm while test code runs in the vm context, so a TypeError
-* thrown by @ctrl/dom is not `instanceof` the test realm's TypeError (`expect(fn).toThrow(TypeError)`
-* would fail). Give the context's error constructors a Symbol.hasInstance that also accepts the
-* outer realm's instances; errors created in the context keep working as before.
-*/
-function bridgeErrorRealms(global) {
-	for (const name of ERROR_CONSTRUCTORS) {
-		const inner = global[name];
-		const outer = globalThis[name];
-		if (typeof inner !== "function" || inner === outer) continue;
-		Object.defineProperty(inner, Symbol.hasInstance, {
-			value: (value) => Function.prototype[Symbol.hasInstance].call(inner, value) || value instanceof outer,
-			configurable: true
-		});
-	}
-}
-function createDom(window) {
-	return {
-		window,
-		reconfigure(settings) {
-			if (settings.windowTop !== void 0) throw new TypeError("@ctrl/dom-jest-environment: dom.reconfigure() does not support windowTop");
-			if (settings.url === void 0) return;
-			const url = URL.parse(String(settings.url));
-			if (url === null) throw new TypeError(`Could not parse "${settings.url}" as a URL`);
-			window._setURL(url);
-		}
-	};
-}
-var CtrlDomEnvironment = class {
-	context;
-	global;
-	fakeTimers;
-	fakeTimersModern;
-	moduleMocker;
-	customExportConditions;
-	ctrlDomWindow;
-	/** jest-environment-jsdom's `dom`, reduced to what suites use (see CtrlDomDom). */
-	dom;
-	/** The file's timers (see CtrlDomTestEnvironmentOptions.timeSkip). */
-	clock;
-	/** Stops adding the page and the clock to @ctrl/sentry-tests' failure reports. */
-	#unsubscribeFailures = null;
-	constructor(config, _environmentContext) {
-		const { projectConfig } = config;
-		const { customExportConditions, nodeFetch, timeSkip, ...windowOptions } = projectConfig.testEnvironmentOptions ?? {};
-		this.customExportConditions = customExportConditions ?? ["browser"];
-		const context = createContext(constants.DONT_CONTEXTIFY);
-		this.context = context;
-		const global = context;
-		this.global = global;
-		installNodeGlobals(global, nodeFetch === true ? /* @__PURE__ */ new Set() : JSDOM_ABSENT_GLOBALS);
-		installCommonGlobals(this.global, projectConfig.globals);
-		const realmSymbol = global.Symbol;
-		if (!("asyncDispose" in realmSymbol)) {
-			Object.defineProperty(realmSymbol, "asyncDispose", { value: Symbol.for("nodejs.asyncDispose") });
-			Object.defineProperty(realmSymbol, "dispose", { value: Symbol.for("nodejs.dispose") });
-		}
-		global.Error.stackTraceLimit = 100;
-		const window = dom.createWindow({
-			...windowOptions,
-			compat: windowOptions.compat ?? "jsdom-26",
-			url: windowOptions.url ?? DEFAULT_URL
-		});
-		this.ctrlDomWindow = window;
-		this.dom = createDom(window);
-		internal.captureInterfaceBaseline();
-		dom.installGlobals(window, global);
-		Object.defineProperty(global, CTRL_DOM_MODULES, {
-			value: {
-				dom,
-				internal
-			},
-			configurable: true,
-			enumerable: false,
-			writable: false
-		});
-		bridgeErrorRealms(global);
-		const envSkip = process.env.CTRL_DOM_TIME_SKIP;
-		const skip = envSkip === "1" ? true : envSkip === "0" ? false : timeSkip !== false;
-		this.clock = internal.installClock(new internal.VirtualClock({ skip }), global).clock;
-		this.moduleMocker = new ModuleMocker(this.global);
-		this.fakeTimers = new LegacyFakeTimers({
-			config: projectConfig,
-			global: this.global,
-			moduleMocker: this.moduleMocker,
-			timerConfig: {
-				idToRef: (id) => id,
-				refToId: (ref) => ref
-			}
-		});
-		this.fakeTimersModern = new ModernFakeTimers({
-			config: projectConfig,
-			global: this.global
-		});
-		internal.guardInterfaceDefinitions(global);
-		internal.setUncaughtExceptionHandler(reportToHost);
-		internal.setNotImplementedHandler(forwardNotImplemented(global));
-		const onTestEvent = failureSnapshotHandler(() => this.ctrlDomWindow?.document);
-		if (onTestEvent !== void 0) this.handleTestEvent = onTestEvent;
-		this.#unsubscribeFailures = internal.subscribeTestFailures(() => this.ctrlDomWindow?.document);
-	}
-	async setup() {}
-	exportConditions() {
-		return this.customExportConditions;
-	}
-	getVmContext() {
-		return this.context;
-	}
-	/**
-	* Closes the window (cancelling its timers, frames, idle callbacks and tasks) and undoes the file's
-	* patches to the shared interface prototypes. The globals stay installed, like under
-	* jest-environment-jsdom where the global *is* the window: work a test file left behind (React's
-	* scheduler runs on Node's setImmediate) can still read `window`/`document` instead of
-	* crashing the worker with a ReferenceError. The vm context is discarded with the file.
-	*/
-	async teardown() {
-		this.#unsubscribeFailures?.();
-		this.#unsubscribeFailures = null;
-		internal.setUncaughtExceptionHandler(null);
-		internal.setNotImplementedHandler(null);
-		this.fakeTimers?.dispose();
-		this.fakeTimersModern?.dispose();
-		this.ctrlDomWindow?.close();
-		this.ctrlDomWindow = null;
-		this.clock?.dispose();
-		this.clock = null;
-		this.dom = null;
-		internal.restoreInterfaces();
-		this.context = null;
-		this.fakeTimers = null;
-		this.fakeTimersModern = null;
-	}
-};
-const TestEnvironment = CtrlDomEnvironment;
-
-export { CTRL_DOM_MODULES, TestEnvironment, CtrlDomEnvironment as default };
+import{constants as e,createContext as t}from"node:vm";import{LegacyFakeTimers as n,ModernFakeTimers as r}from"@jest/fake-timers";import{ModuleMocker as i}from"jest-mock";import{installCommonGlobals as a}from"jest-util";import*as o from"@ctrl/dom";import*as s from"@ctrl/dom/internal";function debugEnabled(){let e=process.env.CTRL_DOM_DEBUG?.trim().toLowerCase();return e===`aria`||e===`compact`||e===`html`}function failureSnapshotHandler(e){if(!debugEnabled())return;let t=null;return async n=>{if(n.name!==`test_start`&&n.name!==`test_fn_failure`)return;t??=await import(`@ctrl/dom/testing-library/agent`);let r=e();if(r==null)return;if(n.name===`test_start`){t.resetFailureSnapshot(r);return}let i=n.error,a=typeof i==`object`&&i&&typeof i.message==`string`?i.message:``,o=t.captureFailureSnapshot(r);o!==null&&t.appendToErrorMessage(i,t.formatFailureSnapshot(o,a))}}const c=Symbol.for(`ctrl-dom.dom.modules`),l=/* @__PURE__ */ new Set([`fetch`,`Request`,`Response`]),u=/* @__PURE__ */ new Set([`GLOBAL`,`root`,`global`,`globalThis`,`Buffer`,`ArrayBuffer`,`Uint8Array`,`jest-symbol-do-not-touch`,`localStorage`,`sessionStorage`]),d=/* @__PURE__ */ new Map([[`fetch`,!0],[`Request`,!1],[`Response`,!1],[`Headers`,!1],[`FormData`,!1],[`WebSocket`,!1],[`EventSource`,!1],[`MessageEvent`,!1],[`CloseEvent`,!1]]);let f=null;function nodeGlobalDescriptors(){return f??=Object.getOwnPropertyNames(globalThis).filter(e=>!u.has(e)).map(e=>[e,d.has(e)?null:Object.getOwnPropertyDescriptor(globalThis,e)])}function installNodeGlobals(e,t){let n=new Set(Object.getOwnPropertyNames(e)),r=globalThis;for(let[i,a]of nodeGlobalDescriptors()){if(n.has(i)||t.has(i))continue;let o=a===null?d.get(i):a.enumerable;if(a===null||a.configurable){let settle=t=>Object.defineProperty(e,i,{value:t,writable:!0,enumerable:o,configurable:!0});Object.defineProperty(e,i,{get(){let e=r[i];return settle(e),e},set:settle,enumerable:o,configurable:!0})}else Object.defineProperty(e,i,a)}e.global=e,e.Buffer=Buffer,e.ArrayBuffer=ArrayBuffer,e.Uint8Array=Uint8Array}function reportToHost(e){process.emit(`uncaughtException`,e,`uncaughtException`)}function forwardNotImplemented(e){return(t,n)=>{let r=e.console;n!==`jsdom-26`&&r.error(t.stack,t.detail),r.error(t)}}const p=[`Error`,`TypeError`,`RangeError`,`SyntaxError`,`ReferenceError`,`EvalError`,`URIError`];function bridgeErrorRealms(e){for(let t of p){let n=e[t],r=globalThis[t];typeof n==`function`&&n!==r&&Object.defineProperty(n,Symbol.hasInstance,{value:e=>Function.prototype[Symbol.hasInstance].call(n,e)||e instanceof r,configurable:!0})}}function createDom(e){return{window:e,reconfigure(t){if(t.windowTop!==void 0)throw TypeError(`@ctrl/dom-jest-environment: dom.reconfigure() does not support windowTop`);if(t.url===void 0)return;let n=URL.parse(String(t.url));if(n===null)throw TypeError(`Could not parse "${t.url}" as a URL`);e._setURL(n)}}}var CtrlDomEnvironment=class{context;global;fakeTimers;fakeTimersModern;moduleMocker;customExportConditions;ctrlDomWindow;dom;clock;#e=null;constructor(u,d){let{projectConfig:f}=u,{customExportConditions:p,nodeFetch:m,timeSkip:h,...g}=f.testEnvironmentOptions??{};this.customExportConditions=p??[`browser`];let _=t(e.DONT_CONTEXTIFY);this.context=_;let v=_;this.global=v,installNodeGlobals(v,m===!0?/* @__PURE__ */ new Set:l),a(this.global,f.globals);let y=v.Symbol;`asyncDispose`in y||(Object.defineProperty(y,"asyncDispose",{value:Symbol.for(`nodejs.asyncDispose`)}),Object.defineProperty(y,"dispose",{value:Symbol.for(`nodejs.dispose`)})),v.Error.stackTraceLimit=100;let b=o.createWindow({...g,compat:g.compat??`jsdom-26`,url:g.url??`http://localhost/`});this.ctrlDomWindow=b,this.dom=createDom(b),s.captureInterfaceBaseline(),o.installGlobals(b,v),Object.defineProperty(v,c,{value:{dom:o,internal:s},configurable:!0,enumerable:!1,writable:!1}),bridgeErrorRealms(v);let x=process.env.CTRL_DOM_TIME_SKIP,S=x===`1`||x!==`0`&&h!==!1;this.clock=s.installClock(new s.VirtualClock({skip:S}),v).clock,this.moduleMocker=new i(this.global),this.fakeTimers=new n({config:f,global:this.global,moduleMocker:this.moduleMocker,timerConfig:{idToRef:e=>e,refToId:e=>e}}),this.fakeTimersModern=new r({config:f,global:this.global}),s.guardInterfaceDefinitions(v),s.setUncaughtExceptionHandler(reportToHost),s.setNotImplementedHandler(forwardNotImplemented(v));let C=failureSnapshotHandler(()=>this.ctrlDomWindow?.document);C!==void 0&&(this.handleTestEvent=C),this.#e=s.subscribeTestFailures(()=>this.ctrlDomWindow?.document)}async setup(){}exportConditions(){return this.customExportConditions}getVmContext(){return this.context}async teardown(){this.#e?.(),this.#e=null,s.setUncaughtExceptionHandler(null),s.setNotImplementedHandler(null),this.fakeTimers?.dispose(),this.fakeTimersModern?.dispose(),this.ctrlDomWindow?.close(),this.ctrlDomWindow=null,this.clock?.dispose(),this.clock=null,this.dom=null,s.restoreInterfaces(),this.context=null,this.fakeTimers=null,this.fakeTimersModern=null}};const m=CtrlDomEnvironment;export{c as CTRL_DOM_MODULES,m as TestEnvironment,CtrlDomEnvironment as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl/dom-jest-environment",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Jest environment for @ctrl/dom, the fast DOM for testing React components (testEnvironment: \"@ctrl/dom-jest-environment\", or preset: \"@ctrl/dom\").",
   "keywords": [
     "jest",
@@ -52,7 +52,7 @@
     "jest-util": "30.4.1"
   },
   "peerDependencies": {
-    "@ctrl/dom": "^0.1.4",
+    "@ctrl/dom": "^0.1.5",
     "jest": ">=30.0.0"
   }
 }