PhantomJS Runners for Mocha

Mocha is a feature-rich JavaScript test framework running on node and the browser. Along with the Chai assertion library they make an impressive combo. PhantomJS is a headless WebKit with a JavaScript/CoffeeScript API. It has fast and native support for various web standards like DOM handling, CSS selectors, JSON, Canvas, and SVG.

The mocha-phantomjs project provides a mocha-phantomjs.coffee script file and extensions to drive PhantomJS while testing your HTML pages with Mocha from the console.

Key Features

Standard Out

Finally, process.stdout.write, done right. Mocha is primarily written for node, hence it relies on writing to standard out without trailing newline characters. This behavior is critical for reporters like the dot reporter. We make up for PhantomJS's lack of stream support by both customizing console.log and creating a process.stdout.write function to the current PhantomJS process. This technique combined with a handful of fancy ANSI cursor movement codes allows PhantomJS to support Mocha's diverse reporter options.

Exit Codes

Proper exit status codes from PhantomJS using Mocha's failures count. So in standard UNIX fashion, a 0 code means success. This means you can use mocha-phantomjs on your CI server of choice.

Mixed Mode Runs

You can use your existing Mocha HTML file reporters side by side with mocha-phantomjs. This gives you the option to run your tests both in a browser or with PhantomJS. Since mocha-phantomjs needs to control when the run() command is sent to the mocha object, we accomplish this by setting the mochaPhantomJS on the window object to true. Below, in the usage section, is an example of a HTML structure that can be used both by opening the file in your browser or choice or using mocha-phantomjs.

Usage

$ phantomjs mocha-phantomjs.coffee URL [REPORTER]

The mocha-phantomjs.coffee script needs to be accompanied by the mocha-phantomjs directory included in the Github's lib project directory. This directory contains core extensions the script needs to inject into the loaded URL. If the mocha-phantomjs.coffee file resides directly beside this directory, everything should just work.

Your HTML file structure should look something like this. The reporter set below to html is only needed for viewing the HTML page in your browser. The mocha-phantomjs.coffee script overrides that reporter value. The conditional run at the bottom allows the mixed mode feature described above.

<html>
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="mocha.css" />
  </head>
  <body>
    <div id="mocha"></div>
    <script src="mocha.js"></script>
    <script src="chai.js"></script>
    <script>
      mocha.ui('bdd'); 
      mocha.reporter('html');
      expect = chai.expect;
    </script>
    <script src="test/mycode.js"></script>
    <script>
      if (!window.mochaPhantomJS) { mocha.run(); }
    </script>
  </body>
</html>

Supported Reporters

Mocha-phantomjs does not scrap the web page under test! No other PhantomJS driver stacks up to our runner support. Some have used a debounce method to keep duplicate messages in the spec reporter from showing up twice. Loosing one of Mocha's console reporters neatest features, initial test start feedback. The animation below is an example of how our runner script fully compiles with expected Mocha behavior.

The following is a list of supported runners. If you do not see one that you really want, fork the repo and try to write the customizeProcessStdout() and customizeConsole() functions to support that runner. If you need help, create a github issue and let me know.

Spec Reporter (default)

The default reporter. You can force it using spec for the reporter argument.

Dot Matrix Reporter

Use dot for the reporter argument.

The PhantomJS process has no way of knowing anything about your console window's width. So we default the width to 75 columns. But if you pass down the COLUMNS environment variable, it will pick that up and adjust to your current terminal width. For example, using the $COLUMNS variable like so.

env COLUMNS=$COLUMNS phantomjs mocha-phantomjs.coffee URL dot

TAP Reporter

Use tap for the reporter argument.

Min Reporter

Use min for the reporter argument.

List Reporter

Use list for the reporter argument.

Doc Reporter

Use doc for the reporter argument.

TeamCity Reporter

Use teamcity for the reporter argument.

$ phantomjs lib/mocha-phantomjs.coffee test/passing.html teamcity
##teamcity[testSuiteStarted name='mocha.suite']
##teamcity[testStarted name='Tests Passing passes 1']
##teamcity[testFinished name='Tests Passing passes 1' duration='0']
##teamcity[testStarted name='Tests Passing passes 2']
##teamcity[testFinished name='Tests Passing passes 2' duration='0']
##teamcity[testStarted name='Tests Passing passes 3']
##teamcity[testFinished name='Tests Passing passes 3' duration='0']
##teamcity[testIgnored name='Tests Passing skips 1' message='pending']
##teamcity[testFinished name='Tests Passing skips 1' duration='undefined']
##teamcity[testIgnored name='Tests Passing skips 2' message='pending']
##teamcity[testFinished name='Tests Passing skips 2' duration='undefined']
##teamcity[testIgnored name='Tests Passing skips 3' message='pending']
##teamcity[testFinished name='Tests Passing skips 3' duration='undefined']
##teamcity[testSuiteFinished name='mocha.suite' duration='133']

Testing

Simple! Just clone the repo, then run npm install and the various node development dependencies will install to the node_modules directory of the project. If you have not done so, it is typically a good idea to add /node_modules/.bin to your $PATH so these modules bins are used. Now run cake test to start off the test suite.

We also use Travis CI to run our tests too. The current build status:

TODO

Create a mocha-phantomjs bin file for use in Node.js and publish a NPM.

Alternatives

OpenPhantomScripts - https://github.com/mark-rushakoff/OpenPhantomScripts
Front Tests - https://github.com/Backbonist/front-tests

andersjanmyr / mocha-phantomjs Goto Github PK

mocha-phantomjs's Introduction