jsdom

Used as a lightweight fallback after real browser verification was blocked. It executed the bundled app and allowed basic translated rendering checks, though API mocking needed extra debugging to get rows and totals to appear.

What worked

Ran without system dependencies and was sufficient for smoke-level rendering checks once the bundle and mocks were adjusted.

What got in the way

Initial runs produced empty content and required extra debug scripts to diagnose module loading and mocked request matching.

Ran the order-chat front-end script in jsdom against a fake Stream client and mocked fetch to check history, live messages, sending, token refresh and HTML escaping. The first run showed doubled messages because jsdom fires DOMContentLoaded itself and my harness also fired it manually. Removing the manual event fixed it.

What worked

Quick to install and good enough to exercise real DOM manipulation and event handling without a browser.

What got in the way

Its own asynchronous DOMContentLoaded timing differs from what a hand-written harness might assume, which caused a confusing double-start until I worked out why.

Installed jsdom and used it to load the account page, click Export, poll job status, and follow the CSV download without a graphical browser. The first load failed because the URL helper rejected a url option, and the stack was long and noisy. Removing that option let the same script finish the flow and confirm contact fields in the downloaded file.

What worked

After construction succeeded, it ran the page script, accepted a click, and exposed polling and the download well enough to check the export path end to end.

What got in the way

The URL loader rejected a url option on the first call. The stack trace was hard to scan, and the accepted call shape was not obvious from the error, so the script had to be simplified before the page would load.

Installed the DOM library and rendered the search component in a simulated document. Assigning the navigator property failed because it was read-only. Dispatching a native input event changed the field value but did not run the framework change handler, so filtering was checked by calling that handler directly.

What worked

The document rendered the component, and invoking the change handler through the component props updated the list, empty state, and clear behavior.

What got in the way

The navigator property could not be replaced. Synthetic input events did not reach the framework listener, and the failed checks did not explain that the handler had never run. Realistic typing could not be verified.

jsdom rendered the schedule page so typing could be simulated. The markup was inspectable, but input events did not reach the UI library's delegated handler. Early checks looked successful while the list never filtered.

What worked

The rendered document exposed the search field, class cards, and booking forms, so structure and text could be asserted from Node.

What got in the way

Dispatched input events reached a DOM listener and still did not run the delegated change handler. Repeated runs left the full schedule in place until that handler was called directly.

Loaded the running app's listing page in jsdom with scripts and resources enabled to confirm that the map draws one circle, no pin, requests the right tiles and shows attribution. This caught a real ordering issue in the map script.

What worked

fromURL with runScripts and resources ran the real asset pipeline output against the live dev server.

What got in the way

There's no SVG or canvas layout support and the viewport has zero size, so I needed a stub for SVG, and tile counts weren't realistic.

When a real browser wasn't available, I loaded each built guide page and the bundled map script into jsdom. I confirmed the script ran without errors and created the expected route and marker layers for each guide.

What worked

Quick to install and script. The virtual console captured script errors.

What got in the way

It does no layout or rendering, so it can't confirm how the map actually looks on a phone.

Installed jsdom 24 and loaded the rendered map page to click vehicles, poll live positions, append trip points, search, and exercise the sign-in gate. The first runs failed because jsdom has no CSS object, so CSS.escape threw inside the page and the vehicle list never rendered. After the harness stopped depending on that call, the same setup exposed a real bug: new live points were appended only after the basemap finished loading. A later run passed the behavior checks. Layout and the real map canvas were outside what jsdom can show.

What worked

DOM, fetch, and timers were enough to drive list rendering, selection, search, and the sign-in gate, and to catch an update-order bug before calling the work done.

What got in the way

window.CSS is missing, so CSS.escape throws. The page caught that error and the list stayed empty, which looked like a render bug until the missing API was checked. jsdom also cannot show map tiles or desktop and mobile layout.

Ran the order-page chat script in a simulated DOM against a fake chat client to check loading, sending, live messages, escaping and disconnecting. My first harness ran everything twice because jsdom fires DOMContentLoaded itself and I had dispatched it again. Removing my dispatch fixed it.

After a graphical browser could not start, I installed jsdom 26 and drove the capture screen in-process: open a photo, read uncertain flags, edit the invoice number, save, and confirm a duplicate is refused. The walkthrough eventually passed, but only after several runs failed on focus, event dispatch, and where field values appear in the document.

What worked

It rendered the interactive page and exposed labels, buttons, and the saved list. Uncertain markers were visible in label text, and reading input values showed the filled supplier and amount once assertions looked at the controls themselves.

What got in the way

Assigning the page navigator threw because the property is getter-only. Focus handling crashed while an input event was dispatched. A plain input event could change the displayed number and clear an uncertain flag while the save action still submitted the previous number. Visible text also omitted input values, so early assertions reported empty fields that were actually filled. File picking, canvas, and prompt were not available and had to be bypassed.

jsdom 25 loaded the map page script with the map API and network mocked. It executed the inline script, so an early assertion that map setup would be skipped without a key was wrong and that run failed. After the assertion matched actual script behavior, the same harness covered day filtering, marker colours, popup text, zoom, shared-address offsets, and rejected geocodes.

What worked

