grunt-run-task

Run Grunt tasks in you tests, so you can test them.

So you want to test your Grunt tasks, eh? And you don't want to litter your project’s Gruntfile with tasks that are needed “just for the tests”? And you want your tests to be self-contained? Then this module is for you!

Whatsitdo?

This package gives you the tools to run Grunt tasks inside your tests and clean up afterwards. You can use your test tool’s setup and tear down methods to run the Grunt task you want to test with arbitrary configuration.

If you’re using BDD it could look like this:

var assert = require('assert');
var grunt = require('grunt');
var runTask = require('grunt-run-task');

describe('my awesome Grunt task', function () {
  runTask.loadTasks('tasks');

  describe('when using the default options', function () {
    var task = runTask.task('awesome_task', {
      options: {},
      src: [ 'test/fixtures/src.js' ],
      dest: 'tmp/src.out.js'
    });

    beforeEach(task.run());
    afterEach(task.clean());

    it('does awesome stuff', function() {
      assert(grunt.file.exists(task.files[0].dest));
    });
  });
});

Installation

This module is tested with Grunt 0.4.x and Node.js 0.10.x, 0.11.x and 0.12.x. Use npm to install it:

npm install --save-dev grunt-run-task

API

runTask(name, config, done)

Run the given task immediately with the given config. Call the callback, once the task has finished. Returns the created Task instance.

Options

• name String The name of the task to run. This may include colon-separated arguments to pass to the task, or, in the case of multi-tasks, the name of the target to run.
• config Object The configuration to use for the task.

Example

Run the jshint task.

runTask.loadNpmTasks('grunt-contrib-jshint');
runTask('jshint:default', {
  // JSHint is a multi-task, setup the "default" target
  default: {
    files: [ '**/*.js' ]
  }
}, function (err, task) {
  if (err) {
    // The task did encounter an error
  }
});

runTask.task(name, [config])

Return a new Task object that can be used to run the given task.

Options

• name String The name of the task to run. This may include colon-separated arguments to pass to the task, or, in the case of multi-tasks, the name of the target to run.
• config Object The configuration to use for the task.

Example

Run the uglify task, and cleanup created files afterwards.

runTask.loadNpmTasks('grunt-contrib-uglify');
var task = runTask.task('uglify', {
  default: {
    files: {
      'build/app.js': [ '**/*.js' ]
    }
  }
});

task.run('default', function (err) {
  task.clean(function (err) {
    // Done
  });
});

runTask.grunt

The (internal) Grunt instance used for running your tasks. You can use this if you want to test if your task called the Grunt API or modified some configuration entries. This will not be the same instance you would obtain with require('grunt').

runTask.initConfig(configObject)

Wrapper for the grunt.initConfig method.

runTask.registerTask(taskName, ...)

Wrapper for the grunt.registerTask method.

runTask.registerMultiTask(taskName, ...)

Wrapper for the grunt.registerMultiTask method.

runTask.registerInitTask(taskName, ...)

Wrapper for the grunt.registerInitTask method.

runTask.renameTask(oldTaskName, newTaskName)

Wrapper for the grunt.renameTask method.

runTask.loadTasks(tasksPath)

Wrapper for the grunt.loadTasks method.

runTask.loadNpmTasks(pluginName)

Wrapper for the grunt.loadTasks method.

runTask.option(pluginName)

Wrapper for the grunt.option method.

Class: Task

The task class implements the EventEmitter2 API. Any events that are emitted by Grunt while your task runs are forwarded to the task class.

Properties

• name String The name of the task.
• multi Boolean Whether this is a multi-task.
• init Boolean Whether this is a init-task
• target String If the task is a multi-task, this is the target name it was created with.
• args Array Any arguments that were passed when creating the task.
• files Array The destination files that this task (might have) created.

task.run([arguments...], [done])

Run the task with the given arguments. If the last argument is a function, run the task immediately and call the function once the task finished. Otherwise, return a function expecting a single parameter, the callback, that actually runs the task.

Options

• arguments String Any arguments to pass to the task, similar to what you would specify on the command line, by appending colon-separated options to the task you wish to run.
• done Function A callback to be called once the task has finished.

task.fail([arguments...], [done])

Run the task with the given arguments, but expect it to fail. If the last argument is a function, run the task immediately and call the function once the task finished. Otherwise, return a function expecting a single parameter, the callback, that actually runs the task.

Options

• arguments String Any arguments to pass to the task, similar to what you would specify on the command line, by appending colon-separated options to the task you wish to run.
• done Function A callback to be called once the task has finished.

task.clean([done])

Clean up the task's dest files.

Options

• done Function A callback to be called once all files have been removed.

License

Copyright © 2014 Jonas Pommerening

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.