jsdom

jsdom is feeling the AGI!

This release is dedicated to @scttcper, who unleashed @codex upon jsdom and found tons of performance improvements. Along the way, he found and fixed many correctness issues as well.

We really appreciate his thoughtful PRs, which did a great job following the project's contribution guidelines, and were clearly human-curated, with their PR descriptions edited to be brief and respectful of the maintainers' time.

Thanks to @scttcper, as well as all the other contributors of this release (most of whom were AI-assisted).

• Added named access to elements on document, such as document.myForm for <form name="myForm">. (@vojtisprime11)
• Added QuotaExceededError, including its use for storage quota errors and oversized crypto.getRandomValues() requests.
• Added support for the relaxed DOM naming rules when creating elements, attributes, and document types.
• Improved performance of DOM construction, tree mutations, range operations, and live collection access, especially on large documents. (@scttcper, @erezrokah)
• Improved performance of getComputedStyle(), style changes, and CSS serialization. (@scttcper, @jhult)
• Improved performance of event dispatch, form control and label lookups, and updates to <select> elements and radio button groups. (@scttcper)
• Reduced memory use when creating and working with DOM nodes, attributes, event listeners, and mutation observers. (@scttcper)
• Changed window.close() to preserve access to the document and its DOM through retained references.
• Fixed element.querySelectorAll() returning no matches when the first part of the selector matches the element itself, which regressed in v30.0.0. (@asamuzaK)
• Fixed case sensitivity in CSS attribute selectors, including selectors matching data-state="", title="", and other case-sensitive values. (@asamuzaK)
• Fixed document.querySelector() failing to find a matching element when an earlier element has the same ID but does not match the rest of the selector. (@vojtisprime11)
• Fixed :focus matching in shadow trees. (@asamuzaK)
• Fixed DOM insertion and replacement, including valid document.replaceChildren() calls, invalid document element and doctype placements, and mutations during element.replaceWith().
• Fixed the ordering of script execution, custom element callbacks, iframe loading, and mutation observer notifications during DOM insertion, including in shadow trees.
• Fixed queued events and navigation continuing after window.close() or iframe removal, and prevented new scripts, resource loads, timers, and animation frames from starting in destroyed documents. (@scttcper)
• Fixed parent documents waiting indefinitely for loading to finish when a child iframe removes itself during loading.
• Fixed request cancellation across redirects, during pending requestInterceptor() callbacks, and when reusing an XMLHttpRequest after aborting it.
• Fixed resource loading and JSDOM.fromURL() potentially hanging when response handling throws and response stream cleanup does not finish.
• Fixed successful cached resource loads being treated as aborted.
• Fixed getComputedStyle() and document.styleSheets using the wrong stylesheet order after inserting or updating <style> elements.
• Fixed getComputedStyle() ignoring nested @import and @media rules in imported stylesheets, and returning stale results after imports finish loading.
• Fixed style invalidation, stylesheet removal, and frame source updates in shadow trees.
• Fixed repeated getComputedStyle() calls changing case-sensitive background URLs, and inconsistent resolution of border shorthands containing system colors. (@scttcper)
• Fixed computed border widths, including borderless elements incorrectly reporting 16px, which regressed in v30.0.0. (@Alberto-BaseNet)
• Fixed getComputedStyle() to resolve 'font-weight' keywords to numeric values. (@tianrking)
• Fixed getComputedStyle() to convert lengths to pixels inside CSS math functions containing percentages, and to resolve percentages in 'font-size' math functions. (@soroushm)
• Fixed serialization of min() and max() containing nested calc(), which regressed in v30.0.0. (@asamuzaK)
• Fixed CSS values mixing lengths or percentages with math functions, such as 'grid-template-columns' values containing both 100px and calc(). (@rome-xi)
• Fixed parsing of 'background' and 'border' shorthands with adjacent components, such as url(a.png)no-repeat, including a crash when parsing inline styles. Also fixed handling of invalid shorthand assignments and escaped or unusual characters in CSS declarations. (@asamuzaK)
• Fixed parsing of unitless zero values in 'flex' shorthands, such as 35 1 0, and rejection of negative 'flex-basis' lengths and percentages. (@asamuzaK)
• Fixed shorthand style assignments producing extra mutation records and custom element callbacks for intermediate values. (@scttcper)
• Fixed Range and Selection handling of CDATA sections, including boundary offsets and range cloning, extraction, deletion, insertion, and stringification. (@scttcper)
• Fixed text.normalize() incorrectly removing the text node or merging its siblings. (@scttcper)
• Fixed cloning and importing CDATA sections and processing instructions whose contents have been modified, and serialization of CDATA sections adopted into HTML documents.
• Fixed stale named-property collections on window, and incorrect named access from empty or namespaced id="" and name="" values. (@scttcper)
• Fixed elements in documents created with DOMParser or document.implementation.createHTMLDocument() appearing as named properties on window and being retained in memory. (@Iaotle)
• Fixed memory leaks from mutation observers retaining observed nodes, abort signals retaining removed event listeners, and storage event tracking retaining closed windows. (@scttcper)
• Fixed storage events being sent to windows created after the storage change, and ensured surviving recipients still receive events when the source document is destroyed.
• Fixed attribute lookups after namespace prefix changes, and namespaced attributes incorrectly affecting ID lookups and element behavior. (@scttcper)
• Fixed input.list in detached element trees. (@scttcper)
• Fixed attr.ownerDocument after setting an attribute node on an element in another document or adopting its element. (@Kjubikstronk)
• Fixed fresh element.getElementsByTagName() calls using the previous document's case-sensitivity rules after adoption between HTML and XML documents. (@Kjubikstronk)
• Fixed element.tagName returning stale casing after adoption between HTML and XML documents.
• Fixed radio button grouping and checkedness updates for controls with different form owners, controls outside their form, unnamed controls, and canceled clicks.
• Fixed <select> selection updates when moving options, and unintended selection resets when moving a whole <select> or changing unrelated descendants.
• Fixed cloning <input> elements to preserve input.indeterminate.
• Fixed focus state after removing a focused element or its ancestor, including inside shadow trees.
• Fixed script execution when inserting children into a connected, empty <script>. (@Kjubikstronk)
• Fixed incorrect script execution after changes to src="", and handling of type="", for="", and event="".
• Fixed document.currentScript during nested script execution and scripts in shadow trees.
• Fixed event dispatch, window.event, and default passive listener handling for non-node event targets, and event dispatch when user code modifies window.constructor.
• Fixed volumechange and ratechange events to fire asynchronously. (@christianaurichzm)
• Fixed DOM APIs accepting user-created proxies around DOM objects where genuine DOM objects are required.
• Fixed XPath iterator invalidation after DOM mutations and errors for invalid result types.
• Fixed NodeIterator traversal when its filter removes nodes.
• Fixed fileReader.readAsText() to honor the blob's MIME type charset when no supported explicit encoding is supplied.
• Fixed fractional seconds in time input parsing and serialization. (@Jaybhade)
• Fixed large input.valueAsNumber assignments for time and local date/time inputs.
• Fixed hard wrapping of <textarea> values to use the numeric textarea.cols value.
• Fixed document.readyState to be "complete" for documents created with document.implementation.createDocument() and document.implementation.createHTMLDocument().
• Fixed element.translate for empty translate="" values and elements without a parent.
• Fixed XML parsing of lone surrogates to replace them with the Unicode replacement character.
• Fixed node.lookupNamespaceURI() for the xml and xmlns prefixes. (@vojtisprime11)
• Fixed <base> elements to ignore data: and javascript: URLs. (@vojtisprime11)
• Fixed svgElement.viewportElement inside <symbol> elements.
• Fixed the default blobEvent.timecode to be NaN.
• Fixed the object shape and property descriptors of CSS.

