@provino/env-jsdom 0.0.0-stage → 0.1.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pixel Perfect Software
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,9 @@
1
- # Temporary Holding Version
1
+ # @provino/env-jsdom
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Provino's own jsdom test environment: a fresh window for each test file, put on the worker's global and removed exactly afterwards. `jsdom` (`>=26 <31`) is an optional peer dependency. This environment serves projects that use Provino's own config; a Jest project's `testEnvironment: 'jsdom'` runs the project's own `jest-environment-jsdom` instead.
4
+
5
+ This package is a building block of [Provino](https://github.com/pixel-perfect-software/provino), a test runner for Jest projects, on npm as [`provino`](https://www.npmjs.com/package/provino). The `provino` package ships every `@provino/*` package inlined in one bundle, so you install `provino`, not this package.
6
+
7
+ **Versioning:** this package's public API is held to semver before 1.0: its API report is committed in the repository, under `etc/`, and a change to a `@public` signature needs a changeset.
8
+
9
+ [MIT](https://github.com/pixel-perfect-software/provino/blob/main/LICENSE)
@@ -0,0 +1,50 @@
1
+ import { Environment, EnvironmentOptionsMap } from "@provino/types";
2
+ /**
3
+ * The options of the jsdom environment: `url`, `html`, `userAgent`, `pretendToBeVisual`,
4
+ * `customExportConditions` (read by the policy's `environmentConditions`, not here) and `jsdom`,
5
+ * anything else the `JSDOM` constructor takes.
6
+ * @public
7
+ */
8
+ type JsdomEnvironmentOptions = EnvironmentOptionsMap["jsdom"];
9
+ /**
10
+ * The jsdom test environment.
11
+ *
12
+ * `prepare` imports the project's `jsdom` once per worker (a missing package is
13
+ * `ENV_JSDOM_NOT_INSTALLED`). `setup` makes a new `JSDOM` from the options, puts its window on the
14
+ * worker's `globalThis` with `populateGlobal` and returns that global. `teardown` closes the
15
+ * window and puts the global back from a descriptor snapshot taken before the window went on
16
+ * (what `populateGlobal` changed and whatever the test added or changed), so afterwards the
17
+ * global's property names and every original descriptor equal
18
+ * what `setup` saw. A key it cannot restore is a warning, not a failure (decision D22): the
19
+ * teardown returns a report naming it.
20
+ *
21
+ * Window `error` events with no listener of the test's own become uncaught exceptions.
22
+ *
23
+ * With `processObject: 'per-file'` in the context, `setup` also installs a copy of the worker's
24
+ * `process` for the file (listeners and an `env` of its own), which teardown removes.
25
+ *
26
+
27
+ * Only the `worker` realm is supported: `setup` throws `ENV_JSDOM_REALM_UNSUPPORTED` for
28
+ * `context`, which needs the `realm` isolation tier (T2.8).
29
+ *
30
+ * Not copied from Vitest: its wrappers for `URL` and `Blob`/`FormData` interop between Node's
31
+ * `fetch` and jsdom's `Blob`; a jsdom `Blob` is not accepted as a `fetch` body here.
32
+ * @public
33
+ */
34
+ export declare const jsdomEnvironment: Environment<"jsdom", JsdomEnvironmentOptions>;
35
+ /**
36
+ * Stable codes for `@provino/env-jsdom` errors, so callers and tests assert on the code, not the
37
+ * text.
38
+ * @public
39
+ */
40
+ type JsdomEnvironmentErrorCode = "ENV_JSDOM_NOT_INSTALLED" | "ENV_JSDOM_NOT_PREPARED" | "ENV_JSDOM_REALM_UNSUPPORTED";
41
+ /**
42
+ * An error from the jsdom environment. A global it cannot restore is not an error: `teardown`
43
+ * reports those (decision D22).
44
+ * @public
45
+ */
46
+ export declare class JsdomEnvironmentError extends Error {
47
+ readonly code: JsdomEnvironmentErrorCode;
48
+ constructor(code: JsdomEnvironmentErrorCode, message: string, options?: ErrorOptions);
49
+ }
50
+ export type { JsdomEnvironmentErrorCode, JsdomEnvironmentOptions };
package/dist/index.js ADDED
@@ -0,0 +1,200 @@
1
+ import worker from "node:process";
2
+ import { createFileProcess, leakReport, populateGlobal, snapshotProperties } from "@provino/env-shared";
3
+
4
+ // src/errors.ts
5
+ /**
6
+ * An error from the jsdom environment. A global it cannot restore is not an error: `teardown`
7
+ * reports those (decision D22).
8
+ * @public
9
+ */
10
+ var JsdomEnvironmentError = class extends Error {
11
+ code;
12
+ constructor(code, message, options) {
13
+ super(message, options);
14
+ this.name = "JsdomEnvironmentError";
15
+ this.code = code;
16
+ }
17
+ };
18
+
19
+ // src/window.ts
20
+ function forwardConsole(virtualConsole, to) {
21
+ const forwarding = virtualConsole;
22
+ if (typeof forwarding.forwardTo === "function") forwarding.forwardTo(to);
23
+ else forwarding.sendTo?.(to);
24
+ }
25
+ /**
26
+ * Where a user agent goes, so it is set without turning subresource loading on (a page would fetch
27
+ * its scripts and images):
28
+ * - jsdom 26 to 29 take `resources`: a `ResourceLoader` carries the user agent, and a subclass whose
29
+ * `fetch` returns `null` loads nothing. (A plain object is refused there, and `'usable'` loads.)
30
+ * - jsdom 30 has no `ResourceLoader`, and any `resources` value turns loading on
31
+ * (`loadSubresources: resources !== undefined`), so the user agent is defined on `navigator`
32
+ * after construction instead. XHR keeps jsdom's own user agent header.
33
+ */
34
+ function userAgentOptions(jsdom, userAgent) {
35
+ const { ResourceLoader } = jsdom;
36
+ if (typeof ResourceLoader === "function") {
37
+ class NoFetch extends ResourceLoader {
38
+ fetch() {
39
+ return null;
40
+ }
41
+ }
42
+ return { constructor: { resources: new NoFetch({ userAgent }) } };
43
+ }
44
+ return {
45
+ constructor: {},
46
+ after(dom) {
47
+ Object.defineProperty(dom.window.navigator, "userAgent", {
48
+ get: () => userAgent,
49
+ configurable: true,
50
+ enumerable: true
51
+ });
52
+ }
53
+ };
54
+ }
55
+ function createDom(jsdom, options, console) {
56
+ const virtualConsole = new jsdom.VirtualConsole();
57
+ forwardConsole(virtualConsole, console);
58
+ const agent = options.userAgent === void 0 ? void 0 : userAgentOptions(jsdom, options.userAgent);
59
+ const dom = new jsdom.JSDOM(options.html ?? "<!DOCTYPE html>", {
60
+ pretendToBeVisual: options.pretendToBeVisual ?? true,
61
+ runScripts: "dangerously",
62
+ url: options.url ?? "http://localhost:3000",
63
+ virtualConsole,
64
+ ...agent?.constructor,
65
+ ...options.jsdom
66
+ });
67
+ agent?.after?.(dom);
68
+ return dom;
69
+ }
70
+
71
+ // src/environment.ts
72
+ function isPrepared(value) {
73
+ return typeof value === "object" && value !== null && "JSDOM" in value && typeof value.JSDOM === "function" && "VirtualConsole" in value && typeof value.VirtualConsole === "function";
74
+ }
75
+ /**
76
+ * Node's own fetch family, which the window gets instead of jsdom's (jsdom has none, or one that
77
+ * can't take a Node body). Vitest overrides the same names.
78
+ */
79
+ const NODE_OVERRIDES = [
80
+ "fetch",
81
+ "Request",
82
+ "Response",
83
+ "Headers",
84
+ "AbortController",
85
+ "AbortSignal",
86
+ "URLSearchParams"
87
+ ];
88
+ /** Names jsdom lacks and Node has; copied when the window has none. */
89
+ const NODE_FILLS = [
90
+ "structuredClone",
91
+ "BroadcastChannel",
92
+ "MessageChannel",
93
+ "MessagePort",
94
+ "TextEncoder",
95
+ "TextDecoder"
96
+ ];
97
+ /**
98
+ * A window `error` event with no listener of the test's own is an uncaught exception, as in a
99
+ * browser's console (Jest and Vitest do the same): the event is prevented and the error goes to
100
+ * the process's `uncaughtException`, where the runtime charges it. Returns the way to remove it.
101
+ */
102
+ function bridgeErrors(win) {
103
+ let userListeners = 0;
104
+ const add = win.addEventListener.bind(win);
105
+ const remove = win.removeEventListener.bind(win);
106
+ const bridge = (event) => {
107
+ if (userListeners === 0 && event.error != null) {
108
+ event.preventDefault();
109
+ worker.emit("uncaughtException", event.error);
110
+ }
111
+ };
112
+ add("error", bridge);
113
+ const counted = (...args) => {
114
+ if (args[0] === "error") userListeners++;
115
+ return add(...args);
116
+ };
117
+ const uncounted = (...args) => {
118
+ if (args[0] === "error" && userListeners > 0) userListeners--;
119
+ return remove(...args);
120
+ };
121
+ win.addEventListener = counted;
122
+ win.removeEventListener = uncounted;
123
+ return () => {
124
+ remove("error", bridge);
125
+ };
126
+ }
127
+ /**
128
+ * The jsdom test environment.
129
+ *
130
+ * `prepare` imports the project's `jsdom` once per worker (a missing package is
131
+ * `ENV_JSDOM_NOT_INSTALLED`). `setup` makes a new `JSDOM` from the options, puts its window on the
132
+ * worker's `globalThis` with `populateGlobal` and returns that global. `teardown` closes the
133
+ * window and puts the global back from a descriptor snapshot taken before the window went on
134
+ * (what `populateGlobal` changed and whatever the test added or changed), so afterwards the
135
+ * global's property names and every original descriptor equal
136
+ * what `setup` saw. A key it cannot restore is a warning, not a failure (decision D22): the
137
+ * teardown returns a report naming it.
138
+ *
139
+ * Window `error` events with no listener of the test's own become uncaught exceptions.
140
+ *
141
+ * With `processObject: 'per-file'` in the context, `setup` also installs a copy of the worker's
142
+ * `process` for the file (listeners and an `env` of its own), which teardown removes.
143
+ *
144
+
145
+ * Only the `worker` realm is supported: `setup` throws `ENV_JSDOM_REALM_UNSUPPORTED` for
146
+ * `context`, which needs the `realm` isolation tier (T2.8).
147
+ *
148
+ * Not copied from Vitest: its wrappers for `URL` and `Blob`/`FormData` interop between Node's
149
+ * `fetch` and jsdom's `Blob`; a jsdom `Blob` is not accepted as a `fetch` body here.
150
+ * @public
151
+ */
152
+ const jsdomEnvironment = {
153
+ name: "jsdom",
154
+ realms: ["worker"],
155
+ async prepare() {
156
+ try {
157
+ const jsdom = await import("jsdom");
158
+ const { ResourceLoader } = jsdom;
159
+ return {
160
+ JSDOM: jsdom.JSDOM,
161
+ VirtualConsole: jsdom.VirtualConsole,
162
+ ...ResourceLoader === void 0 ? {} : { ResourceLoader }
163
+ };
164
+ } catch (cause) {
165
+ throw new JsdomEnvironmentError("ENV_JSDOM_NOT_INSTALLED", "The jsdom environment needs the 'jsdom' package (version 26 to 30): install it as a dev dependency.", { cause });
166
+ }
167
+ },
168
+ setup(context, prepared) {
169
+ if (context.realm !== "worker") throw new JsdomEnvironmentError("ENV_JSDOM_REALM_UNSUPPORTED", `The jsdom environment supports the 'worker' realm only, not '${context.realm}'. A vm-context window needs the 'realm' isolation tier (T2.8).`);
170
+ if (!isPrepared(prepared)) throw new JsdomEnvironmentError("ENV_JSDOM_NOT_PREPARED", "The jsdom environment's setup needs what its prepare returned.");
171
+ const dom = createDom(prepared, context.options, context.console);
172
+ const win = dom.window;
173
+ const clearErrors = bridgeErrors(win);
174
+ const nodeGlobals = globalThis;
175
+ const winGlobals = win;
176
+ winGlobals.Buffer = Buffer;
177
+ winGlobals.jsdom = dom;
178
+ for (const name of NODE_FILLS) if (nodeGlobals[name] !== void 0 && winGlobals[name] === void 0) winGlobals[name] = nodeGlobals[name];
179
+ for (const name of NODE_OVERRIDES) if (nodeGlobals[name] !== void 0) winGlobals[name] = nodeGlobals[name];
180
+ const snapshot = snapshotProperties(globalThis);
181
+ const populated = populateGlobal(globalThis, win, { bindFunctions: true });
182
+ if (context.processObject === "per-file") globalThis.process = createFileProcess();
183
+ return {
184
+ global: globalThis,
185
+ globalReads: populated,
186
+ teardown() {
187
+ let leaked = [];
188
+ try {
189
+ clearErrors();
190
+ win.close();
191
+ } finally {
192
+ leaked = snapshot.restore();
193
+ }
194
+ return leakReport(leaked);
195
+ }
196
+ };
197
+ }
198
+ };
199
+
200
+ export { JsdomEnvironmentError, jsdomEnvironment };
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
1
  {
2
2
  "name": "@provino/env-jsdom",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0-rc.1",
4
+ "description": "Provino's own jsdom test environment: a fresh window per file, put on the worker's global and removed exactly afterwards.",
5
+ "homepage": "https://github.com/pixel-perfect-software/provino#readme",
6
+ "bugs": {
7
+ "url": "https://github.com/pixel-perfect-software/provino/issues"
8
+ },
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/pixel-perfect-software/provino.git",
12
+ "directory": "packages/env-jsdom"
13
+ },
14
+ "license": "MIT",
15
+ "type": "module",
16
+ "sideEffects": false,
17
+ "exports": {
18
+ ".": {
19
+ "provino-source": "./src/index.ts",
20
+ "types": "./dist/index.d.ts",
21
+ "import": "./dist/index.js"
22
+ }
23
+ },
24
+ "files": [
25
+ "dist"
26
+ ],
27
+ "engines": {
28
+ "node": "^22.15.0 || >=24"
29
+ },
30
+ "dependencies": {
31
+ "@provino/env-shared": "0.1.0-rc.1",
32
+ "@provino/types": "0.1.0-rc.1"
33
+ },
34
+ "peerDependencies": {
35
+ "jsdom": ">=26 <31"
36
+ },
37
+ "devDependencies": {
38
+ "@types/jsdom": "30.0.0",
39
+ "jsdom": "30.1.3",
40
+ "jsdom-26": "npm:jsdom@26.1.0"
41
+ },
42
+ "scripts": {
43
+ "build": "tsdown --config ../../tooling/packaging/tsdown.config.ts",
44
+ "test": "node --test --conditions=provino-source \"src/**/*.test.ts\""
45
+ }
6
46
  }