2.0.0 • Public • Published

    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).



    npm i mocha-jsdom

    DownloadsWeekly Downloads






    Unpacked Size

    90 kB

    Total Files


    Last publish


    • rstacruz