• Fixed getComputedStyle() with calc() and other functions throwing an exception, which regressed in v30.0.0. (@asamuzaK)
• Sped up up range operations on large documents (@leonidaz)

Breaking changes:

• Node.js minimum version raised to ^22.22.2 || ^24.15.0 || >=26.0.0.

Other changes:

• Added CSS.escape() and CSS.supports() functions. (@asamuzaK)
• Added 'background-position-x' and 'background-position-y' CSS properties. (@olagokemills)
• Fixed getComputedStyle() to convert length values into pixels. (@asamuzaK)
• Fixed CSS function serialization, e.g., in the return value of getPropertyValue(). (@asamuzaK)
• Fixed the type of error thrown by document.evaluate() (@dokson)

• Fixed 'border-radius' computed style serialization. (@asamuzaK)
• Fixed computed style computation when using 'background-origin' and 'background-clip' CSS properties. (@asamuzaK)
• Significantly optimized initial calls to getComputedStyle(), before the cache warms up. (@asamuzaK)

• Added basic support for the ratio CSS type. (@asamuzaK)
• Fixed getComputedStyle() sometimes returning outdated results after CSS was modified. (@asamuzaK)

• Significantly improved and sped up getComputedStyle(). Computed value rules are now applied across a broader set of properties, and include fixes related to inheritance, defaulting keywords, custom properties, and color-related values such as currentcolor and system colors. (@asamuzaK)
• Fixed CSS 'background' and 'border' shorthand parsing. (@asamuzaK)

• Fixed CSS parsing of 'border', 'background', and their sub-shorthands containing keywords or var(). (@asamuzaK)
• Fixed getComputedStyle() to return a more functional CSSStyleDeclaration object, including indexed access support, which regressed in v29.0.0.

Breaking changes:

• Node.js v22.13.0+ is now the minimum supported v22 version (was v22.12.0+).

Other changes:

