node package manager
Easy sharing. Manage teams and permissions with one click. Create a free org »



Run your front-end mocha tests where they belong; in the browser! Much like [jasmine-gem][jasmine-gem], mocha-server serves up your Mocha suite in a web page so you don't have to spend time writing HTML test runners and can focus on the code itself. You can even run them them headlessly with mocha-phamtomjs so they can be part of your build process!


npm install mocha-server


In its simplest form, you run mocha-server from the command-line:

$ mocha-server

This will launch a server that can be accessed at http://localhost:8888 ; open it with a browser to run the mounted tests.

The following flags can also be used:

  Usage: mocha-server [options]
    --help               output usage information
    -V, --version            output the version number
    -r, --require <name>     require the given module
    -R, --reporter <name>    specify the reporter to use
    -u, --ui <name>          specify user-interface (bdd|tdd|exports)
    -b, --bail               bail after first test failure
    -h, --headless           run headless with phantomjs
    -c, --compilers <name>   pass in [ext]:[path to compiler]
    --agent <userAgent>      specify the user agent to use
    --cookie <name>=<value>  specify cookie
    --header <name>=<value>  specify custom header
    --setting <key>=<value>  specify specific phantom settings
    --view <width>x<height>  specify phantom viewport size
    --ignore-leaks           ignore global variable leaks
    --recursive              include sub directories

By default, tests are pulled in from the test directory.

Load Order

As dependencies can be very important in running Javascripts code and tests, mocha-server provides two mechanisms for ensuring the load order.


First, the --require or -r flags can be used repeatedly to identify files that should be loaded first. For example:

$ mocha-server -r ./test/test-helper.js ./test/my-tests

Will load ./test/test-helper.js before it loads any of the tests found uncer ./test/my-tests.

Sprocket-style require

Alternatively, you can use sprockets style require directives to indicate depdencies. This functionality is supplied by snockets.

Adding Additional Javascript Compilers

Out of the box, mocha-server supports Javascript and coffeescript files through snockets. You can pass in additional compilers through the --compiler</code flag as follows:

$ mocha-server --compiler jade:./test/compilers/jade.js

Will compile all files with the .jade extension using the compiler defined in ./test/compilers/jade.js.

A compiler is made up of a match property that is regular-expression that indicates the files type returned and a compileSync function that will return the source generated.

Look under the spec/support for an example compiler.


Much like mocha will attempt to load ./test/mocha.opts, mocha-server will attempt to load ./test/mocha-server.opts, concatenating the arguments to those passed on the command line. For example, suppose you have the following:

--require ./test/support

It will ensure the contents of test/support is loaded first, that the tests are run headlessly, and that all the tests in test/assets are run.

Running Headlessly

mocha-server uses mocha-phantomjs to run headlessly. You need to install PhantomJS v.1.7.0 or greater and then you can enter:

$ mocha-server --headless


$ mocha-server -h

This launches the server, then runs mocha-phantomjs against it. Several command-line arguments are passed through to it.


The files under test folder provide examples of writing tests for the system. You can run them by:

$ mocha-server


Fork the repo, make a branch, add tests, make your changes, and submit a pull-request!


You can test mocha-server by cloning this repository and running:

$ cake test

This will run the tests under the spec folder.