happy-dom

What is happy-dom?

happy-dom is a fast and lightweight DOM implementation for Node.js. It is designed to be compatible with the browser's DOM API, making it useful for server-side rendering, testing, and other scenarios where a DOM is needed outside of a browser environment.

What are happy-dom's main functionalities?

DOM Manipulation

happy-dom allows you to create and manipulate DOM elements just like you would in a browser environment. This is useful for server-side rendering and testing.

const { Window } = require('happy-dom');
const window = new Window();
const document = window.document;

const div = document.createElement('div');
div.textContent = 'Hello, World!';
document.body.appendChild(div);

console.log(document.body.innerHTML); // <div>Hello, World!</div>

Event Handling

happy-dom supports event handling, allowing you to add event listeners and dispatch events. This is useful for testing event-driven code.

const { Window } = require('happy-dom');
const window = new Window();
const document = window.document;

const button = document.createElement('button');
button.textContent = 'Click me';
button.addEventListener('click', () => {
  console.log('Button clicked!');
});
document.body.appendChild(button);

// Simulate a click event
const event = new window.Event('click');
button.dispatchEvent(event); // Button clicked!

Querying DOM Elements

happy-dom allows you to query DOM elements using methods like `querySelector` and `querySelectorAll`. This is useful for selecting and manipulating specific elements in the DOM.

const { Window } = require('happy-dom');
const window = new Window();
const document = window.document;

document.body.innerHTML = '<div class="test">Hello</div><div class="test">World</div>';
const elements = document.querySelectorAll('.test');

console.log(elements.length); // 2
console.log(elements[0].textContent); // Hello
console.log(elements[1].textContent); // World

Other packages similar to happy-dom

jsdom

jsdom is another popular DOM implementation for Node.js. It provides a more complete and detailed implementation of the DOM and other web standards. However, it is generally slower and more resource-intensive compared to happy-dom.

cheerio

cheerio is a fast, flexible, and lean implementation of core jQuery designed specifically for the server. It is not a full DOM implementation but provides a subset of jQuery functionality for parsing and manipulating HTML. It is faster and more lightweight than jsdom but less feature-rich.

linkedom

linkedom is a lightweight and fast DOM implementation for Node.js. It aims to be a minimalistic alternative to jsdom, providing essential DOM functionalities with better performance. It is similar to happy-dom in terms of performance and use cases.

README

About

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.

The goal of Happy DOM is to emulate enough of a web browser to be useful for testing, scraping web sites and server-side rendering.

Happy DOM focuses heavily on performance and can be used as an alternative to JSDOM.

DOM Features

• Custom Elements (Web Components)

• Shadow Root (Shadow DOM)

• Declarative Shadow DOM

• Mutation Observer

• Tree Walker

• Fetch

And much more..

Works With

• Google LitHTML

• Google LitElement

• React

• Angular

• Vue

Module Systems

• ESM
• CommonJS

Installation

npm install happy-dom

Usage

Happy DOM can be used as a simulated Browser or by using the Window class directly to quickly setup up a DOM.

Window

import { Window } from 'happy-dom';

const window = new Window({ url: 'https://localhost:8080' });
const document = window.document;

document.body.innerHTML = '<div class="container"></div>';

const container = document.querySelector('.container');
const button = document.createElement('button');

container.appendChild(button);

// Outputs "<div class="container"><button></button></div>"
console.log(document.body.innerHTML);

// Closes the window
await window.happyDOM.close();

Browser

import { Browser, BrowserErrorCaptureEnum } from 'happy-dom';

const browser = new Browser({ settings: { errorCapture: BrowserErrorCaptureEnum.processLevel } });
const page = browser.newPage();

// Navigates page
await page.goto('https://github.com/capricorn86');

// Clicks on link
page.mainFrame.document.querySelector('a[href*="capricorn86/happy-dom"]').click();

// Waits for all operations on the page to complete (fetch, timers etc.)
await page.waitUntilComplete();

// Outputs "GitHub - capricorn86/happy-dom: Happy DOM..."
console.log(page.mainFrame.document.title);

// Closes the browser
await browser.close();

Documentation

Read more about how to use Happy DOM in our Wiki.

Performance

Operation	JSDOM	Happy DOM
Import / Require	333 ms	45 ms
Parse HTML	256 ms	26 ms
Serialize HTML	65 ms	8 ms
Render custom element	214 ms	19 ms
querySelectorAll('tagname')	4.9 ms	0.7 ms
querySelectorAll('.class')	6.4 ms	3.7 ms
querySelectorAll('[attribute]')	4.0 ms	1.7 ms
querySelectorAll('[class~="name"]')	5.5 ms	2.9 ms
querySelectorAll(':nth-child(2n+1)')	10.4 ms	3.8 ms

See how the test was done here

Jest

Happy DOM provide with a package called @happy-dom/jest-environment that makes it possible to use Happy DOM with Jest.

Vitest

Vitest supports Happy DOM out of the box.

Global Registration

Happy DOM provide with a package called @happy-dom/global-registrator that can register Happy DOM globally. It makes it possible to use Happy DOM for testing in a Node environment.

Sister Projects

Sponsors