• Overhauled the CSSOM implementation, replacing the @acemir/cssom and cssstyle dependencies with fresh internal implementations built on webidl2js wrappers and the css-tree parser. Serialization, parsing, and API behavior is improved in various ways, especially around edge cases.
• Added CSSCounterStyleRule and CSSNamespaceRule to jsdom Windows.
• Added cssMediaRule.matches and cssSupportsRule.matches getters.
• Added proper media query parsing in MediaList, using css-tree instead of naive comma-splitting. Invalid queries become "not all" per spec.
• Added cssKeyframeRule.keyText getter/setter validation.
• Added cssStyleRule.selectorText setter validation: invalid selectors are now rejected.
• Added styleSheet.ownerNode, styleSheet.href, and styleSheet.title.
• Added bad port blocking per the fetch specification, preventing fetches to commonly-abused ports.
• Improved Document initialization performance by lazily initializing the CSS selector engine, avoiding ~0.5 ms of overhead per Document. (@thypon)
• Fixed a memory leak when stylesheets were removed from the document.
• Fixed CSSStyleDeclaration modifications to properly trigger custom element reactions.
• Fixed nested @media rule parsing.
• Fixed CSSStyleSheet's "disallow modification" flag not being checked in all mutation methods.
• Fixed XMLHttpRequest's response getter returning parsed JSON during the LOADING state instead of null.
• Fixed getComputedStyle() crashing in XHTML documents when stylesheets contained at-rules such as @page or @font-face.
• Fixed a potential hang in synchronous XMLHttpRequest caused by a race condition with the worker thread's idle timeout.

• Added blob.text(), blob.arrayBuffer(), and blob.bytes() methods.
• Improved getComputedStyle() to account for CSS specificity when multiple rules apply. (@asamuzaK)
• Improved synchronous XMLHttpRequest performance by using a persistent worker thread, avoiding ~400ms of setup overhead on every synchronous request after the first one.
• Improved performance of node.getRootNode(), node.isConnected, and event.dispatchEvent() by caching the root node of document-connected trees.
• Fixed getComputedStyle() to correctly handle !important priority. (@asamuzaK)
• Fixed document.getElementById() to return the first element in tree order when multiple elements share the same ID.
• Fixed <svg> elements to no longer incorrectly proxy event handlers to the Window.
• Fixed FileReader event timing and fileReader.result state to more closely follow the spec.
• Fixed a potential hang when synchronous XMLHttpRequest encountered dispatch errors.
• Fixed compatibility with environments where Node.js's built-in fetch() has been used before importing jsdom, by working around undici v6/v7 incompatibilities.

• Overhauled resource loading customization. See the new README for details on the new API.
• Added MIME type sniffing to <iframe> and <frame> loads.
• Regression: WebSockets are no longer correctly throttled to one connection per origin. This is a result of the bug at nodejs/undici#4743.
• Fixed decoding of the query components of <a> and <area> elements in non-UTF-8 documents.
• Fixed XMLHttpRequest fetches and WebSocket upgrade requests to be interceptable by the new customizable resource loading. (Except synchronous XMLHttpRequests.)
• Fixed the referrer of a document to be set correctly when redirects are involved; it is now the initiating page, not the last hop in the redirect chain.
• Fixed correctness bugs when passing ArrayBuffers or typed arrays to various APIs, where they would not correctly snapshot the data.
• Fixed require("url").parse() deprecation warning when using WebSockets.
• Fixed <iframe>, <frame>, and <img> (when canvas is installed) to fire load events, not error events, on non-OK HTTP responses.
• Fixed many small issues in XMLHttpRequest.

• Added TextEncoder and TextDecoder.
• Improved decoding of HTML bytes by using the new @exodus/bytes package; it is now much more correct. (@ChALkeR)
• Improved decoding of XML bytes to use UTF-8 more often, instead of sniffing for <meta charset> or using the parent frame's encoding.
• Fixed a memory leak when Ranges were used and then the elements referred to by those ranges were removed.

• Improved CSS parsing and CSSOM object APIs via updates to @acemir/cssom. (@acemir)

• Added CSSGroupingRule, CSSNestedDeclarations, CSSConditionRule, CSSContainerRule, CSSScopeRule, CSSSupportsRule, CSSLayerBlockRule, and CSSLayerStatementRule to jsdom Windows. (@acemir)
• Improved CSS parsing and CSSOM object APIs via updates to @acemir/cssom. (@acemir)
• Fixed @import-ed stylesheets to be properly exposed to CSSOM, and not to overwrite the sheet created from the <link> or <style> element. (@acemir)

• Improved CSS parsing by switching to @acemir/cssom, including support for nested selectors, nested declarations, layer statements, and improved at-rule validation. (@acemir)
• Fixed some selector cache invalidation issues where changes to attributes were not being picked up. (@asamuzaK)
• Fixed package.json "engines" field to reflect the new minimum Node.js versions needed to run jsdom, as noted in the changelog for v27.0.1.

This release inadvertently raised the minimum Node.js version from v20.0.0 to v20.19.0+, v22.12.0+, v24.0.0+. (This happened via a dependency update.) This probably should have been a breaking (major) change, instead of happening in a patch version, since it prevents using earlier Node.js versions.

After further testing, we found that most of our development dependencies also require these versions, and so it's not feasible for the jsdom project to support earlier Node.js versions. (For example, our testing frameworks will not run on them.) If you need to use such earlier versions, or otherwise are working in an environment which gives related errors such as ERR_REQUIRE_ESM, then please stick with the v26.1.0 release of jsdom. (Noting, of course, that such versions are unsupported, and we will not respond to bug reports opened against them.)

