grunt-pretest

Grunt plugin to run task only when specified tests are passed.

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-pretest --save-dev

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

grunt.loadNpmTasks('grunt-pretest');

The "pretest" task

Overview

The pretest task is multi task.

In your project's Gruntfile, add a section named pretest to the data object passed into grunt.initConfig().

grunt.initConfig({
  pretest: {
    options: {
      // Task-specific options go here.
    },
    your_target: {
      options: {
        // Target-specific options go here.
      }
    },
  },
});

Options

options.test

Type: any
Default value: true

Specifies test or array of tests that should be passed to run a task. Any test that is not a function is converted to boolean value. If test is a function, its result is used as test value. The following parameters are passed into the function:

• reference to the data object (see below)
• reference to grunt object

If test function returns a non-empty string, a non-empty array or a function, the returned value will be used as task that should be run instead of task option.

The task described in task option or returned from a test function will be run only if:

• results of all tests have true value when testConnect option is and
• result of any test has true value when testConnect option is or

options.testConnect

Type: String
Default value: and

A boolean connector that should be used when array of tests is specified in test option. Valid values are the following: and, or (case-insensitive). Any other value is treated as and.

options.task

Type: String | Array of String | Function

Describes task(s) that should be run when test is passed. This option can be omitted if test function returns the necessary task(s). Each string should specify task in usual format (e.g. concat:foo, bar:testing:123). If a function is set as task, the following parameters will be passed into the function:

• reference to the data object (see below)
• reference to grunt object

If task function returns a non-empty string or a non-empty array, the returned value will be used as argument for grunt.task.run (i.e. defines task(s) that should be run after the processed pretest task).

Data object

Data object that is passed into test and task function has the following fields:

• task - value of task option
• pretest - reference to the object that represents the processed pretest task (see Inside Tasks for available properties)
• options - options of the processed pretest task
• source - a source item that is being processed

Usage examples

In this example, the concat task will be run only if directory specified by configDir configuration parameter exists.

grunt.initConfig({
    pretest: {
        configDir: {
            options: {
                test: function(data, grunt) {
                    return grunt.file.isDir(grunt.config.get("configDir"));
                },
                task: 'concat:config_files'
            }
        }
    }
});

In the following example, the test function returns a task that should be run depending on value of target option.

grunt.initConfig({
    pretest: {
        configDir: {
            options: {
                test: function(data, grunt) {
                    var target = grunt.option("target");
                    return target
                            ? "prepare:" + (target === "prod" ? "product" : "dev")
                            : false;
                }
            }
        }
    }
});

It is possible to specify sources for which tests and tasks should be run.

grunt.initConfig({
    pretest: {
        sourceList: {
            src: ["a.json", "b.xml", "c.data"],
            options: {
                test: function(data, grunt) {
                    var runTask = true;
                    try {
                        fs.statSync(data.source);
                    }
                    catch (e) {
                        runTask = false;
                    }
                    return runTask;
                },
                task: function(data, grunt) {
                    return "some-task:" + data.source;
                }
            }
        }
    }
});

See Gruntfile.js for more examples.

Related projects

• grunt-init-pack
• grunt-uniator

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

• 1.0.0 / 2016-03-18

  • Change parameters for test and task functions.
  • Add ability to specify sources for which tests and tasks should be run (resolve #2).

• 0.2.0 / 2016-03-07

  • Add support for Grunt 1.0.

• 0.1.0 / 2016-02-03

  • task option can be omitted if test function returns task that should be run.
  • Task function can return task that should be run after the processed pretest task.