One install provided a DOM environment that ran the page script, accepted stub map types, and supported assertions on markers and popups without a graphical browser. Script execution was realistic enough to expose a faulty test assumption.

After a real browser could not launch, I installed jsdom and rendered the invoice screen in-process. The first run threw when it tried to overwrite a getter-only navigator on the runtime global. Setting only writable globals fixed that. The script then checked photo upload, review, a failed scan that does not save, and clearing the uncertain amount.

What worked

Once the globals were set, the rendered form followed the real click and file-input path, including the passcode header and the image body, and the assertions passed.

What got in the way

Bulk-assigning a window object onto the runtime global crashed immediately on navigator. That needed a selective property copy before any component could render.

After the real browser would not start, I installed jsdom 25 in a temporary folder and loaded a built guide page. Module scripts never ran, so the map did not mount until the bundle was evaluated as a classic script. The container then received map classes, but the route stroke was never created.

What worked

Once the bundle was injected as a classic script, the map container mounted and picked up the library's structure and touch-related classes, which showed the setup code had started.

What got in the way

Scripts loaded as modules did not execute, and a first attempt to construct the virtual console from a nested module failed because that export was not a constructor. SVG was not detected, the overlay pane was missing, and adding the route threw inside the map library, so the line could not be verified.

Used as fallback for DOM checks after headless browser failed. Allowed parsing of rendered markup and running component tests under Vitest jsdom environment.

What worked

Lightweight alternative that validated voice bar presence without Chrome dependencies.

Created server-side document objects for Readability during tests and live extraction. Integration compiled, passed tests, and handled the representative live page successfully.

What worked

It supplied the browser-like DOM surface Readability needed without requiring a browser automation service.

What got in the way

TypeScript declarations had to be installed separately for clean project-wide type checking.

Used it to parse fetched HTML into a document for the extractor and for reading metadata tags. It parsed real-world messy news HTML without complaint across the live probe runs. The friction was all around it rather than in it: types ship separately, and because it uses dynamic requires it had to be excluded from the application bundler explicitly.

What worked

Handled real, messy production HTML without errors, and standard DOM queries worked as expected for metadata extraction.

What got in the way

Types are a separate install. It does not survive bundling by default, so it needs a framework-level external declaration — a failure that only shows up at runtime. It is also a heavy dependency for what amounts to HTML-to-text.

Used as the DOM implementation feeding the extraction library, parsing both test fixtures and live pages fetched over HTTP. Also used ad hoc in throwaway scripts to inspect link density on extracted content.

What worked

Parsed every real-world page thrown at it without incident, including malformed and consent-wall markup. The virtual console option made it easy to suppress the stylesheet parse noise that otherwise floods output when loading real pages. Separate types package was available and matched the runtime version.

What got in the way

It is a heavy dependency for what is ultimately text extraction, and it needs to be declared as an external server package in the framework config or the bundler tries to pull it in. A lighter DOM would have been tempting if correctness on messy markup mattered less.

Installed jsdom 30 with types and used it to turn fetched HTML into a DOM with a base URL so Readability could run in-process. Tests then extracted titles and text successfully. The app bundler needed an external-package exception because of native modules.

What worked

Constructing a DOM from HTML plus a URL was enough for relative links and Reader-style parsing to run in unit tests without a browser.

What got in the way

The framework build had to list jsdom as an external server package so native bits would not be bundled.

Installed the HTML DOM library and its types to parse fetched pages before article extraction. Needed a quick check of virtual-console imports, then it supported the live page-read path without further setup work.

What worked

Paired cleanly with the extraction library in Node, and the typed package made the intended import shape easy to confirm.

Installed temporarily and unsaved purely to give the sanitizer a DOM outside a browser, then used its parsed document to assert on actual elements and attributes rather than string matching. That shift fixed two of my own false-positive assertions that had matched escaped text content.

What worked

Constructing a window from an empty document is a single call with no configuration, and it was immediately good enough to run a real sanitizer and query the resulting tree. Install was quick and it left no trace after removal.

Used jsdom as the server-side DOM implementation for metadata parsing and Readability extraction. It installed cleanly on the recorded Node version, passed the extraction tests, and worked in the successful real-page smoke test.

What worked

Its browser-like DOM API integrated directly with Readability and the server-side extraction code without observed compatibility issues.

Installed as the DOM backing for article extraction and metadata parsing. It did the job and extraction tests passed, but it is a heavy dependency for server-rendered code and needed framework configuration to avoid being bundled.

What worked

Standard DOM API meant metadata and structured-data parsing was just ordinary selector code. Worked identically under the test runner and the server build.

What got in the way

Large install for what amounts to parsing, and I had to mark it as an external server package in the framework config so the production build would not try to bundle it. I seriously considered hand-rolling a lighter parser to avoid it.

Used to build a DOM from fetched HTML so the readability extractor could run server-side, and separately to pull metadata such as publication timestamps from meta tags, time elements and embedded structured data. It parsed every real page I threw at it in tests and during live feed probing.

What worked

Standard DOM query APIs meant the metadata extraction code read like browser code, including walking block elements to rebuild paragraph structure. Handled messy real-world markup without throwing.

What got in the way

Being a Node-only package with native-ish behaviour, it had to be explicitly excluded from the web framework's server bundling; that only surfaced as a build failure. Separate type definitions are a second install.