Subsequent jsdom releases will explicitly require these minimum Node.js versions, and will have CI testing to ensure that the minimum version is not accidentally raised again.

Normal changelog:

• Fixed some regressions in CSS selectors. Most such regression fixes were done in a minor update of a dependency, and thus available for all fresh installs of v27.0.0. However, one related to class="" attribute changes is only possible with a new version of jsdom. (@asamuzaK)

Changes since 26.1.0

• Node.js v20 is now the minimum supported version.
• Added a variety of event constructors, even though we do not implement their associated specifications or ever fire them: BeforeUnloadEvent, BlobEvent, DeviceMotionEvent (omitting requestPermission()), DeviceOrientationEvent (omitting requestPermission()), PointerEvent, PromiseRejectionEvent, and TransitionEvent.
• Added movementX and movementY to MouseEvent. (These are from the Pointer Lock specification, the rest of which is not implemented.)
• Added customElements.getName(). (@mash-graz)
• Updated the virtual console:
  • "jsdomError" events are now documented, with specific type properties and other properties that depend on the type.
  • sendTo() was renamed to forwardTo().
  • The jsdomErrors option to forwardTo() can be used to control which errors are sent to the Node.js console. This replaces the previous omitJSDOMErrors boolean option.
  • "jsdomError"s for failed XMLHttpRequest fetches are no longer emitted.
  • The values that are printed when forwarding "jsdomError"s to the Node.js console are streamlined.
• Switched our CSS selector engine from nwsapi to @asamuzakjp/dom-selector, closing over 20 selector-related bugs.
• Upgraded tough-cookie, which now considers URLs like http://localhost/ to be secure contexts (per the spec), and thus will return Secure-flagged cookies for such URLs. (@colincasey)
• Upgraded cssstyle, which brings along many improvements and fixes to the CSSStyleDeclaration object and its properties.
• Updated the user agent stylesheet to be derived from the HTML Standard, instead of from an old revision of Chromium.
• Changed element.click() to fire a PointerEvent instead of a MouseEvent.
• Changed certain events to be passive by default.
• Changed the <input> element's pattern="" attribute to use the v regular expression flag, instead of u.
• Fixed many specification conformance issues with the Window object, including named properties and changing various data properties to accessor properties.
• Fixed document.createEvent() to accept a more correct set of event names.
• Fixed the ElementInternals accessibility getters and setters. (They were introduced in v23.1.0, but due to inadequate test coverage never actually worked.)
• Fixed using Object.defineProperty() on certain objects, such as HTMLSelectElement instances.
• Fixed jsdom.reconfigure({ url }) not updating document.baseURI or properties derived from it. (This regressed in v26.1.0.)
• Fixed CSS system colors, as well as the initial, inherit, and unset keywords, to resolve correctly. (@asamuzaK)
• Fixed CSS display style resolution. (@asamuzaK)

Changes since 27.0.0-beta.3

• Upgraded cssstyle, which brings along various CSS parsing fixes.

• Breaking change: upgraded tough-cookie, which now considers URLs like http://localhost/ to be secure contexts (per the spec), and thus will return Secure-flagged cookies for such URLs. (@colincasey)
• Added customElements.getName(). (@mash-graz)
• Changed the <input> element's pattern="" attribute to use the v regular expression flag, instead of u.
• Fixed jsdom.reconfigure({ url }) not updating document.baseURI or properties derived from it. This regressed in v26.1.0.
• Fixed CSS system colors, as well as the initial, inherit, and unset keywords, to resolve correctly. This is especially important since the change in v27.0.0-beta.1 to use system colors in the user agent stylesheet. (@asamuzaK)
• Fixed CSS background property parsing and serialization. (@asamuzaK)
• Fixed CSS color parsing and serialization inside of gradients. (@asamuzaK)
• Fixed CSS display style resolution. (@asamuzaK)
• Upgraded @asamuzakjp/dom-selector, which notably fixed repeated use of the :scope selector. (@asamuzaK)

Significantly improved specification conformance for the Window object, including named properties and changing various data properties to accessor properties. This is not likely to be breaking, but since it's a complex change to such a core object, we're happy to do another beta testing release with this included before graduating the v27 line to stable.

Additionally, updated cssstyle to v4.4.0, which brings along various conformance fixes to the CSSStyleDeclaration object and its properties.

Breaking changes:

• Node.js v20+ is now the minimum supported version.
• The user agent stylesheet is now derived from the HTML Standard, instead of from Chromium. This might change the results you see from getComputedStyle().
• The virtual console has seen a number of changes:
  • "jsdomError" events are now documented, with specific type properties and other properties that depend on the type.
  • sendTo() was renamed to forwardTo().
  • The jsdomErrors option to sendTo() can be used to control which errors are sent to the Node.js console. This replaces the previous omitJSDOMErrors boolean option.
  • "jsdomError"s for failed XMLHttpRequest fetches are no longer emitted.
  • The values that are printed when forwarding "jsdomError"s to the Node.js console are streamlined.

Other changes:

• Fixed the ElementInternals accessibility getters and setters. (They were introduced in v23.1.0, but due to inadequate test coverage never actually worked.)
• Fixed using Object.defineProperty() on certain objects, such as HTMLSelectElement instances.

