Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    Run client-side Mocha tests in PhantomJS or SlimerJS

    Join the chat at

    Build Status

    So now that you got your tests Mocha running on a simple flat HTML file, now how do you run them in your CI environment? Karma? what is this karma.conf.js file I have to write? and some background runner task? how do I grep over just a few tests? wait I need a to also install a launcher for phantomjs or slimerjs too? bleck.

    Rather than force you to redo your test harness and local development testing, simply run phantomjs mocha-phantomjs-core.js spec tests/mytests.html and be done with it. mocha-phantomjs-core builds on top of what you already have, with no high barrier to entry like Karma.

    New in 2.0 is SlimerJS support! There are some bugs still to be worked out, but now you can run your tests headless on the latest firefox version instead of an old QtWebKit!


    npm install mocha-phantomjs-core


    <phantomjs|slimerjs> mocha-phantomjs-core.js <TESTS> <REPORTER> <CONFIG as JSON>
    phantomjs ./node_modules/mocha-phantomjs-core/mocha-phantomjs-core.js tests.html
    phantomjs ./node_modules/mocha-phantomjs-core/mocha-phantomjs-core.js tests/runner.html xunit > results.xml
    /usr/local/bin/phantomjs /path/to/mocha-phantomjs-core.js tests.html spec "{\"useColors\":true}"

    Due to resource loading timing issues with external sources, you may need to call initMochaPhantomJS before calling any mocha setup functions like setup(), ui(), etc. mocha-phantomjs-core will notify you if you need this, and if so, add a check for it before your mocha setup code:

    if (typeof initMochaPhantomJS === 'function') {

    This can be avoided by removing unnessecary external resources like fonts, CSS, etc. from your tests, or simply having mocha.js as the first script loaded.


    It's best to always refer to the tests for full usage and examples.


    One of mocha's built in reporters, or a full path to a file for a 3rd party reporter (see below on how to write one).


    a string to pass to mocha.grep() to filter tests. also provide invert: true if you want to invert the grep and filter out tests.


    Boolean. Force or suppress color usage. Defaults to what your terminal supports.


    Boolean. Stop the test run at the first failure if true. Defaults to false.


    Boolean. Suppress the resource failure output that mocha-phantomjs-core will output by default.


    Time in milliseconds after the page loads that needs to be called. Defaults to 10 seconds.


    Sets mocha's root suite timeout. Defers to mocha's default if omitted.


    Sets the viewport size. Specify height and width, like below:


    If you need to pass additional settings to the phantomjs webpage, you can specify an object of settings here, including common ones like userAgent and loadImages.

    phantomjs mocha-phantomjs-core.js dot tests/mytests.html "{\"viewportSize\":{\"width\":720,\"height\":480}}"

    Previously mocha-phantomjs required you to look for mochaPhantomJS and then use That is no longer required. Call as you normally would.


    mocha-phantomjs-core supports creating screenshots from your test code. For example, you could write a function like below into your test code.

    function takeScreenshot() {
      if (window.callPhantom) {
        var date = new Date()
        var filename = "screenshots/" + date.getTime()
        console.log("Taking screenshot " + filename)
        callPhantom({'screenshot': filename})

    If you want to generate a screenshot for each test failure you could add the following into your test code.

      afterEach(function () {
        if (this.currentTest.state == 'failed') {

    Send event

    mocha-phantomjs-core supports sending events from your test code to allow for more ouside testing. For example, to trigger an external click event:

    if (window.callPhantom) {
        sendEvent: ['click', 10, 10] // array of arguments

    Changing viewportSize

    mocha-phantomjs-core now also supports changing of viewportSize (the simulated window size for the headless browser) - while running tests.

    if (window.callPhantom) {
        viewportSize : {
          width : 100,
          height : 100

    This comes on particlarly handy when testing for responsiveness.

    Environment variables

    mocha-phantomjs-core will expose environment variables at mocha.env

    Third Party Reporters

    Mocha has support for custom 3rd party reporters, and mocha-phantomjs does support 3rd party reporters, but keep in mind - the reporter does not run in Node.js, but in the browser, and node modules can't be required. You need to only use basic, vanilla JavaScript when using third party reporters. However, some things are available:

    • require: You can only require other reporters, like require('./base') to build off of the BaseReporter
    • exports, module: Export your reporter class as normal
    • process: use process.stdout.write preferrably to support the --file option over console.log (see #114)

    Also, no compilers are supported currently, so please provide plain ECMAScript 5 for your reporters.


    npm install
    npm test

    Travis CI does a matrix build against phantomjs 1.9.7 and 2.0.0, currently. See .travis.yml for the latest.

    To debug an individual test, since they are just process forks, you may want to run them directly, like

    phantomjs mocha-phantomjs-core.js test/timeout.html spec "{\"timeout\":500}"


    Released under the MIT license. Copyright (c) 2015 Ken Collins and Nathan Black.


    npm i mocha-phantomjs-core

    Downloadsweekly downloads








    last publish


    • avatar