TJ Holowaychuk

Mocha 1.4.0

This is another relatively small release but still has some goodies!

.only()

By appending .only() Mocha will generate an internal .grep() call for you. This is very useful if you have a regression and a test-case fails. Instead of moving the test-case and associated code out in order to debug you can simply invoke it.only(title, callback) (for the BDD UI) and Mocha will ignore all others. Here’s an example that will execute “bar” and its test-cases only:

describe('foo', function(){
  it('should foo', function(){

  })
})

describe.only('bar', function(){
  it('should bar', function(){

  })
})

.skip()

By appending .skip() you can tell Mocha to ignore these tests. This was previously called xdescribe(), xit() etc to match other frameworks (Jasmine I believe?) but we decided to go with .skip() which is more readable. The jasmine-style functions will remain for now but they will be removed in the future. This is effectively the same as commenting out cases, however they remain in a pending state so that you do not forget to re-enable them.

describe('foo', function(){
  it.skip('should foo', function(){

  })
})

describe('bar', function(){
  it('should bar', function(){

  })
})

Filtering HTML passes and failures

The “passes” and “failures” labels are now clickable links that will filter respectively.

Retina

The canvas progress reporter is now retina-enabled via the autoscale-canvas component. No more ugly pixelated progress!

Changelog

Here’s the full changelog between 1.3 and 1.4:

add mkdir -p to mocha init. Closes #539
add .only(). Closes #524
add .skip(). Closes #524
add passes/failures toggling to HTML reporter
add pending state to xit() and xdescribe() [Brian Moore]
add the @charset “UTF-8”; to fix #522 with FireFox. [Jonathan Creamer]
add border-bottom to #stats links
add check for runnable in Runner#uncaught(). Closes #494
add 0.4 and 0.6 back to travis.yml
add -E, --growl-errors to growl on failures only
add prefixes to debug() names. Closes #497
add Mocha#invert() to js api
change str.trim() to use utils.trim(). Closes #533
change dot reporter to use sexy unicode dots
fix HTML progress indicator retina display
fix url-encoding of click-to-grep HTML functionality
fix exports double-execution regression. Closes #531
fix error when clicking pending test in HTML reporter
fix make tm

Mocha test coverage

The latest release of Mocha adds two new reporters, now totaling 13 packaged with the library. The two new ones are “json-cov” and “html-cov”, the latter inherits from the former in order to produce a single-page test coverage report.

If you’re curious what a live example looks like, check out this page.

Setup

With Node’s require.paths array out of the picture there’s a bit of boiler-plate involved in setting up test coverage for your project, but it’s pretty minimal. First you’ll want to install the jscoverage executable, this program parses your source code and spits out an instrumented version, effectively a bunch of lines that look like this:

  $_jscoverage[filename][line]++;

This enables libraries like Mocha to execute the code as they normally would, however we can then extract this coverage information and generate fancy reports. jscoverage takes the input directory, and an output directory, I usually calls this “lib-cov”:

 $ jscoverage lib lib-cov

Typically when testing your library you’ll use relative require() calls that look like this: var express = require('../'), and the library entry point is ./index.js. Normally this file might look something like below, or you may not have an ./index.js file at all.

  module.exports = require('./lib/express');

By using ./index.js we can then alter this statement to conditionally export the instrumented version when the EXPRESS_COV environment variable is present:

 module.exports = process.env.EXPRESS_COV
   ? require('./lib-cov/express')
   : require('./lib/express');

Then all you need to do is invoke mocha with --reporter html-cov and redirect the stdout to a file such as coverage.html. Line 25 the test-cov target of the Express Makefile illustrates how I typically handle this but depending on your setup it may vary.

That’s it! remember to add “coverage.html” to your .npmignore and .gitignore files ;)

Introducing Tobi

A few days ago we released another small test related project named Tobi for nodejs. Tobi is similar to Ruby tools such as Capybara or Webrat in fulfilling the need for headless acceptance testing. Tobi utilizes jQuery and node’s jsdom to give you an expressive foundation for testing your application in a familiar way.

Motivation

For those of you who follow our work at LearnBoost we have a Selenium / Sauce Labs based acceptance testing tool named Soda, which is fantastic to work with and helps us test our massive app before pushing to production. However, large soda suites typically take several minutes to run, even when running parallel in our targeted Sauce Lab browers. This is of course a very important task to perform, but is far to slow for constant execution during development, so we created Tobi.

Examples

Tobi is test-framework agnostic, meaning it will generally work with any test framework out there for node. Below is an example which runs stand-alone.

Paired with the should.js library expressive assertions can be made on both the response as well as the DOM, for example:

res.should.have.header('Content-Type', 'text/html');
$('ul.messages').should.have.one('li', 'Successfully authenticated');

Locators

Tobi uses “locators” which are similar to those found with Selenium, to essentially expand on css selectors making your code that much more readable. For example rather than selecting a form input via css selector such as

$('[name=username]').val('tj');

we can use the browser.* methods to help us

browser.type('username', 'tj');

Zombies?

Oddly enough a similar project yet-again sprung up a few days before we open sourced ours, named zombie.js. It seems to have similar intentions, leaning more towards a “real” browser implementation. Although interesting acceptance tests should be run in real browsers, which is why I like to consider Tobi more of an integration testing framework, or a pseudo-acceptance sanity check for developers, soda still takes care of deployment.

So, check them both out, see which works for you, but dont forget to apply functional tests, I highly recommend giving Sauce Labs a look. There is no replacement for real browsers! get on it!