This release includes several changes that might be disruptive, and so are being tested as a beta release before the next major release. Hopefully, they will not be breaking, but your help testing would be appreciated.

New selector engine

Mostly notably, this switches our CSS selector engine from nwsapi to @asamuzakjp/dom-selector. This was attempted back in 23.2.0, but reverted in 24.0.0 because of performance concerns. Since that time, @asamuzakjp/dom-selector has improved its performance significantly. On the real-world benchmarks from #3659, we see the new version taking 1.1x as long (compared to 1.5x with the previous attempt). We hope this lower performance overhead will be enough to allow us to stick with the new selector engine. As a sample of how much more capable it is, 19 independent selector-related bugs were closed by merging in this new version.

Please test with the new selector engine and report back with any performance concerns on the issue tracker, ideally before we make the next stable release.

New event constructors

The other major change in this prerelease is the addition of many new event constructors. Previously, we have avoided implementing event constructors unless we implemented their attendant specification. For example, we did not implement BeforeUnloadEvent since we don't implement unloading of documents; we did not implement BlobEvent since we did not implement the MediaStream Recording specification; etc. However, these are common popular requests, and so we've chosen to implement these event constructors without implementing their related specifications.

If this causes you any problems, e.g. due to breaking feature detection, please open an issue on the issue tracker, ideally before we make the next stable release.

The full list of implemented event constructors is: BeforeUnloadEvent, BlobEvent, DeviceMotionEvent (omitting requestPermission()), DeviceOrientationEvent (omitting requestPermission()), PointerEvent, PromiseRejectionEvent, and TransitionEvent.

Additional changes

The following non-breaking changes are included in this release:

• Added movementX and movementY to MouseEvent. (These are from the Pointer Lock specification, the rest of which is not implemented.)
• Changed element.click() to fire a PointerEvent instead of a MouseEvent.
• Changed certain events to be passive by default.
• Fixed document.createEvent() to accept a more correct set of event names.

• Added at least partial support for various SVG elements and their classes: <defs> (SVGDefsElement), <desc> (SVGDescElement), <g> (SVGGElement), <metadata> (SVGMetadataElement), <switch> (SVGSwitchElement), and <symbol> (SVGSymbolElement).
• Added SVGAnimatedPreserveAspectRatio and SVGAnimatedRect, including support in the reflection layer.
• Added the SVGSVGElement createSVGRect() method, and the SVGRect type (which is distinct from DOMRect.)
• Added indexed property support to HTMLFormElement.
• Updated the SVGElement viewportElement() method to correctly establish the viewport based on ancestor elements.
• Removed the now-bloated form-data dependency in favor of our own smaller implementation of multipart/form-data serialization. No functional changes are expected.
• Various performance improvements, caches, microoptimizations, and deferred object creation.

Breaking change: canvas peer dependency requirement has been upgraded from v2 to v3. (@sebastianwachter)

Other changes:

• Added AbortSignal.any(). (@jdbevan)
• Added initial support for form-associated custom elements, in particular making them labelable and supporting the ElementInternals labels property. The form-associated callbacks are not yet supported. (@hesxenon)
• Updated whatwg-url, adding support for URL.parse().
• Updated cssstyle and rrweb-cssom, to improve CSS parsing capabilities.
• Updated nwsapi, improving CSS selector matching.
• Updated parse5, fixing a bug around <noframes> elements and HTML entity decoding.
• Fixed JSDOM.fromURL() to properly reject the returned promise if the server redirects to an invalid URL, instead of causing an uncaught exception.

• Updated dependencies, notably tough-cookie, which no longer prints a deprecation warning.

This major release changes the prototype of a jsdom's EventTarget.prototype to point to the Object.prototype inside the jsdom, instead of pointing to the Node.js Object.prototype. Thus, the prototype chain of Window stays entirely within the jsdom, never crossing over into the Node.js realm.

This only occurs when runScripts is set to non-default values of "dangerously" or "outside-only", as with the default value, there is no separate Object.prototype inside the jsdom.

This will likely not impact many programs, but could cause some changes in instanceof behavior, and so out of an abundance of caution, we're releasing it as a new major version.

• Fixed calls to postMessage() that were done as a bare property (i.e., postMessage() instead of window.postMessage()).

• Fixed an issue with the in operator applied to EventTarget methods, e.g. 'addEventListener' in window, which only appeared in Node.js ≥22.5.0. (@legendecas)
• Fixed the events fired by blur(): it no longer fires focus and focusin on the Document, and blur and focusout no longer have their relatedTarget property set. (@asamuzaK)

• Fixed selection methods to trigger the selectionchange event on the Document object. (@piotr-oles)

• Added the getSetCookie() method to the Headers class. (@ushiboy)
• Fixed the creation and parsing of elements with names from Object.prototype, like "constructor" or "toString".
• Updated rweb-cssom, which can now parse additional CSS constructs.

This release reverts our selector engine back to nwsapi. As discussed in #3659, the performance regressions from @asamuzakjp/dom-selector turned out to be higher than anticipated. In the future, we can revisit @asamuzakjp/dom-selector after it reaches nwsapi's performance on the two real-world benchmarks provided by the community.

