{
  "name": "grunt-mocha-test",
  "description": "A grunt task for running server side mocha tests",
  "version": "0.11.0",
  "homepage": "https://github.com/pghalliday/grunt-mocha-test",
  "author": {
    "name": "Peter Halliday",
    "email": "pghalliday@gmail.com",
    "url": "http://stuffpetedoes.blogspot.nl/"
  },
  "repository": {
    "type": "git",
    "url": "git://github.com/pghalliday/grunt-mocha-test.git"
  },
  "bugs": {
    "url": "https://github.com/pghalliday/grunt-mocha-test/issues"
  },
  "licenses": [
    {
      "type": "MIT",
      "url": "https://github.com/pghalliday/grunt-mocha-test/blob/master/LICENSE-MIT"
    }
  ],
  "main": "grunt.js",
  "engines": {
    "node": ">= 0.10.4"
  },
  "scripts": {
    "test": "grunt",
    "ci": "grunt ci"
  },
  "config": {
    "travis-cov": {
      "threshold": 100
    }
  },
  "dependencies": {
    "mocha": "~1.20.0",
    "hooker": "~0.2.3",
    "fs-extra": "~0.9.1"
  },
  "devDependencies": {
    "grunt-cli": "~0.1.13",
    "grunt": "~0.4.4",
    "chai": "~1.9.0",
    "grunt-contrib-jshint": "~0.10.0",
    "grunt-blanket": "~0.0.8",
    "grunt-contrib-copy": "~0.5.0",
    "grunt-contrib-clean": "~0.5.0",
    "travis-cov": "~0.2.5",
    "coffee-script": "~1.7.1",
    "mocha-lcov-reporter": "0.0.1",
    "grunt-coveralls": "~0.3.0",
    "cover-child-process": "~0.1.5",
    "grunt-env": "~0.4.1"
  },
  "keywords": [
    "gruntplugin",
    "mocha",
    "test"
  ],
  "readme": "# grunt-mocha-test\n\n[![Build Status](https://travis-ci.org/pghalliday/grunt-mocha-test.png)](https://travis-ci.org/pghalliday/grunt-mocha-test)\n[![Coverage Status](https://coveralls.io/repos/pghalliday/grunt-mocha-test/badge.png?branch=master)](https://coveralls.io/r/pghalliday/grunt-mocha-test?branch=master)\n[![Dependency Status](https://david-dm.org/pghalliday/grunt-mocha-test.png?theme=shields.io)](https://david-dm.org/pghalliday/grunt-mocha-test)\n[![devDependency Status](https://david-dm.org/pghalliday/grunt-mocha-test/dev-status.png?theme=shields.io)](https://david-dm.org/pghalliday/grunt-mocha-test#info=devDependencies)\n\nA grunt task for running server side mocha tests\n\n## Usage\n\nInstall next to your project's Gruntfile.js with: \n\n```\nnpm install grunt-mocha-test --save-dev\n```\n\nNote that due to some dependencies using newer features of `npm` it is necessary to update `npm` if still using the default version that ships with node 0.8. This can be done as follows:\n\n```\nnpm update npm -g \n```\n\nOn some systems it may be necessary to run this with `sudo`\n\n### Running tests\n\nHere is a simple example gruntfile if you just want to run tests\n\n```javascript\nmodule.exports = function(grunt) {\n\n  // Add the grunt-mocha-test tasks.\n  grunt.loadNpmTasks('grunt-mocha-test');\n\n  grunt.initConfig({\n    // Configure a mochaTest task\n    mochaTest: {\n      test: {\n        options: {\n          reporter: 'spec'\n        },\n        src: ['test/**/*.js']\n      }\n    }\n  });\n\n  grunt.registerTask('default', 'mochaTest');\n\n};\n```\n\nThe following mocha options are supported\n\n- grep\n- ui\n- reporter\n- timeout\n- invert\n- ignoreLeaks\n- growl\n- globals\n- bail\n- require\n- colors (specify as \"colors: true\")\n- slow\n\n### Specifying compilers\n\nThe Mocha `--compilers` option is almost identical to the `--require` option but with additional functionality for use with the Mocha `--watch` mode. As the `--watch` mode is not relevant for this plugin there is no need to implement a separate `compilers` option and actually the `require` option should be used instead.\n\nThe following example shows the use of the CoffeeScript compiler.\n\n```\nnpm install coffee-script\n```\n\n```javascript\nmochaTest: {\n  test: {\n    options: {\n      reporter: 'spec',\n      require: 'coffee-script/register'\n    },\n    src: ['test/**/*.coffee']\n  }\n}\n```\n\nIn order to make this more user friendly, the `require` option can take either a single file/function or an array of files/functions in case you have other globals you wish to require.\n\neg.\n\n```javascript\nmochaTest: {\n  test: {\n    options: {\n      reporter: 'spec',\n      require: [\n        'coffee-script/register',\n        './globals.js',\n        function(){ testVar1=require('./stuff'); },\n        function(){ testVar2='other-stuff'; }\n      ]\n    },\n    src: ['test/**/*.coffee']\n  }\n}\n```\n\nNB. File references for the `require` option can only be used with Javascript files, ie. it is not possible to specify a `./globals.coffee` in the above example.\n\n### Specifying a Mocha module\n\nIf you would like to use a different version of Mocha than the one packaged with this plugin, you can specify the module with the `mocha` option:\n\n```javascript\nmochaTest: {\n  test: {\n    options: {\n      mocha: require('mocha')\n    },\n    src: ['test/**/*.coffee']\n  }\n}\n```\n\n### Generating coverage reports\n\nHere is an example gruntfile that registers 2 test tasks, 1 to run the tests and 1 to generate a coverage report using `blanket.js` to instrument the javascript on the fly.\n\n```\nnpm install blanket\n```\n\n```javascript\nmodule.exports = function(grunt) {\n\n  grunt.loadNpmTasks('grunt-mocha-test');\n\n  grunt.initConfig({\n    mochaTest: {\n      test: {\n        options: {\n          reporter: 'spec',\n          // Require blanket wrapper here to instrument other required\n          // files on the fly. \n          //\n          // NB. We cannot require blanket directly as it\n          // detects that we are not running mocha cli and loads differently.\n          //\n          // NNB. As mocha is 'clever' enough to only run the tests once for\n          // each file the following coverage task does not actually run any\n          // tests which is why the coverage instrumentation has to be done here\n          require: 'coverage/blanket'\n        },\n        src: ['test/**/*.js']\n      },\n      coverage: {\n        options: {\n          reporter: 'html-cov',\n          // use the quiet flag to suppress the mocha console output\n          quiet: true,\n          // specify a destination file to capture the mocha\n          // output (the quiet option does not suppress this)\n          captureFile: 'coverage.html'\n        },\n        src: ['test/**/*.js']\n      }\n    }\n  });\n\n  grunt.registerTask('default', 'mochaTest');\n};\n```\n\nAs noted above it is necessary to wrap the blanket require when calling mocha programatically so `coverage/blanket.js` should look something like this.\n\n```javascript\nvar path = require('path');\nvar srcDir = path.join(__dirname, '..', 'src');\n\nrequire('blanket')({\n  // Only files that match the pattern will be instrumented\n  pattern: srcDir\n});\n```\n\nThis will preprocess all `.js` files in the `src` directory. Note that `Blanket` just uses pattern matching so this rework of the paths prevents files in `node_modules` being instrumented too. Also bear in mind using `Blanket` to instrument files on the fly only works if the file is not already in the require cache (this is an odd case but if you can't figure out why a file is not instrumented and the `pattern` looks ok then this may be the cause).\n\n### Failing tests if a coverage threshold is not reached\n\nBuilding on the previous example, if you wish to have your tests fail if it falls below a certain coverage threshold then I advise using the `travis-cov` reporter\n\n```\nnpm install travis-cov\n```\n\n```javascript\nmodule.exports = function(grunt) {\n\n  grunt.loadNpmTasks('grunt-mocha-test');\n\n  grunt.initConfig({\n    mochaTest: {\n      test: {\n        options: {\n          reporter: 'spec',\n          require: 'coverage/blanket'\n        },\n        src: ['test/**/*.js']\n      },\n      'html-cov': {\n        options: {\n          reporter: 'html-cov',\n          quiet: true,\n          captureFile: 'coverage.html'\n        },\n        src: ['test/**/*.js']\n      },\n      // The travis-cov reporter will fail the tests if the\n      // coverage falls below the threshold configured in package.json\n      'travis-cov': {\n        options: {\n          reporter: 'travis-cov'\n        },\n        src: ['test/**/*.js']\n      }\n    }\n  });\n\n  grunt.registerTask('default', 'mochaTest');\n};\n```\n\nDon't forget to update `package.json` with options for `travis-cov`, for example:\n\n```javascript\n  ...\n\n  \"config\": {\n    \"travis-cov\": {\n      // Yes, I like to set the coverage threshold to 100% ;)\n      \"threshold\": 100\n    }\n  },\n\n  ...\n```\n\n### Instrumenting source files with coverage data before running tests\n\n\nIn most cases it may be more useful to instrument files before running tests. This has the added advantage of creating intermediate files that will match the line numbers reported in exception reports. Here is one possible `Gruntfile.js` that uses the `grunt-blanket` plug in.\n\n```\nnpm install grunt-contrib-clean\nnpm install grunt-contrib-copy\nnpm install grunt-blanket\nnpm install travis-cov\n```\n\n```javascript\nmodule.exports = function(grunt) {\n\n  grunt.loadNpmTasks('grunt-mocha-test');\n  grunt.loadNpmTasks('grunt-contrib-clean');\n  grunt.loadNpmTasks('grunt-contrib-copy');\n  grunt.loadNpmTasks('grunt-blanket');\n\n  grunt.initConfig({\n    clean: {\n      coverage: {\n        src: ['coverage/']\n      }\n    },\n    copy: {\n      coverage: {\n        src: ['test/**'],\n        dest: 'coverage/'\n      }\n    },\n    blanket: {\n      coverage: {\n        src: ['src/'],\n        dest: 'coverage/src/'\n      }\n    },\n    mochaTest: {\n      test: {\n        options: {\n          reporter: 'spec',\n        },\n        src: ['/coverage/test/**/*.js']\n      },\n      coverage: {\n        options: {\n          reporter: 'html-cov',\n          quiet: true,\n          captureFile: 'coverage.html'\n        },\n        src: ['/coverage/test/**/*.js']\n      },\n      'travis-cov': {\n        options: {\n          reporter: 'travis-cov'\n        },\n        src: ['/coverage/test/**/*.js']\n      }\n    }\n  });\n\n  grunt.registerTask('default', ['clean', 'blanket', 'copy', 'mochaTest']);\n};\n```\n\nThis will delete any previously instrumented files, copy the `test` files to a `coverage` folder and instrument the `src` javascript files to the `coverage` folder. Lastly it runs tests from the `coverage` folder. It's more complicated but often easier to work with.\n\n### Running in permanent environments (like watch)\n\nIf you run `grunt-mocha-test` with `grunt-contrib-watch` using the `spawn: false` option, you will notice that the tests only run on the first change. Subsequent changes will result in an empty report with a `0 passing` message.\n\nThis happens because `mocha` loads your tests using `require` resulting in them being added to the require cache. Thus once they have been loaded in a process the subsequent calls to `require` hit the cache without executing the code again. To prevent this from happening, use the `clearRequireCache` option (default value is `false`).\n\nHere is an example that also demonstrates how to only run changed tests:\n\n```javascript\nmodule.exports = function(grunt) {\n\n  grunt.loadNpmTasks('grunt-mocha-test');\n  grunt.loadNpmTasks('grunt-contrib-watch');\n\n  grunt.initConfig({\n    mochaTest: {\n      test: {\n        options: {\n          reporter: 'spec',\n          clearRequireCache: true\n        },\n        src: ['test/**/*.js']\n      },\n    },\n\n    watch: {\n      js: {\n        options: {\n          spawn: false,\n        },\n        files: '**/*.js',\n        tasks: ['default']\n      }\n    }\n  });\n\n  // On watch events, if the changed file is a test file then configure mochaTest to only\n  // run the tests from that file. Otherwise run all the tests\n  var defaultTestSrc = grunt.config('mochaTest.test.src');\n  grunt.event.on('watch', function(action, filepath) {\n    grunt.config('mochaTest.test.src', defaultTestSrc);\n    if (filepath.match('test/')) {\n      grunt.config('mochaTest.test.src', filepath);\n    }\n  });\n\n  grunt.registerTask('default', 'mochaTest');\n};\n```\n\n### Using node flags\n\nThere are some flags that Mocha supports that are actually Node flags, eg.\n\n- --debug\n- --harmony-generators\n\nIt is currently not possible to set these at runtime when using Mocha as a library and as such cannot be supported by `grunt-mocha-test` without a major refactor (and severe impact on performance as it would involve spawning processes).\n\nThe recommended way of using these flags would be to pass them to node when starting the grunt process. The simplest way to do this would be to leverage the [`scripts`](https://www.npmjs.org/doc/misc/npm-scripts.html) functionality of NPM and `package.json`.\n\n```\n  ...\n  },\n  \"scripts\": {\n    \"test\": \"node --debug --harmony-generators ./node_modules/.bin/grunt test\"\n  }\n  ...\n```\n\nThe tests would then be run using\n\n```\nnpm test\n```\n\nNote that this assumes that `grunt-cli` has been installed locally and not globally\n\n## Contributing\nIn 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: \n\n```\nnpm test\n```\n\n## License\nCopyright © 2014 Peter Halliday  \nLicensed under the MIT license.\n\n[![Donate Bitcoins](https://coinbase.com/assets/buttons/donation_large-6ec72b1a9eec516944e50a22aca7db35.png)](https://coinbase.com/checkouts/9d121c0321590556b32241bbe7960362)\n",
  "readmeFilename": "README.md",
  "_id": "grunt-mocha-test@0.11.0",
  "dist": {
    "shasum": "75e41ba107590e4acbd29860925c012e443ca322"
  },
  "_from": "grunt-mocha-test@0.11.0",
  "_resolved": "https://registry.npmjs.org/grunt-mocha-test/-/grunt-mocha-test-0.11.0.tgz"
}