grunt-amd-require-tests

Finds test files in AMD projects and "require"s them for your test runner

The purpose of this grunt plugin is to dynamically find JavaScript test files as they are created, and update a file that "require"s them for your AMD project.

In your test runner, you will "require" the file generated by this plugin, which will in turn require all the actual test files.

Recommended usage is to include this task in your grunt-contrib-watch tasks so newly added test files will automatically be run.

This plugin was inspired by the author's frustration at having to manually update the test runner every time a spec file was added to the project, while working on a project using require.js and Mocha.

Getting Started

This plugin requires Grunt ~0.4.2

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-amd-require-tests --save-dev

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

grunt.loadNpmTasks('grunt-amd-require-tests');

The "amd_require_tests" task

Overview

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

grunt.initConfig({
  amd_require_tests: {
    options: {
      path: 'optional/base/path/for/files/to/be/found',
      templateFile: 'optional/path/to/custom.template'
    },
    your_target: {
      files: {
        'path/to/generatedFile.js': ['path/to/test/files/to/find/e/g/**/*Spec.js']
      }
    },
  },
});

Options

options.path

Type: String Default value: './'

Optional base path for files to be found. Filename patterns will be searched from this base path, and filenames of discovered test files will appear in generated file with paths relative to this path.

options.templateFile

Type: String Default value: n/a

Optional path to a custom lodash template file to be used to generate the output file.

The object passed to the template function contains an array of file objects (named files) containing the following properties:

• .name filename with the trailing *.js truncated
• .fullName full filename
• .comma an empty string for the last file in the array, otherwise a comma

Usage Examples

The examples below assume a file directory structure such as:

/
|-- Gruntfile.js
+-- test
    |-- barSpec.js
    +-- foo
        +-- fooSpec.js

Default Options

In this example, the default options are used. A file named requireAllSpecs.js will be created, and it will contain JavaScript code that will "require" all files (via the define() function) matching the glob pattern test/**/*Spec.js. See the templateFile option to customize the format of the generated file.

By default, the file paths in the generated file will be relative to the path of the Gruntfile. Use the path option to set a different path.

Configuration:

grunt.initConfig({
  amd_require_tests: {
    files: {
      'test/requireAllSpecs.js': ['test/**/*Spec.js']
    },
  },
});

Sample output:

// **** do not edit - generated file **
// This file generated by grunt-amd-require-tests
// We use define rather than require as the former works with relative paths
define([
  './test/barSpec',
  './test/foo/fooSpec'
], function(){
  'use strict';
  return null;
});

Custom Path

In this example, a custom path is specified.

A file named requireAllSpecs.js will be created, and it will contain JavaScript code that will "require" all files (via the define() function) matching the glob pattern **/*Spec.js, relative to the specified path (test/).

The file paths in the generated file will also be relative to the specified path.

Configuration:

grunt.initConfig({
  amd_require_tests: {
    options: {
      path: 'test/',
    },
    files: {
      'test/requireAllSpecs.js': ['**/*Spec.js']
    },
  },
});

Sample output:

// **** do not edit - generated file **
// This file generated by grunt-amd-require-tests
// We use define rather than require as the former works with relative paths
define([
  './barSpec',
  './foo/fooSpec'
], function(){
  'use strict';
  return null;
});

Custom Template

In this example, a custom template file is specified.

A file named requireAllSpecs.js will be created, and it will contain JavaScript code that will "require" all files (via the require() function, as specified in the custom template) matching the glob pattern test/**/*Spec.js, relative to the Gruntfile.

Configuration:

grunt.initConfig({
  amd_require_tests: {
    options: {
      templateFile: 'path/to/custom.template',
    },
    files: {
      'test/requireAllSpecs.js': ['test/**/*Spec.js']
    },
  },
});

Sample template file:

// **** Custom template example ****
// You may provide a custom lodash template for the file to be generated
// with the `templateFile` option. The template is called with an array
// of file objects (named `files`) containing the following properties:
//   .name        filename with the trailing *.js truncated
//   .fullName    full filename
//   .comma       an empty string for the last file in the array, otherwise a comma
require([<% _.forEach(files, function(file, i, arr) {%>
  '${ file.name }'${ file.comma }  // ${ file.fullName }<% }); %>
], function(){});

Sample output:

// **** Custom template example ****
// You may provide a custom lodash template for the file to be generated
// with the `templateFile` option. The template is called with an array
// of file objects (named `files`) containing the following properties:
//   .name        filename with the trailing *.js truncated
//   .fullName    full filename
//   .comma       an empty string for the last file in the array, otherwise a comma
require([
  'test/barSpec',  // test/barSpec.js
  'test/foo/fooSpec'  // test/foo/fooSpec.js
], function(){});

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

(Nothing yet)