Since reverting to nwsapi causes several functionality regressions, e.g. removing :has() support, we've decided to make this a major version.

Additionally:

• Small fixes to edge-case behavior of the following properties: input.maxLength, input.minLength, input.size, progress.max, tableCell.colSpan, tableCell.rowSpan, tableCol.span, textArea.cols, textArea.maxLength, textArea.minLength, textArea.rows.

This release switches our CSS selector engine from nwsapi to @asamuzakjp/dom-selector. The new engine is more actively maintained, and supports many new selectors: see the package's documentation for the full list. It also works better with shadow trees.

There is a potential of a performance regression due to this change. In our stress test benchmark, which runs most of these 273 selectors against this 128 KiB document, the new engine completes the benchmark only 0.25x as fast. However, we're hopeful that in more moderate usage this will not be a significant issue. Any help speeding up @asamuzakjp/dom-selector is appreciated, and feel free to open an issue if this has had a significant impact on your project.

• Added an initial implementation of ElementInternals, including the shadowRoot getter and the string-valued ARIA properties. (@zjffun)
• Added the string-valued ARIA attribute-reflecting properties to Element.
• Fixed history.pushState() and history.replaceState() to follow the latest specification, notably with regards to how they handle empty string inputs and what new URLs are possible.
• Fixed the input.valueAsANumber setter to handle NaN correctly. (@alexandertrefz)
• Updated various dependencies, including cssstyle which contains several bug fixes.

• Fixed the incorrect canvas peer dependency introduced in v23.0.0.

• Node.js v18 is now the minimum supported version.
• Updated various dependencies, including whatwg-url which integrates various additions to the URL and URLSearchParams objects.

• Added crypto.randomUUID(). (@jamesbvaughan)
• Added DOMRect and DOMRectReadOnly.
• Added AbortSignal.timeout().
• Added abortSignal.throwIfAborted().
• Added support for the submitter argument to the FormData constructor. (@jenseng)
• Improved getComputedStyle()'s results for color-based properties, to resolve named colors and attempt to provide initial inheritance support. (@hoekz-wwt)
• Updated Window's event handler properties (e.g. oncopy, ontouchstart, etc.) to reflect the latest list from the standard.
• Fixed DOMParser-created documents to inherit their URL from the creating document.

• Node.js v16 is now the minimum supported version.
• Removed support for running jsdom in the browser via a browserified bundle. This carried with it too much complexity, especially for our testing infrastructure, and a testing package we relied on was recently deprecated.

• Fixed setRangeText() used on <input> and <textarea> elements to calculate the new end index correctly. (@pmstss)
• Fixed pageX, pageY, offsetX, and offsetY on MouseEvents during dispatch. (@jenseng)
• Upgraded nwsapi to v2.2.4, bringing along various fixes to our selector engine.

• Fixed jsdom.reconfigure() to also adjust the URL as seen by the history API, so that e.g. history.replaceState(null, "") would not mess up the URL. (@jdufresne)
• Fixed location.hash = "" to leave any # in location.href.
• Fixes a few bugs with CSS parsing by replacing cssom with rweb-cssom, since the latter is maintained. (@seanparmelee)

• Added x, y, pageX, pageY, offsetX, and offsetY to MouseEvent. (@jenseng, @ViniciusFXavier)
• Added support for unset with getComputedStyle(). (@jsnajdr)
• Added the submitter property to SubmitEvent. (@jenseng)
• Fixed MouseEvent's screenX and screenY to no longer coerce to integers, allowing fractional values. (@jenseng)
• Fixed formEl.submit() to not longer fire submit events. (@jenseng)
• Fixed stylesheets to no longer affect the document after their corresponding <link> is removed. (@jsnajdr)
• Fixed pointer-events to inherit when used with getComputedStyle(). (@jnajdr)
• Fixed <script> elements with no src="" to no longer fire load events. (@t1ger2080)
• Improved getComputedStyle() to cache its results, which should make it much faster. (@jsnajdr)

A potentially-breaking bug fix:

• Fixed the window, document, location, and top properties of Window to be non-configurable. (@ExE-Boss)

Other changes:

• Added support for <input type=image> submitting forms. (@jenseng)
• Added the location setter to the Window object, which forwards to the location.href setter. Setting the URL is still only implemented for fragment navigations, however. (@ExE-Boss)
• Fixed defer="" <script> elements that are added after DOMContentLoaded to execute, instead of being skipped.
• Fixed selectElement.selectedOptions being incorrect when optionElement.selected is set. This was a regression introduced in v20.0.1. Unfortunately this also reverts the performance improvement when appending <option> elements that was introduced then. (@eps1lon)
• Fixed the self, locationbar, menubar, personalbar, scrollbars, statusbar, toolbar, frames, parent, external, length, and screen properties of Window to be replaceable: that is, setting them will override their values, instead of having the new value be ignored. (@ExE-Boss)
• Fixed a few issues with JSDOM.fromURL() in the browser build of jsdom. (@LungZeno)

• Updated dependencies, notably w3c-xmlserializer, which fixes using DOMParser on XML documents containing emoji.

