$ npm install jsdom
If this gives you trouble with errors about installing Contextify, especially on Windows, see below.
see: mailing list
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.
You can use it with a URL
// Count all of the links from the Node.js build pagevar jsdom = require"jsdom";jsdomenv""""console.log"there have been" window$"a"length "nodejs releases!";;
or with raw HTML
// Run some jQuery on a html fragmentvar jsdom = require"jsdom";jsdomenv'<p><a class="the-link" href="">jsdom\'s Homepage</a></p>'""console.log"contents of a.the-link:" window$"a.the-link"text;;
or with a configuration object
// Print all of the news items on hackernewsvar jsdom = require"jsdom";jsdomenvurl: ""scripts: ""var $ = window$;console.log"HN Links";$"td.title:not(:last) a"eachconsole.log" -" $thistext;;;
// Print all of the news items on hackernewsvar jsdom = require"jsdom";var fs = require"fs";var jquery = fsreadFileSync"./jquery.js" "utf-8";jsdomenvurl: ""src: jqueryvar $ = window$;console.log"HN Links";$"td.title:not(:last) a"eachconsole.log" -" $thistext;;;
jsdomenvstring scripts config callback;
The arguments are:
string: may be a URL, file name, or HTML fragment
scripts: a string or array of strings, containing file names or URLs that will be inserted as
config: see below
callback: takes two arguments
error: either an
Errorobject if something failed initializing the window, or an array of error messages from the DOM if there were script errors
window: a brand new
jsdomenvhtml// free memory associated with the windowwindowclose;;
If you would like to specify a configuration object only:
config.html: a HTML fragment
config.file: a file which jsdom will load HTML from; the resulting window's
location.hrefwill be a
config.url: sets the resulting window's
config.fileare not provided, jsdom will load HTML from this URL.
config.jar: a custom cookie jar, if desired; see mikeal/request documentation.
referrer: the new document will have this referrer.
cookie: manually set a cookie value, e.g.
'key=value; expires=Wed, Sep 21 2011 12:00:00 GMT; path=/'.
cookieDomain: a cookie domain for the manually set cookie; defaults to
config.done is required, as is one of
If you want to spawn a document/window and specify all sorts of options this is the section for you. This section covers the
var jsdom = require"jsdom"jsdom;var doc = jsdommarkup level options;var window = docparentWindow;
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
<body> tags. Document fragments are also supported (including
""), and will behave as sanely as possible (e.g. the resulting document will lack the
documentElement properties if the corresponding elements aren't included).
null (which means level3) by default, but you can pass another level if you'd like.
var jsdom = require"jsdom";var doc = jsdomjsdom"<html><body></body></html>" jsdomlevel1 "core";
options See the explanation of the
config object above.
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:
Documentusing the jsdom builder (
var jsdom = require"jsdom"jsdom;var doc = jsdom"<html><body></body></html>" nullfeatures: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).
require"jsdom"defaultDocumentFeatures =FetchExternalResources: "script"ProcessExternalResources: false;
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.
["script", "img", "css", "frame", "iframe", "link"]or
Enables/disables fetching files over the file system/HTTP.
/url to be skipped/or
Do not download and process resources with url matching a regular expression.
jsdom includes support for using the canvas package to extend any
<canvas> elements with the canvas API. To make this work, you need to include canvas as a dependency in your project, as a peer of jsdom. If jsdom can find the canvas package, it will use it, but if it's not present, then
<canvas> elements will behave like
var jsdom = require"jsdom";var doc = new jsdomlevel1 "core"Document;console.logdocnodeName; // outputs: #document
var jsdom = require"jsdom"jsdom;var document = jsdom"<html><head></head><body>hello world</body></html>";var window = documentparentWindow;console.logwindowdocumentinnerHTML;// output: "<html><head></head><body>hello world</body></html>"console.logwindowinnerWidth;// output: 1024console.logtypeof windowdocumentgetElementsByClassName;// outputs: function
var jsdom = require"jsdom";var window = jsdomjsdomparentWindow;jsdomjQueryifywindow ""window$"body"append'<div class="testing">Hello World, It works</div>';console.logwindow$".testing"text;;
var jsdom = require"jsdom"jsdom;var window = jsdomparentWindow;window__myObject = foo: "bar" ;var scriptEl = windowdocumentcreateElement"script";scriptElsrc = "anotherScript.js";windowdocumentbodyappendChildscriptEl;// anotherScript.js will have the ability to read `window.__myObject`, even// though it originated in Node!
First you'll want to
npm install. To run all the tests, use
npm test, which just calls
test/runner directly, you can slice and dice which tests your want to run from different levels. Usage is as follows:
test/runner --helpRun the jsdom test suiteOptions:-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
Contextify is a dependency of jsdom, used for running
<script> tags within the
that pretends to be a browser environment instead of a server. You can see how this is an important feature.
Unfortunately, getting C++ compiled within npm's installation system can be tricky, especially for Windows users. Thus, one of the most common problems with jsdom is trying to use it without the proper compilation tools installed. Here's what you need to compile Contextify, and thus to install jsdom:
There are some slight modifications to this that can work; for example full versions of Visual Studio usually work, and sometimes you can even get an x64 version of Node.js working too. But it's tricky, so start with the basics!
You'll need various build tools installed, like
make, Python 2.7, and a compiler toolchain. How to install these will
be specific to your distro, if you don't already have them.