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
Installation
npm install happy-domUsage
Basic Usage
A simple example of how you can use Happy DOM.
import { Window } from 'happy-dom';
const window = new Window();
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);VM Context
The default Window class is a VM context. A VM context will execute JavaScript code scoped within the context where the Window instance will be the global object.
import { Window } from 'happy-dom';
const window = new Window();
const document = window.document;
window.location.href = 'http://localhost:8080';
document.write(`
<html>
<head>
<title>Test page</title>
</head>
<body>
<div class="container">
<!–– Content will be added here -->
</div>
<script>
const element = document.createElement('div');
const container = document.querySelector('.container');
element.innerHTML = 'Test';
container.appendChild(element);
</script>
</body>
</html>
`);
// Will output "Test"
console.log(document.querySelector('.container div').innerHTML);Global Context
Happy DOM exports a class called GlobalWindow, which can be used to run Happy DOM in the global context instead of the default behaviour of running in a VM context.
import { Window, GlobalWindow } from 'happy-dom';
const vmWindow = new Window();
const globalWindow = new GlobalWindow();
// Will output "false"
console.log(vmWindow.Array === global.Array);
// Will output "true"
console.log(globalWindow.Array === global.Array);
globalWindow.eval('global.test = 1');
// Will output "1"
console.log(global.test);Server-Side Rendering of Web Components
The example below will show you how to setup a Node VM context to render a page with custom elements (web components) in Happy DOM. We can then use a new web feature called Declarative Shadow DOM to include the shadow roots in the HTML output.
Declarative Shadow DOM is only supported by Chromium based browsers. Unsupported browsers should safely fallback to being rendered using Javascript.
import { Window } from 'happy-dom';
const window = new Window();
const document = window.document;
window.location.href = 'http://localhost:8080';
document.write(`
<html>
<head>
<title>Test page</title>
</head>
<body>
<div>
<my-custom-element>
<span>Slotted content</span>
</my-custom-element>
</div>
<script>
class MyCustomElement extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
}
connectedCallback() {
this.shadowRoot.innerHTML = \`
<style>
:host {
display: inline-block;
background: red;
}
</style>
<div><slot></slot></div>
\`;
}
}
customElements.define('my-custom-element', MyCustomElement);
</script>
</body>
</html>
`);
/*
Will output:
<my-custom-element>
<span>Slotted content</span>
<template shadowroot="open">
<style>
:host {
display: inline-block;
background: red;
}
</style>
<div><slot></slot></div>
</template>
</my-custom-element>
*/
console.log(document.body.querySelector('div').getInnerHTML({ includeShadowRoots: true }));Additional Features
Happy DOM exposes two functions that may be useful when working with asynchrounous code.
whenAsyncComplete()
Returns a Promise that is resolved when all async tasks has been completed.
window.happyDOM.whenAsyncComplete().then(() => {
// Do something when all async tasks are completed.
});cancelAsync()
This method will cancel all running async tasks.
window.setTimeout(() => {
// This timeout will be canceled
});
window.happyDOM.cancelAsync();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.
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.