##grunt-vows-runner

A test-runner for vows using grunt.

###Philosophy

File and directory matching, file watching, coverage reporting, etc. should be supplied by third-party tools where possible. Grunt is a great source of such third-party-tools. These are much more likely to continue development than the equivalent tools built into vows, since they are used by many other packages as well.

###Additions

With grunt-vows-runner you can

• Use grunt tasks and templates.
• Run suites in the same target concurrently.
• Set options at the target level.
• Set the isolate option at the suite and target level, and run isolated and non-isolated suites concurrently.
• Disable groups of tests at the target level

###Differences from the vows command-line runner

• Uses grunt to specify which files to run
• Uses grunt's watch task instead of vows' built-in watch implementation
• No shuffle option (if you want this, let me know--it is easy to implement)
• No built-in js-coverage support
• I highly recommend istanbul, which does not need the cooperation of the test-runner (simply istanbul cover bin/vows will work ); and it is written in javascript, not java

###Installation

1. Change directories to the root directory of your project
2. npm install grunt-vows-runner

###Usage

Add the following line to your Gruntfile.js

grunt.loadNpmTasks('grunt-vows-runner');

The vows task is now available; for example

grunt vows

###Configuration

Configuration is placed in the grunt.initConfig section of your Gruntfile.js file in the vows object.

vows is a multitask.

Each target references one or more source files containing suites and may contain options which will be applied to all of those suites.

An example vows configuration with two targets:

...
vows : {
  all : {
    src : "<%= allTests %>",
    options : {
      reporter : "spec"
    }
  },
  allXunit : {
    src : "<%= allTests %>",
    dest : "testResults.xml"
    options : {
      reporter : "xunit"
    }
  }
},
allTests : "tests/*"
...

The example above uses the compact format for specifying files as well as templates.

One destination file (dest) can be specified per target. It will contain the output of all the suites in the target. If no destination file is specified, the output will go to the console.

Paths for both source and destination files are relative to the directory that the Gruntfile.js is in.

Results are summed by target. Grunt-vows-runner doesn't combine the results of multiple targets.

Suites within a target are run concurrently; faster suites will finish first. Targets in grunt are always run sequentially.

####Options

Options can be placed at the task (vows), target, or suite level.

Here is an example of each:

Gruntfile.js (task- and target-level options)

...
vows : {
  options : {
    reporter : "spec"
  },
  most : {
    src : ["test/*", "!test/chattyTests.js"]
  },
  chatty : {
    src : "test/chattyTests.js",
    options : {
      reporter : "silent"
    }
  }
}
...

test/errorTests.js (suite-level options)

...
vows.describe('Error Handling').addBatch({
...
}).export(module, {error : false});
...

The following options are available:

• error
• Whether or not vows should handle errors in topics for you. Set error : false if you want to handle your own errors. The first argument to your vows will be reserved for errors.
• reporter
• silent, spec, json, tap, xunit, dot-matrix. (Look in vows/lib/vows/reporters for a complete list.)
• matcher
• a javascript RegExp object; only run tests whose titles match this object.
• isolate
• Run each suite in its own process. This is useful if the system-under-test uses the node process object internally.
• disabled
• Temporarily disable tests for a target.

###Command-Line Options

grunt-vows-runner incorporates the following grunt command-line options, if present:

• --no-color
• --verbose

###Alternatives

If you would like a grunt plugin that simply forwards options to the existing vows command-line runner, see grunt-vows.