jsdom

What is jsdom?

The jsdom npm package is a pure-JavaScript implementation of many web standards, notably the WHATWG DOM and HTML Standards, for use with Node.js. It is designed to create a web browsing environment similar to what you would find in a web browser, allowing for the parsing and manipulation of HTML and XML documents. It can be used for testing web pages and JavaScript libraries in a Node.js environment.

What are jsdom's main functionalities?

DOM Manipulation

This feature allows you to manipulate the DOM of a document. The code sample demonstrates how to append a new list item to an unordered list.

const { JSDOM } = require('jsdom');
const dom = new JSDOM(`<ul><li>Item 1</li></ul>`);
const ul = dom.window.document.querySelector('ul');
ul.appendChild(dom.window.document.createElement('li')).textContent = 'Item 2';
console.log(dom.window.document.body.innerHTML);

Event Handling

This feature enables you to simulate and handle events. The code sample shows how to simulate a click event on a button and handle it by logging a message.

const { JSDOM } = require('jsdom');
const dom = new JSDOM(`<button id='myButton'>Click me</button>`);
const button = dom.window.document.querySelector('#myButton');
button.addEventListener('click', () => console.log('Button clicked!'));
button.click();

Fetching Remote Content

This feature allows you to fetch remote content and create a JSDOM instance from it. The code sample demonstrates fetching and logging the HTML content of a webpage.

const { JSDOM } = require('jsdom');
JSDOM.fromURL('https://example.com/').then(dom => {
  console.log(dom.serialize());
});

Running Scripts

This feature allows you to run scripts within the context of the JSDOM instance. The code sample shows how to execute a script that changes the text content of the document body.

const { JSDOM } = require('jsdom');
const dom = new JSDOM(`<script>document.body.textContent = 'Hello, world!';</script>`);
console.log(dom.window.document.body.textContent);

Other packages similar to jsdom

cheerio

Cheerio is a fast, flexible, and lean implementation of core jQuery designed specifically for the server. It does not implement a full web browser API as jsdom does, but it is often used for simpler DOM manipulation tasks and is faster due to its focus on a subset of use cases.

puppeteer

Puppeteer is a Node library which provides a high-level API to control Chrome or Chromium over the DevTools Protocol. It is more powerful for tasks like web scraping, automated testing, and rendering since it operates over a real browser, but it is heavier and more resource-intensive compared to jsdom.

phantomjs

PhantomJS is a headless WebKit scriptable with a JavaScript API. It has similar capabilities to Puppeteer but uses WebKit as the rendering engine instead of Chromium. It is no longer actively maintained, but it was once a popular choice for headless website testing.

README

jsdom

A javascript implementation of the W3C DOM.

Install

npm install jsdom

or

git clone http://github.com/tmpvar/jsdom.git
cd jsdom
npm link

Human contact

see: mailing list

Easymode

Bootstrapping a DOM is generally a difficult process involving many error prone steps. We didn't want jsdom to fall into the same trap and that is why a new method, jsdom.env(), has been added in jsdom 0.2.0 which should make everyone's lives easier.

with URL

// Count all of the links from the nodejs build page
var jsdom = require("jsdom");

jsdom.env("http://nodejs.org/dist/", [
  'http://code.jquery.com/jquery-1.5.min.js'
],
function(errors, window) {
  console.log("there have been", window.$("a").length, "nodejs releases!");
});

or with raw html

// Run some jQuery on a html fragment
var jsdom = require('jsdom');

jsdom.env('<p><a class="the-link" href="http://jsdom.org>JSDOM\'s Homepage</a></p>', [
  'http://code.jquery.com/jquery-1.5.min.js'
],
function(errors, window) {
  console.log("contents of a.the-link:", window.$("a.the-link").text());
});

or with a configuration object

// Print all of the news items on hackernews
var jsdom = require('jsdom');

jsdom.env({
  html: 'http://news.ycombinator.com/',
  scripts: [
    'http://code.jquery.com/jquery-1.5.min.js'
  ],
  done: function(errors, window) {
    var $ = window.$;
    console.log('HN Links');
    $('td.title:not(:last) a').each(function() {
      console.log(' -', $(this).text());
    });
  }
});

or with raw javascript source

// Print all of the news items on hackernews
var jsdom  = require('jsdom');
var fs     = require('fs');
var jquery = fs.readFileSync("./jquery-1.6.2.min.js").toString();

jsdom.env({
  html: 'http://news.ycombinator.com/',
  src: [
    jquery
  ],
  done: function(errors, window) {
    var $ = window.$;
    console.log('HN Links');
    $('td.title:not(:last) a').each(function() {
      console.log(' -', $(this).text());
    });
  }
});

How it works

jsdom.env is built for ease of use, which is rare in the world of the DOM! Since the web has some absolutely horrible javascript on it, as of jsdom 0.2.0 jsdom.env will not process external resources (scripts, images, etc). If you want to process the javascript use one of the methods below (jsdom.jsdom or jsdom.jQueryify)

jsdom.env(html, [scripts], [config], callback)

• html (required) May be a url, html fragment, or file

• scripts (optional) May contain files or urls

• callback (required) Takes 2 arguments:

  • errors : array of errors
  • window : a brand new window

  example: jsdom.env(html, function(errors, window) {})