• Fixed xhr.abort() to no longer give an exception when the constructed XMLHttpRequest was invalid. (@whamtet)
• Fixed event.getModifierState() on MouseEvent and KeyboardEvent instances to properly consult the ctrlKey, altKey, metaKey, and shiftKey properties of the event. (@juzerzarif)
• Fixed custom element creation to not be affected by any modifications to the window.customElements property. (@bicknellr)

• Improved the performance of appending <option> elements to <select> elements. (@TheHound)
• Fixed location.pathname getter to not crash when the JSDOM instance was created using an opaque-path URL, including the default URL of about:blank.
• Fixed crypto.getRandomValues() to accept typed array subclasses. (@sebamarynissen)
• Updated various dependency minor versions. Notably, nwsapi fixed some selectors bugs, and tough-cookie fixed some cookie bugs.

• Node.js v14 is now the minimum supported version.
• Added crypto.getRandomValues(). (@sjrd)
• Added HTMLFormControlsCollection and RadioNodeList, so formEl.elements now behaves correctly. (@UndefinedBehavior)
• Added the signal option to addEventListener(). (@cheap-glitch)
• Fixed the :root pseudoclass to work correctly. (@hughs-ch)
• Updated parse5, bringing along some HTML parsing and serialization fixes. (@fb55)

• Changed jsdom.nodeLocation() to return undefined when used on nodes that originate via fragment parsing (e.g., via innerHTML). Previously it would return based on the node location of the fragment string, which made node locations unreliable with respect to the original document source. This restores the behavior that was present in v14.0.0, and was accidentally broken in v14.1.0. (@bakkot)
• Fixed calling window.close() inside the Window's load event to no longer crash. (@MattiasBuelens)

• Fixed connectedCallback to fire in situations involving document fragments, which was broken in v18.0.1. (@GrantGryczan)

• Fixed headers.append() and headers.set() to normalize values. (@MattiasBuelens)
• Fixed pageshow events to have bubbles: true and cancelable: true. (@MattiasBuelens)
• Implemented the reason property on AbortSignals, along with the corresponding reason argument to abortSignal.abort() and AbortSignal.abort(). (@MattiasBuelens)

• Fixed live Ranges to update correctly after calling node.normalize(). (@hgiesel)
• Fixed live Ranges to update correctly after removing child nodes. (@hgiesel)
• Fixed setting inputEl.valueAsDate = null to no longer throw an exception, but instead set the value to the empty string. (@simon-weimann)
• Improved performance of node insertion and node.contains(). (@GrantGryczan)

Potentially-breaking bug fixes:

• Fixed SSL certificate checking for WebSocket connections. Previously, invalid SSL certificates were always accepted; now, they properly respect the ResourceLoader's strictSSL option (which defaults to true).
• Changed the global in which almost all Promise and TypeError instances are created to be the jsdom global, not the Node.js global. This could affect any code that uses instanceof.

Other changes:

• Fixed moving an element between HTML and XML documents to reset the tagName cache, allowing it to return a lowercase value once it's in the XML document. (@LucasLefevre)
• Fixed form submission to not happen when the form is invalid. (@pozil)

Breaking change: Node v12 is now the minimum supported version.

• Added AbortSignal.abort(). (@ninevra)
• Added dummy x and y properties to the return value of getBoundingClientRect(). (@eiko)
• Implemented wrapping for textareaEl.value if the wrap="" attribute is specified. (@ninevra)
• Changed newline normalization in <textarea>s according to recent HTML Standard updates. (@ninevra)
• Fixed some bad cascade computation in getComputedStyle(). (@romain-trotard)

• Added parentNode.replaceChildren(). (@ninevra)
• Fixed jsdom's handling of when code running inside the jsdom throws null or undefined as an exception. (@mbest)
• Removed the dependency on the deprecated request package, in the process fixing several issues with the XMLHttpRequest implementation around header processing. Special thanks to vegardbb for completing this months-long effort!

• Fixed infinite recursion when using MutationObservers to observe elements inside a MutationObserver callback.

• Fixed Access-Control-Allow-Headers: * to work with XMLHttpRequest. (@silviot)
• Fixed xhr.response to strip any leading BOM when xhr.responseType is "json".
• Fixed new Text() and new Comment() constructors to properly set the resulting node's ownerDocument.
• Fixed customElements.whenDefined() to resolve its returned promise with the custom element constructor, per recent spec updates. (@ExE-Boss)
• Fixed parsing to ensure that <svg><template></template></svg> does not throw an exception, but instead correctly produces a SVG-namespace <template> element.
• Fixed domParser.parseFromString() to treat <noscript> elements appropriately.
• Fixed form control validity checking when the control was outside the <form> element and instead associated using the form="" attribute.
• Fixed legendEl.form to return the correct result based on its parent <fieldset>.
• Fixed optionEl.text to exclude <script> descendants.
• Fixed radio buttons and checkboxes to not fire input and change events when disconnected.
• Fixed inputEl.indeterminate to reset to its previous value when canceling a click event on a checkbox or radio button.
• Fixed the behavior of event handler attributes (e.g. onclick="...code...") when there were global variables named element or formOwner. (@ExE-Boss)
• On Node.js v14.6.0+ where WeakRefs are available, fixed NodeIterator to no longer stop working when more than ten NodeIterator instances are created, and to use less memory due to inactive NodeIterators sticking around. (@ExE-Boss)

