Write CasperJS tests using Mocha

npm install mocha-casperjs
46 downloads in the last day
320 downloads in the last week
1 779 downloads in the last month

CasperJS automation via Mocha Build Status

Combine the power of casperjs' automation with Mocha's robust testing framework features


  • automatically load Casper, Mocha, and optionally chai and casper-chai
  • automatically run your Casper steps after each test
  • use any Mocha reporter that can run in the phantomjs or slimerjs environment

For example, let's rewrite Casper's google testing example

describe('Google searching', function() {
  before(function() {

  it('should retrieve 10 or more results', function() {
    casper.then(function() {
      this.fill('form[action="/search"]', {
        q: 'casperjs'
      }, true)

    casper.waitForUrl(/q=casperjs/, function() {

How to use

mocha-casperjs is still in active development against the latest casperjs and since a couple of issues have arose that required patches, please use the latest version of casperjs, if not at least >= 1.1.0-beta3.

npm install -g mocha-casperjs

Like Mocha, if you place your tests in the test or tests directory, it will find them and run them. You can also specify tests to run individually instead.

Additional Conveniences

If chai is discovered (it must be installed adjacent to mocha-casperjs), it will automatically use the should style as well as expose expect globally.

If casper-chai is discovered, it will be used with chai.

The selectXPath casper helper method is exposed globally as xpath.

Command Line Options

In addition to specifying options on the command line, you can add them to a mocha-casperjs.opts like mocha.opts, except it looks for this file in the current directory.


These are all Mocha command line options that mocha-casperjs supports. Currently the default timeout is 30 seconds, not two, as writing end to end tests takes more time.

Note the CasperJS cli parser does not support shorthands or spaces between parameters. So rather than -g foo and --grep foo, use --grep=foo

--casper-timeout=<timeout in ms>

Set Casper's timeout. Defaults to 5 seconds. You will want this less than Mocha's.


Pipe reporter output to the specified file instead of standard out. Use this if you have to filter out console messages from reporter output, like for json, xunit, etc. type of reporters


Load Mocha from the specified path, otherwise look for it adjacent to mocha-casperjs


Load Chai from the specified path, otherwise look for it adjacent to mocha-casperjs


Load casper-chai from the specified path, otherwise look for it adjacent to mocha-casperjs

CasperJS options

Also, you can add CasperJS options to mocha-casperjs.opts. Below are the supported options:



Sets the User-Agent string (like Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)) to send through headers when performing requests.

--viewport-width=<pixels> --viewport-height=<pixels>

Sets the PhantomJS viewport to custom size. Useful for testing media queries and capturing screenshots:

casper.on('load.finished', function (resource) {
  this.captureSelector(screenshots_path + 'body.png', 'body');

Custom 3rd party Reporters

You can provide your own reporter via the --reporter flag. mocha-phantomjs will try to require the module and load it. Some things to take note of:

  • Both node modules and script files can be required, so for relative paths to scripts, make sure they start with '.'. E.g. use --reporter=./foo to load foo.js that is in the current directory. CoffeeScript files can be directly required too, as phantomjs has coffeescript built in.
  • PhantomJS is not node.js. You won't have access to standard node modules like url, http, etc. Refer to PhantomJS's built in modules. However, mocha-casperjs does provide a very minimalistic process shim to PhantomJS's system module.
  • If you want access to built-in Mocha reporters, they are available on Mocha.reporters. For example, Mocha.reporters.Base.

How it works

mocha-casperjs is a big conglomeration of various ideas and approaches.

  • It patches Mocha's Runnable to have every runabble be async and flush the casper tests - an approach taken from mocha-as-promised.
  • It replaces Mocha.process.stdout with phantom's, including formatting - an approach taken from mocha-phantomjs
  • It attaches to Casper error events and fails the test with the last error that occoured.
npm loves you