Happy DOM is a JavaScript implementation of a web browser without its graphical user interface. It includes many web standards from WHATWG DOM and HTML.
happy-dom is a JavaScript implementation of a web browser environment without the graphical interface. It provides a complete DOM, HTML parser, and many WHATWG web standards in a pure JavaScript package. Unlike a headless browser like Puppeteer, happy-dom doesn't run a real browser engine—it simulates browser APIs in Node.js, making it extremely lightweight and fast.
The package emerged as a performance-focused alternative to JSDOM, delivering 5-10x faster execution across common operations like HTML parsing, DOM manipulation, and selector queries. With over 4.5 million weekly downloads, it has become a popular choice for developers who need to test DOM-dependent code without the overhead of launching an actual browser. It's particularly well-suited for unit testing frameworks like Vitest and Jest, where test execution speed directly impacts developer productivity.
happy-dom implements extensive web standards including Custom Elements, Shadow DOM, Fetch API, Web Storage, and even media elements. This comprehensive API surface means most DOM-dependent code runs without modification. The library is actively maintained with 645+ releases and powers approximately 47,500 projects. It's designed for testing web components, server-side rendering React/Vue/Svelte applications, and web scraping scenarios where you need to parse and interact with HTML documents programmatically.
The package shines in CI/CD pipelines where test suite execution time matters. By avoiding the overhead of spawning browser processes, it enables faster feedback loops during development. However, it's important to understand that happy-dom is a simulation—it won't catch rendering bugs, browser-specific quirks, or issues that only surface in real browser engines. It's a tool for unit and integration testing, not end-to-end testing.
import { Window } from 'happy-dom';
// Create a browser-like environment
const window = new Window();
const document = window.document;
// Parse HTML and interact with DOM
document.body.innerHTML = `
<div id="app">
<h1>Hello World</h1>
<button id="counter">Count: 0</button>
</div>
`;
// Query and manipulate elements
const button = document.querySelector('#counter');
let count = 0;
button.addEventListener('click', () => {
count++;
button.textContent = `Count: ${count}`;
});
// Simulate user interaction
button.click();
console.log(button.textContent); // "Count: 1"
// Test custom elements
class MyComponent extends window.HTMLElement {
connectedCallback() {
this.innerHTML = '<p>Custom element rendered</p>';
}
}
window.customElements.define('my-component', MyComponent);
document.body.innerHTML = '<my-component></my-component>';
const component = document.querySelector('my-component');
console.log(component.innerHTML); // "<p>Custom element rendered</p>"
// Test async operations with Fetch API
await window.happyDOM.whenAsyncComplete();
// Clean up when done
await window.close();Unit Testing Web Components: Test custom elements and Shadow DOM functionality without launching a browser. Validate component lifecycle methods, event handling, and DOM manipulation logic in isolation with fast execution times ideal for TDD workflows.
Framework Testing with Vitest/Jest: Integrate with modern testing frameworks to test React, Vue, Svelte, or Angular components. happy-dom provides the browser environment these frameworks expect, allowing you to use Testing Library and other DOM testing utilities without configuring a headless browser.
Server-Side Rendering (SSR): Render web components or framework components server-side by providing a DOM environment in Node.js. This enables pre-rendering HTML for SEO, generating static sites, or implementing SSR architectures without browser dependencies.
Web Scraping and HTML Parsing: Parse HTML documents and interact with them using familiar DOM APIs like querySelector, querySelectorAll, and element manipulation methods. More convenient than raw HTML parsers when you need to execute inline scripts or evaluate dynamic content.
Snapshot Testing: Generate HTML snapshots of components for regression testing. The fast serialization performance makes it practical to snapshot-test large component trees without slowing down your test suite significantly.
npm install happy-dompnpm add happy-dombun add happy-dom