@provino/env-jsdom 0.0.0-stage → 0.1.0-rc.0
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 +21 -0
- package/README.md +8 -2
- package/dist/index.d.ts +50 -0
- package/dist/index.js +200 -0
- package/package.json +43 -3
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
|
-
#
|
|
1
|
+
# @provino/env-jsdom
|
|
2
2
|
|
|
3
|
-
|
|
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 that is pre-alpha and not on npm yet. 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)
|
package/dist/index.d.ts
ADDED
|
@@ -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
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0-rc.0",
|
|
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.0",
|
|
32
|
+
"@provino/types": "0.1.0-rc.0"
|
|
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
|
}
|