grunt-buster

Grunt task for running Buster.JS tests in Node.js or headless in PhantomJS

Getting started

This plugin requires Grunt ~0.4.0

If you haven't used Grunt before, be sure to check out the Getting started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-buster

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-buster');

Then, you must install Buster.JS:

npm install buster

Browser tests

If you want to run tests for the browser environment, you also need to install PhantomJS:

npm install phantomjs

The "buster" task

Overview

In your project's Gruntfile, add a section named buster to the data object passed into grunt.initConfig(). You then need to define at least one target for grunt buster to have any effect.

Example of a minimal working configuration:

buster: {
  foo: {}
}

The buster object can have an arbitrary number of targets, like foo in the above example. If you run grunt buster, all targets are executed. If you run grunt buster:foo, only the foo target is executed.

Options

No options are needed to get started, as grunt-buster will use default values if none is specified.

test

An object with options passed as command line arguments to buster test. For available options for buster test run:

buster test --help

server

An object with options passed as command line arguments to buster server. For available options for buster server run:

buster server --help

options.growl

Growl support is optional. If you would like to use it follow the instructions on how to install node-growl, then enable Growl notifications in the buster task in your Gruntfile.

Example:

buster: {
  options: {
    growl: true
  }
}

You should now get notifications whenever your test suite passes or fails.

Examples

buster: {
  foo: {
    test: {
      config: 'path/to/my/buster.js'
    },
    server: {
      port: 1111
    }
  },
  bar: {
    options: {
      growl: false
    }
  },
  options: {
    growl: true
  }
}

The above config will for the foo target run buster test with the argument --config path/to/my/buster.js, and run buster server with the argument --port 1111, with Growl notifications when the tests complete.

For the bar target, default configuration will be used, and Growl notifications will be turned off.

Running servers, tests and PhantomJS separately

It is possible to start one or more Buster.JS servers, PhantomJS instances or individual Buster.JS test runs by passing Grunt arguments when invoking tasks.

Grunt allows for command line arguments to be passed to multitasks, like so: grunt task:subtask:argument1:argument2. To pass arguments to, and execute all subtasks of a multitask, skip the subtask name: grunt task::argument. In grunt-buster, we use that to gain more granular control over which Buster.JS components are executed, as described below in this section.

Start all configured Buster.JS servers

grunt buster::server

This starts all configured Buster.JS servers, without starting a Phantom.JS instance nor running any tests.

Note: Grunt will not block the server and phantomjs tasks by default. They are intended to be used in combination with blocking tasks like grunt-contrib-watch. If you do not want to run either of the two in combination with a watch command, you can supply the block argument:

grunt buster::server:block

Start instances of PhantomJS

grunt buster::phantomjs

This allows you to capture browsers manually before executing the tests separately (see below).

Run tests

Execute the tests only and not spawn neither a Buster.JS server nor PhantomJS, as they are assumed to be started manually in some other way.

grunt buster::test

Development

If you wish to contribute, please ensure a green test suite.

Install development dependencies:

npm install

Running the test suite:

npm test

Starting a watch loop listening to file changes and running the test suite:

npm start

Making releases

• Update the Release history
• Update the package.json version number
• Tag the release commit with correct version number
• Push new release to npm: npm publish

Release history

v0.4.2 (2016-Jan-06)

• Using cross-spawn-async so that a correct executable is resolved on Windows

v0.4.1 (2015-Nov-10)

• Cleaning up redundant project settings

v0.4.0 (2015-Nov-10)

• Try to use an executable in the path, if an npm package for it not found
• BREAKING: added an engine requirement (node LTS) in package.json

v0.3.2 (2014-Sep-24)

• Use resolve-bin to find buster and phantomjs executables
• Add buster as a peer dependency
• Clean escape characters in Growl

v0.3.1 (2013-Nov-07)

• Fix issue where failing tests make grunt-buster hang

v0.3.0 (2013-Oct-31)

• Fix #9 - Allow for more granular control over buster-server, PhantomJS and buster-test execution
• Only log buster-server output if Grunt is run with verbose

v0.2.1 (2013-May-13)

• Fix broken URLs in package description

v0.2.0 (2013-May-13)

• Updated project URLs after move to busterjs organization on GitHub
• Require Node.js >= 0.8.0
• Fix path.existsSync deprecation warning
• Declare a peer dependency on Grunt ~0.4.0
• Made Growl notifications optional. You must now install the growl package from npm and set options.growl to true to get notifications.
• Added support for Grunt multi-tasks. You must now define at least one target for the buster task to have any work to do. See the above docs for a minimal config example. (Thanks to Richard Nespithal)
• Add --server option to buster-test (Thanks to Andreas Köberle)
• Add support for locally installed versions of Buster.JS and PhantomJS (Thanks to Stein Martin Hustad)

v0.1.2 (2012-Oct-03)

• Looks for buster.js in test/ and spec/ in addition to the root folder
• Fixed corrupt error.png and ok.png (Thanks to Paweł Maciejewski)
• Removed console non-printable characters from growl text message (Thanks to Paweł Maciejewski)

v0.1.1 (2012-Jul-29)

• Ensure that tests is not run until PhantomJS finished starting (thanks to Harrison)

v0.1.0 (2012-Jul-24)

• Initial release