Skip to content

Latest commit

 

History

History
314 lines (224 loc) · 9 KB

README.md

File metadata and controls

314 lines (224 loc) · 9 KB
Raw

Happy DOM Logo

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-dom

Usage

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({
	innerWidth: 1024,
	innerHeight: 768,
	url: 'http://localhost:8080'
});
const document = window.document;

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({
	innerWidth: 1024,
	innerHeight: 768,
	url: 'http://localhost:8080'
});
const document = window.document;

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

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();

setInnerWidth()

Sets the property window.innerWidth and dispatches a "resize" event.

window.happyDOM.setInnerWidth(1920);

setInnerHeight()

Sets the property window.innerHeight and dispatches a "resize" event.

window.happyDOM.setInnerHeight(1080);

setURL()

Sets the property window.location.href.

window.happyDOM.setURL('https://localhost:3000');

Settings

Settings can be sent to the constructor or by setting them on the "window.happyDOM.settings" property.

Set by constructor:

const window = new Window({
	innerWidth: 1920,
	innerHeight: 1080,
	url: 'https://localhost:8080',
	settings: {
		disableJavaScriptFileLoading: true,
		disableJavaScriptEvaluation: true,
		disableCSSFileLoading: true,
		enableFileSystemHttpRequests: true
	}
});

Set by property:

const window = new Window();

window.happyDOM.settings.disableJavaScriptFileLoading = true;
window.happyDOM.settings.disableJavaScriptEvaluation = true;
window.happyDOM.settings.disableCSSFileLoading = true;
window.happyDOM.settings.enableFileSystemHttpRequests = true;

disableJavaScriptFileLoading

Set it to "true" to disable JavaScript file loading. Defaults to "false".

disableJavaScriptEvaluation

Set it to "true" to completely disable JavaScript evaluation. Defaults to "false".

disableCSSFileLoading

Set it to "true" to disable CSS file loading using the HTMLLinkElement. Defaults to "false".

enableFileSystemHttpRequests

Set it to "true" to enable file system HTTP requests using XMLHttpRequest. Defaults to "false".

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.