• Fixed a regression that broke customElements.get() in v16.5.0. (@fdesforges)
• Fixed window.event to have a setter which overwrites the window.event property with the given value, per the specification. This fixes an issue where after upgrading to jsdom v16.5.0 you would no longer be able to set a global variable named event in the jsdom context.

• Added window.queueMicrotask().
• Added window.event.
• Added inputEvent.inputType. (@diegohaz)
• Removed ondragexit from Window and friends, per a spec update.
• Fixed the URL of about:blank iframes. Previously it was getting set to the parent's URL. (@SimonMueller)
• Fixed the loading of subresources from the filesystem when they had non-ASCII filenames.
• Fixed the hidden="" attribute to cause display: none per the user-agent stylesheet. (@ph-fritsche)
• Fixed the new File() constructor to no longer convert / to :, per a pending spec update.
• Fixed mutation observer callbacks to be called with the MutationObserver instance as their this value.
• Fixed <input type=checkbox> and <input type=radio> to be mutable even when disabled, per a spec update.
• Fixed XMLHttpRequest to not fire a redundant final progress event if a progress event was previously fired with the same loaded value. This would usually occur with small files.
• Fixed XMLHttpRequest to expose the Content-Length header on cross-origin responses.
• Fixed xhr.response to return null for failures that occur during the middle of the download.
• Fixed edge cases around passing callback functions or event handlers. (@ExE-Boss)
• Fixed edge cases around the properties of proxy-like objects such as localStorage or dataset. (@ExE-Boss)
• Fixed a potential memory leak with custom elements (although we could not figure out how to trigger it). (@soncodi)

• Added a not-implemented warning if you try to use the second pseudo-element argument to getComputedStyle(), unless you pass a ::part or ::slotted pseudo-element, in which case we throw an error per the spec. (@ExE-Boss)
• Improved the performance of repeated access to el.tagName, which also indirectly improves performance of selector matching and style computation. (@eps1lon)
• Fixed form.elements to respect the form="" attribute, so that it can contain non-descendant form controls. (@ccwebdesign)
• Fixed el.focus() to do nothing on disconnected elements. (@eps1lon)
• Fixed el.focus() to work on SVG elements. (@zjffun)
• Fixed removing the currently-focused element to move focus to the <body> element. (@eps1lon)
• Fixed imgEl.complete to return true for <img> elements with empty or unset src="" attributes. (@strager)
• Fixed imgEl.complete to return true if an error occurs loading the <img>, when canvas is enabled. (@strager)
• Fixed imgEl.complete to return false if the <img> element's src="" attribute is reset. (@strager)
• Fixed the valueMissing validation check for <input type="radio">. (@zjffun)
• Fixed translate="" and draggable="" attribute processing to use ASCII case-insensitivity, instead of Unicode case-insensitivity. (@zjffun)

• Added firing of focusin and focusout when using el.focus() and el.blur(). (@trueadm)
• Fixed elements with the contenteditable="" attribute to be considered as focusable. (@jamieliu386)
• Fixed window.NodeFilter to be per-Window, instead of shared across all Windows. (@ExE-Boss)
• Fixed edge-case behavior involving use of objects with handleEvent properties as event listeners. (@ExE-Boss)
• Fixed a second failing image load sometimes firing a load event instead of an error event, when the canvas package is installed. (@strager)
• Fixed drawing an empty canvas into another canvas. (@zjffun)

• Updated StyleSheetList for better spec compliance; notably it no longer inherits from Array.prototype. (@ExE-Boss)
• Fixed requestAnimationFrame() from preventing process exit. This likely regressed in v16.1.0.
• Fixed setTimeout() to no longer leak the closures passed in to it. This likely regressed in v16.1.0. (@AviVahl)
• Fixed infinite recursion that could occur when calling click() on a <label> element, or one of its descendants.
• Fixed getComputedStyle() to consider inline style="" attributes. (@eps1lon)
• Fixed several issues with <input type="number">'s stepUp() and stepDown() functions to be properly decimal-based, instead of floating point-based.
• Fixed various issues where updating selectEl.value would not invalidate properties such as selectEl.selectedOptions. (@ExE-Boss)
• Fixed <input>'s src property, and <ins>/<del>'s cite property, to properly reflect as URLs.
• Fixed window.addEventLister, window.removeEventListener, and window.dispatchEvent to properly be inherited from EventTarget, instead of being distinct functions. (@ExE-Boss)
• Fixed errors that would occur if attempting to use a DOM object, such as a custom element, as an argument to addEventListener.
• Fixed errors that would occur when closing a window with outstanding requests to data: URLs.
• Fixed sporadic issues with the value of <input type="month"> that could occur in some time zones and for some times.
• Fixed document.implementation.createDocument() to return an XMLDocument, instead of a Document. (@ExE-Boss)
• Fixed running jsdom in a browser to detect globals more reliably. (@ExE-Boss)