jsdom
Hello world
`); console.log(dom.window.document.querySelector("p").textContent); // "Hello world" ``` (Note that jsdom will parse the HTML you pass it just like a browser does, including implied ``, ``, and `` tags.) The resulting object is an instance of the `JSDOM` class, which contains a number of useful properties and methods besides `window`. In general, it can be used to act on the jsdom from the "outside," doing things that are not possible with the normal DOM APIs. For simple cases, where you don't need any of this functionality, we recommend a coding pattern like ```js const { window } = new JSDOM(`...`); // or even const { document } = (new JSDOM(`...`)).window; ``` Full documentation on everything you can do with the `JSDOM` class is below, in the section "`JSDOM` Object API". ## Customizing jsdom The `JSDOM` constructor accepts a second parameter which can be used to customize your jsdom in the following ways. ### Simple options ```js const dom = new JSDOM(``, { url: "https://example.org/", referrer: "https://example.com/", contentType: "text/html", includeNodeLocations: true, storageQuota: 10000000 }); ``` - `url` sets the value returned by `window.location`, `document.URL`, and `document.documentURI`, and affects things like resolution of relative URLs within the document and the same-origin restrictions and referrer used while fetching subresources. It defaults to `"about:blank"`. - `referrer` just affects the value read from `document.referrer`. It defaults to no referrer (which reflects as the empty string). - `contentType` affects the value read from `document.contentType`, as well as how the document is parsed: as HTML or as XML. Values that are not a [HTML MIME type](https://mimesniff.spec.whatwg.org/#html-mime-type) or an [XML MIME type](https://mimesniff.spec.whatwg.org/#xml-mime-type) will throw. It defaults to `"text/html"`. If a `charset` parameter is present, it can affect [binary data processing](#encoding-sniffing). - `includeNodeLocations` preserves the location info produced by the HTML parser, allowing you to retrieve it with the `nodeLocation()` method (described below). It also ensures that line numbers reported in exception stack traces for code running inside ` `); // The script will not be executed, by default: console.log(dom.window.document.getElementById("content").children.length); // 0 ``` To enable executing scripts inside the page, you can use the `runScripts: "dangerously"` option: ```js const dom = new JSDOM(` `, { runScripts: "dangerously" }); // The script will be executed and modify the DOM: console.log(dom.window.document.getElementById("content").children.length); // 1 ``` Again we emphasize to only use this when feeding jsdom code you know is safe. If you use it on arbitrary user-supplied code, or code from the Internet, you are effectively running untrusted Node.js code, and your machine could be compromised. If you want to execute _external_ scripts, included via ` `, { runScripts: "outside-only" }); // run a script outside of JSDOM: dom.window.eval('document.getElementById("content").append(document.createElement("p"));'); console.log(dom.window.document.getElementById("content").children.length); // 1 console.log(dom.window.document.getElementsByTagName("hr").length); // 0 console.log(dom.window.document.getElementsByTagName("p").length); // 1 ``` This is turned off by default for performance reasons, but is safe to enable. Note that in the default configuration, without setting `runScripts`, the values of `window.Array`, `window.eval`, etc. will be the same as those provided by the outer Node.js environment. That is, `window.eval === eval` will hold, so `window.eval` will not run scripts in a useful way. We strongly advise against trying to "execute scripts" by mashing together the jsdom and Node global environments (e.g. by doing `global.window = dom.window`), and then executing scripts or test code inside the Node global environment. Instead, you should treat jsdom like you would a browser, and run all scripts and tests that need access to a DOM inside the jsdom environment, using `window.eval` or `runScripts: "dangerously"`. This might require, for example, creating a browserify bundle to execute as a ``, { url: "https://example.com/", runScripts: "dangerously", resources: { userAgent: "Mellblomenator/9000", dispatcher: new ProxyAgent("http://127.0.0.1:9001"), interceptors: [ requestInterceptor((request, context) => { // Override the contents of this script to do something unusual. if (request.url === "https://example.com/some-specific-script.js") { return new Response("window.someGlobal = 5;", { headers: { "Content-Type": "application/javascript" } }); } // Return undefined to let the request proceed normally }) ] } }); ``` The context object passed to the interceptor includes `element` (the DOM element that initiated the request, or `null` for requests that are not from DOM elements). For example: ```js requestInterceptor((request, { element }) => { if (element) { console.log(`Element ${element.localName} is requesting ${request.url}`); } // Return undefined to let the request proceed normally }) ``` To be clear on the flow: when something in your jsdom fetches resources, first the request is set up by jsdom, then it is passed through any `interceptors` in the order provided, then it reaches any provided `dispatcher` (defaulting to [`undici`'s global dispatcher](https://undici.nodejs.org/#/?id=undicigetglobaldispatcher)). If you use jsdom's `requestInterceptor()`, returning promise fulfilled with a `Response` will prevent any further interceptors from running, or the base dispatcher from being reached. > [!WARNING] > All resource loading customization is ignored when scripts inside the jsdom use synchronous `XMLHttpRequest`. This is a technical limitation as we cannot transfer dispatchers or interceptors across a process boundary. ### Virtual consoles Like web browsers, jsdom has the concept of a "console". This records both information directly sent from the page, via scripts executing inside the document using the `window.console` API, as well as information from the jsdom implementation itself. We call the user-controllable console a "virtual console", to distinguish it from the Node.js `console` API and from the inside-the-page `window.console` API. By default, the `JSDOM` constructor will return an instance with a virtual console that forwards all its output to the Node.js console. This includes both jsdom output (such as not-implemented warnings or CSS parsing errors) and in-page `window.console` calls. To create your own virtual console and pass it to jsdom, you can override this default by doing ```js const virtualConsole = new jsdom.VirtualConsole(); const dom = new JSDOM(``, { virtualConsole }); ``` Code like this will create a virtual console with no behavior. You can give it behavior by adding event listeners for all the possible console methods: ```js virtualConsole.on("error", () => { ... }); virtualConsole.on("warn", () => { ... }); virtualConsole.on("info", () => { ... }); virtualConsole.on("dir", () => { ... }); // ... etc. See https://console.spec.whatwg.org/#logging ``` (Note that it is probably best to set up these event listeners _before_ calling `new JSDOM()`, since errors or console-invoking script might occur during parsing.) If you simply want to redirect the virtual console output to another console, like the default Node.js one, you can do ```js virtualConsole.forwardTo(console); ``` There is also a special event, `"jsdomError"`, which will fire with error objects to report errors from jsdom itself. This is similar to how error messages often show up in web browser consoles, even if they are not initiated by `console.error`. As mentioned above, the default behavior for jsdom is to send these to the Node.js console. This done via `console.error(jsdomError.message)`, or in the case of `"unhandled-exception"`-type jsdom errors that occur from scripts running in the jsdom, via `console.error(jsdomError.cause.stack)`. Using `forwardTo()` will give the same behavior. If you want a non-default behavior, you can customize it in the following ways: ```js // Do not send any jsdom errors to the Node.js console: virtualConsole.forwardTo(console, { jsdomErrors: "none" }); // Send only certain jsdom errors to the Node.js console, ignoring others: virtualConsole.forwardTo(console, { jsdomErrors: ["unhandled-exception", "not-implemented"]}); // Customize the handling of all jsdom errors: virtualConsole.forwardTo(console, { jsdomErrors: "none" }); virtualConsole.on("jsdomError", err => { switch (err.type) { case "unhandled-exception": { // ... process ... break; } case "css-parsing": { // ... process in some other way ... break; } // ... etc. ... } }); ``` The details for each type of jsdom error, listed by their `type` property, are: - `"css-parsing"`: an error parsing CSS stylesheets - `cause`: the exception object from our CSS parser library, [`rrweb-cssom`](https://github.com/rrweb-io/CSSOM) - `sheetText`: the full text of the stylesheet that we attempted to parse - `"not-implemented"`: an error emitted when certain stub methods from [unimplemented parts of the web platform](#unimplemented-parts-of-the-web-platform) are called - `"resource-loading"`: an error [loading resources](#loading-subresources), e.g. due to a network error or a bad response code from the server - `cause` property: the exception object from the internal Node.js network calls jsdom made when retrieving the resource, or from the developer's custom resource loader - `url` property: the URL of the resource that was attempted to be fetched - `"unhandled-exception"`: a [script execution](#executing-scripts) error that was not handled by a `Window` `"error"` event listener - `cause` property: contains the original exception object ### Cookie jars Like web browsers, jsdom has the concept of a cookie jar, storing HTTP cookies. Cookies that have a URL on the same domain as the document, and are not marked HTTP-only, are accessible via the `document.cookie` API. Additionally, all cookies in the cookie jar will impact the fetching of subresources. By default, the `JSDOM` constructor will return an instance with an empty cookie jar. To create your own cookie jar and pass it to jsdom, you can override this default by doing ```js const cookieJar = new jsdom.CookieJar(store, options); const dom = new JSDOM(``, { cookieJar }); ``` This is mostly useful if you want to share the same cookie jar among multiple jsdoms, or prime the cookie jar with certain values ahead of time. Cookie jars are provided by the [tough-cookie](https://www.npmjs.com/package/tough-cookie) package. The `jsdom.CookieJar` constructor is a subclass of the tough-cookie cookie jar which by default sets the `looseMode: true` option, since that [matches better how browsers behave](https://github.com/whatwg/html/issues/804). If you want to use tough-cookie's utilities and classes yourself, you can use the `jsdom.toughCookie` module export to get access to the tough-cookie module instance packaged with jsdom. ### Intervening before parsing jsdom allows you to intervene in the creation of a jsdom very early: after the `Window` and `Document` objects are created, but before any HTML is parsed to populate the document with nodes: ```js const dom = new JSDOM(`Hello
`, { beforeParse(window) { window.document.childNodes.length === 0; window.someCoolAPI = () => { /* ... */ }; } }); ``` This is especially useful if you are wanting to modify the environment in some way, for example adding shims for web platform APIs jsdom does not support. ## `JSDOM` object API Once you have constructed a `JSDOM` object, it will have the following useful capabilities: ### Properties The property `window` retrieves the `Window` object that was created for you. The properties `virtualConsole` and `cookieJar` reflect the options you pass in, or the defaults created for you if nothing was passed in for those options. ### Serializing the document with `serialize()` The `serialize()` method will return the [HTML serialization](https://html.spec.whatwg.org/#html-fragment-serialisation-algorithm) of the document, including the doctype: ```js const dom = new JSDOM(`hello`); dom.serialize() === "hello"; // Contrast with: dom.window.document.documentElement.outerHTML === "hello"; ``` ### Getting the source location of a node with `nodeLocation(node)` The `nodeLocation()` method will find where a DOM node is within the source document, returning the [parse5 location info](https://www.npmjs.com/package/parse5#options-locationinfo) for the node: ```js const dom = new JSDOM( `Hello
Hello
Hi!`);
frag.childNodes.length === 2;
frag.querySelector("strong").textContent === "Hi!";
// etc.
```
Here `frag` is a [`DocumentFragment`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) instance, whose contents are created by parsing the provided string. The parsing is done using a `` element, so you can include any element there (including ones with weird parsing rules like ` Hello Hello`). It's also important to note that the resulting `DocumentFragment` will not have [an associated browsing context](https://html.spec.whatwg.org/multipage/#concept-document-bc): that is, elements' `ownerDocument` will have a null `defaultView` property, resources will not load, etc.
All invocations of the `fragment()` factory result in `DocumentFragment`s that share the same template owner `Document`. This allows many calls to `fragment()` with no extra overhead. But it also means that calls to `fragment()` cannot be customized with any options.
Note that serialization is not as easy with `DocumentFragment`s as it is with full `JSDOM` objects. If you need to serialize your DOM, you should probably use the `JSDOM` constructor more directly. But for the special case of a fragment containing a single element, it's pretty easy to do through normal means:
```js
const frag = JSDOM.fragment(`