Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Deprecation notice: Consider jsdom-global instead, a simpler alternative that also works outside of Mocha. mocha-jsdom still works, but jsdom-global is better supported.


Test frontend libraries in the console using Node.js, mocha and jsdom.



$ npm i --save-dev mocha-jsdom

npm version

Use jsdom() inside your describe(...) block (or the global context). It will turn your Node.js environment into a mock browser environment supporting the full DOM and browser API. The variables window, document, history (and so on) will then be available for use.

var jsdom = require('mocha-jsdom')
var expect = require('chai').expect

describe('mocha tests', function () {


  it('has document', function () {
    var div = document.createElement('div')


See examples/basic for an example of a basic setup.

Upgrading to v2.0.0

If you are coming from mocha-jsdom v1.x, remove jsdom if you're not using it before upgrading. jsdom is now a direct dependency of mocha-jsdom.

# using Yarn
yarn remove jsdom
yarn upgrade mocha-jsdom
# using npm
npm uninstall -S -D jsdom
npm upgrade mocha-jsdom

Node and io.js information

As of jsdom 4.0.0, jsdom now requires io.js and will not work with Node.js 0.12 or below.

How it works

mocha-jsdom is a simple glue to integrate jsdom to mocha.

Invoking jsdom() will inject before and after handlers to the current mocha suite which will setup and teardown jsdom. Here's what it does:

  • Window: global.window will be available as the jsdom.

  • Globals: global variables like document and history are propagated, and they're cleaned up after tests run.

  • Error handling: jsdom errors are sanitized so that their stack traces are shortened.

NB: Before you try this library, learn about jsdom first. In fact, you may be able to integrate jsdom into your tests without this library; this is mostly syntactic sugar and reasonable defaults.

Using with a library

Perfect for testing small DOM-consuming utilities in the console. See test/jquery.js for an example.

describe('mocha tests', function () {

  var $

  before(function () {
    $ = require('jquery')

  it('works', function () {
    document.body.innerHTML = '<div>hola</div>'


See examples/basic for an example of a basic setup.

Using with a library, alternate

You can also pass the source code via src:

describe('mocha tests', function () {
    src: fs.readFileSync('jquery.js', 'utf-8')



You can pass jsdom options:

describe('mocha tests', function () {
    parsingMode: 'xml'


Working with mocha --watch

When using with --watch, you my encounter strange errors from 3rd-party libraries like jQuery not working properly.

In these cases, use require('mocha-jsdom').rerequire instead of require(). This will ensure that the require() call will always happen.

var $
var jsdom = require('mocha-jsdom')
var rerequire = jsdom.rerequire


before(function () {
  $ = rerequire('jquery')

Special config

Other mocha-jsdom specific options:

  • globalize - propagates to values in window to global. defaults to true.

  • console - allows you to use console.log inside a jsdom script. defaults to true.

  • useEach - bind to Mocha's beforeEach/afterEach rather than before/after. defaults to false.

  • skipWindowCheck - skips checking of window at startup. When false, mocha-jsdom will throw an error if window already exists. Defaults to false.

Testling support

Yes, fully compatible with testling. A test suite using jsdom should be able to use testling.

See examples/basic for a setup that allows for testing via iojs (jsdom), testling, and mocha via the browser.


mocha-jsdom © 2014-2018 Rico Sta. Cruz. Released under the MIT License.
Authored and maintained by Rico Sta. Cruz with help from contributors (list).


Simple jsdom integration with mocha







No packages published