jsdom
A pure-JavaScript implementation of web standards like DOM and HTML for Node.js, enabling browser-like environments for testing and scraping.
What is jsdom?
jsdom is a pure-JavaScript implementation of web standards like the DOM and HTML specifications for use with Node.js. It creates a headless browser environment that allows developers to parse and manipulate HTML, execute scripts, and interact with web APIs without a real browser. This solves the problem of needing a browser-like environment for tasks such as unit testing frontend code or scraping web content in Node.js applications.
Node.js developers who need to test web applications, scrape websites, or simulate browser behavior in server-side environments. It is particularly useful for those writing tests for frontend code or building tools that require DOM manipulation without a GUI.
Developers choose jsdom because it provides a lightweight, standards-compliant way to emulate a browser environment directly in Node.js, avoiding the overhead of a full browser. Its configurability and focus on web standards make it ideal for testing and automation scenarios where a real browser is unnecessary or impractical.
Overview
A JavaScript implementation of various web standards, for use with Node.js
Use Cases
Best For
- Unit testing frontend JavaScript code in Node.js environments
- Scraping web pages and extracting data without a headless browser
- Simulating browser behavior for server-side rendering (SSR) tests
- Running automated tests that require DOM manipulation
- Building tools that need to parse and interact with HTML programmatically
- Creating custom testing environments for web standards compliance
Not Ideal For
- Applications requiring accurate CSS layout calculations or visual rendering, such as pixel-perfect UI testing
- Projects that depend on browser navigation features, like testing single-page app routing without manual page recreation
- Real-time web applications needing unimplemented Web APIs, e.g., WebGL, WebRTC, or advanced media playback
- High-performance web scraping where a full headless browser like Puppeteer might handle dynamic content more reliably
Pros & Cons
Pros
Implements WHATWG DOM and HTML specifications, providing a realistic browser-like API that ensures accurate emulation for testing and scraping, as noted in its focus on web standards.
Supports options like URL, referrer, and virtual consoles, allowing tailored behavior such as custom resource loading with interceptors and dispatchers for advanced use cases.
Offers multiple modes from safe to dangerous script running, enabling controlled JavaScript execution within the DOM, including external scripts via the runScripts option.
Can load subresources like scripts and styles when configured, mimicking browser behavior with customizable interceptors and user-agent settings for realistic simulations.
Cons
Lacks implementation for browser navigation features like changing window.location.href, requiring workarounds such as creating new JSDOM instances for multi-page scenarios.
Does not calculate CSS layout or visual rendering, returning dummy values for properties like getBoundingClientRect, which limits use cases for UI testing that depends on element positioning.
Enabling script execution via runScripts: 'dangerously' can expose the Node.js environment to untrusted code, necessitating careful security measures to prevent machine compromise.
Asynchronous script loading lacks built-in completion detection, making it challenging to determine when the DOM is fully ready without manual polling or custom callbacks.
Frequently Asked Questions
Related Projects
huskyGit hooks made easy 🐶 woof!
dotenvLoads environment variables from .env for nodejs projects.
patch-packageFix broken node modules instantly 🏃🏽♀️💨
execaProcess execution for humans
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.