Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Stub a browser environment in node.js and headlessly test your client-side code.
JavaScript HTML
branch: master

Merge pull request #20 from alechenninger/patch-1

Remove unused done callback from example
latest commit e106f92bc8
@craigspaeth craigspaeth authored

README.md

benv

Stub a browser environment and test your client-side code in node.js.

Example

Example using mocha and should.

Given some client-side code

./client/app.js

$(function() {
  $('body').html('Wat!?');
});

Setup, declare global dependencies, and test in node.js.

./test/client/app.js

var benv = require('benv');

beforeEach(function(done) {
  benv.setup(function() {
    benv.expose({
      $: benv.require('../client/vendor/zepto.js', 'Zepto')
    });
    done();
  });
});

afterEach(function() {
  benv.teardown();
});

describe('app.js', function() {
  it('renders Wat', function() {
    require('../client/app.js');
    $('body').html().should.include('Wat!?');
  });
});

Why

Unit testing client side code in a browser is slow and hard to setup with CI. Wouldn't it be nice if we could just run it along-side our server-side tests? Benv is a library of test helpers that make it easy to require your client-side code in node.js and test it like any other node module.

See this blog post for details & inspiration.

API

benv.setup(callback)

Exposes a stubbed browser API into the node.js global namespace so the current process can act like a browser environment.

benv.expose(globals)

Pass in a hash of common global client-side dependencies. For instance you may have a Backbone app that has a global App namespace and uses jQuery. This should be run after benv.setup b/c a lot of libraries assume the window object is already global.

benv.expose({
  _: require('underscore'),
  jQuery: require('jquery'),
  $: require('jquery'),
  Backbone: require('backbone'),
  App: {}
})

benv.teardown(clearDOM = true)

Clean up the globals exposed by setup and expose so other tests can run without being harmed.

Use benv.teardown(false) to keep around references to window, document, and other DOM globals. Useful for libraries that cache references to DOM globals and don't work so nicely when trying to clear globals and re-require these libs.

benv.require(filename, globalVarName)

For non-commonjs wrapped libraries, benv.require will export the global variable that is generally attached to window. For instance zepto doesn't adopt any module pattern but it does create a global Zepto variable.

e.g.

var $ = benv.require('./client/vendor/zepto.js', 'Zepto');

benv.render(filename, data, callback)

Renders the html in a body tag of a template. Pass in the template's filename along with any data passed into the template. Benv is backed by jsdom and benv.render will remove any script tags so as to not accidentally run external javascript.

e.g.

benv.render('./views/artwork.jade', {
  artwork: new Artwork({ title: 'Andy Warhol, Flowers' })
}, function() {
  $('body').html().should.include('Andy Warhol, Flowers');
});

Currently only supports .jade templates, but please contribute others :)

benv.requireWithJadeify(filename, varNames)

For those using jadeify when requiring client-side code that uses jadeify it will throw an error because require('template.jade') isn't valid node code.

If you defer your jade requires to run time e.g. var artworkTemplate = function() { return require('foo.jade').apply(this, arguments); } and use benv.requireWithJadeify('../client/artwork.js', ['artworkTemplate']) you can avoid this error and test the jadeified templates in node again.

Contributing

Please fork the project and submit a pull request with tests. Install node modules npm install and run tests with make test.

License

MIT

Something went wrong with that request. Please try again.