If you would like to specify a configuration object

jsdom.env({ /* config */ })

• config.html : see html above
• config.scripts : see scripts above
• config.src : An array of javascript strings that will be evaluated against the resulting document. Similar to scripts, but it accepts javascript instead of paths/urls.
• config.done : see callback above
• config.document :
• referer : the new document will have this referer
• cookie : manually set a cookie value i.e. 'key=value; expires=Wed, Sep 21 2011 12:00:00 GMT; path=/'
• config.features : see Flexibility section below. Note: the default feature set for jsdom.env does not include fetching remote javascript and executing it. This is something that you will need to carefully enable yourself.

For the hardcore

If you want to spawn a document/window and specify all sorts of options this is the section for you. This section covers the jsdom.jsdom method:

var jsdom  = require("jsdom").jsdom,
    doc    = jsdom(markup, level, options),
    window = doc.createWindow();

• markup is an html/xml document to be parsed. You can also pass null or an undefined value to get a basic document with empty head and body tags. Document fragments are also supported (including ""), and will behave as sanely as possible (eg. the resulting document will lack the head, body and documentElement properties if the corresponding elements aren't included).

• level is null (which means level3) by default, but you can pass another level if you'd like.

   var jsdom = require('jsdom'),
       doc   = jsdom.jsdom('<html><body></body></html>', jsdom.dom.level1.core)
  

• options see the Flexibility section below

Flexibility

One of the goals of jsdom is to be as minimal and light as possible. This section details how someone can change the behavior of Documents on the fly. These features are baked into the DOMImplementation that every Document has, and may be tweaked in two ways:

1. When you create a new Document using the jsdom builder (require('jsdom').jsdom())

    var jsdom = require('jsdom').jsdom,
        doc   = jsdom("<html><body></body></html>", null, {
          features: {
            FetchExternalResources : ['img']
          }
        });
   

Do note, that this will only affect the document that is currently being created. All other documents will use the defaults specified below (see: Default Features)

1. Previous to creating any documents you can modify the defaults for all future documents

    require('jsdom').defaultDocumentFeatures = {
      FetchExternalResources   : ['script'],
      ProcessExternalResources : false,
      MutationEvents           : false,
      QuerySelector            : false
    }
   

Default Features

Default features are extremely important for jsdom as they lower the configuration requirement and present developers a set of consistent default behaviors. The following sections detail the available features, their defaults, and the values that jsdom uses.

FetchExternalResources Default: ['script'] Allowed: ['script', 'img', 'css', 'frame', 'link'] or false

Enables/Disables fetching files over the filesystem/http

ProcessExternalResources default: ['script'] allowed: ['script'] or false

Disabling this will disable script execution (currently only javascript).

MutationEvents default: '2.0' allowed : '2.0' or false

Initially enabled to be up to spec. Disable this if you do not need mutation events and want jsdom to be a bit more efficient.

Note: ProcessExternalResources requires this to be enabled

QuerySelector default : false allowed : true

This feature is backed by sizzle but currently causes problems with some libraries. Enable this if you want document.querySelector and friends, but be aware that many libraries feature detect for this, and it may cause you a bit of trouble.

More Examples

Creating a document-less window

var jsdom  = require("jsdom"),
    window = jsdom.createWindow();

console.log(window.document);
// output: undefined

Creating a document

var jsdom = require("jsdom"),
    doc   = new (jsdom.dom.level1.core.Document)();
console.log(doc.nodeName);
// outputs: #document

Creating a browser-like BOM/DOM/Window

var jsdom    = require("./lib/jsdom").jsdom,
    document = jsdom("<html><head></head><body>hello world</body></html>"),
    window   = document.createWindow();

console.log(window.document.innerHTML);
// output: '<html><head></head><body>hello world</body></html>'

console.log(window.innerWidth)
// output: 1024

console.log(typeof window.document.getElementsByClassName);
// outputs: function

jQueryify

var jsdom  = require("jsdom"),
    window = jsdom.jsdom().createWindow();

jsdom.jQueryify(window, 'http://code.jquery.com/jquery-1.4.2.min.js' , function() {
  window.$('body').append('<div class="testing">Hello World, It works</div>');
  console.log(window.$('.testing').text());
});

Test Compliance:

 level1/core        531/531      100%
 level1/html        238/238      100%
 level1/svg         527/527      100%
 level2/core        283/283      100%
 level2/html        687/687      100%
 level2/style           4/4      100%
 level2/extra           4/4      100%
 level3/xpath         93/93      100%
 window/index           5/5      100%
 window/script          8/8      100%
 window/frame         14/14      100%
 sizzle/index         12/15       80%
 jsdom/index          63/63      100%
--------------------------------------
TOTALS: 3/2472 failed; 99% success
TIME: 16730ms

Running the tests

First you'll want to npm install -g nodeunit then npm install --dev

Using test/runner you can slice and dice which tests your want to run from different levels. Usage is as follows:

test/runner --help
Run the jsdom test suite

Options:
-s, --suites     suites that you want to run. ie: -s level1/core,1/html,html [string]
-f, --fail-fast  stop on the first failed test
-h, --help       show the help
-t, --tests      choose the test cases to run. ie: -t jquery