grunt-js-test is a plugin for Grunt that is designed to run client-side unit tests using Mocha. You can easily run tests through the command line or a continuous integration suite using PhantomJS or it can provide a server to run your tests in a browser using WebDriver and for writing and testing of unit tests. grunt-js-test can also generate coverage reports using either JSCover or Istanbul.
This plugin requires Grunt '~0.4.0'
npm install grunt-js-test --save-devOnce the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-js-test');Open your Gruntfile.js and add your project's configuration as desired (all the options are described below). If you rely on all the defaults, you don't even need to provide anything.
A few simple example projects are available in the examples directory.
Tests are loaded already wrapped up including Mocha, Chai and Sinon. This means you are good to start writing tests immediately.
A simple example unit test using Mocha:
describe('Array', function(){
describe('#indexOf()', function(){
it('should return -1 when the value is not present', function(){
chai.assert.equal(-1, [1,2,3].indexOf(5));
chai.assert.equal(-1, [1,2,3].indexOf(0));
});
});
});If you prefer to use another assert library other than Chai, you can optionally include it as a dependency (see deps option below).
grunt-js-test generates the test HTML page for you, making it quicker to write client-side tests. However, this means that you need a way to load the dependent JavaScript files. grunt-js-test supports require.js projects natively, simply configure the options requirejs and modulesRelativeTo as needed. If you are not creating a require.js based project, then grunt-js-test implements support for JScript IntelliSense Reference Tags. This allows you to easily load dependencies using a format of:
/// <reference path="../relative/file.js" />There is an example project using these reference tags in our examples directory as examples/references.
These reference tags are processed recursively and a dependency tree is created, then sorted, to generate a complete list of dependencies needed in an appropriate order. Therefore you can include files such as:
test.js
/// <reference path="test.setup.html" />
/// <reference path="dosomething.js" />dosomething.js
/// <reference path="library.js" />
/// <reference path="app.css" />and so on. Until a tree is built like:
- js:
library.js
dosomething.js
test.js
- css:
app.css
- html:
test.setup.html
When rendering the test page, all of these dependencies will be included. You can disable all of this functionality if not desired by setting the referenceTags option to false.
As grunt-js-test generates the test HTML pages for you, on occasion you need to add some HTML to the DOM of the page prior to your JavaScript running. There are two ways to do this, the easiest is to simply create a file named .inject.html alongside your test JavaScript file.
For example, if you had a test file called something.unittests.js you could have a similarly named file something.unittests.inject.html, the contents of which would be added to the body of the generated test page.
There is an example project using these reference tags in our examples directory as examples/injectHTML.
You can also reference .html files you wish to have injected using a reference tags similar to referencing JavaScript dependencies. The format of which is simply:
/// <reference path="../relative/path/to/file/to/inject.html" />If you need to add a dependency for a stylesheet, you can include one globally using the stylesheets option or include one on a per-test-file basis using reference tags similarly to how they are used for JavaScript and HTML file dependencies. The format of which is simply:
/// <reference path="../relative/path/to/stylesheet/to/include.css" />Run this task with the grunt js-test command.
Run all test files with PhantomJS. The minimal config would be:
grunt.initConfig({
'js-test': {
'default': {
'options': {}
}
}
});
grunt.loadNpmTasks('grunt-js-test');
grunt.registerTask('test', ['js-test']);Run this task with the grunt js-test-server command.
Start a web server on your local host to allow you to run the unit tests individually.
Pass --coverage while running Grunt to turn on coverage with the default coverageTool. You can pass a value of a string to select the coverage tool you'd like to use, such as --coverage=jscover.
Pass --identifier with a value of a string you'd like to use as your job identifier. This will be the folder name used when saving your coverage reports to the directory configured with coverageReportDirectory. This is useful when using grunt-js-test through continuous integration and want to provide it either the job number or the commit id (or revision number if you're still on SVN).
By default a datetime in the format of YYYY-MM-DD HHMMSS will be used.
These filters allow you to narrow down the tests you run via the js-test CLI. These can be useful when you want are writing a test and want to test it, or a single test is failing and you want to debug it.
Pass --file=test/something.js to provide the path to a specific file you want to run.
Pass --search=jquery with a simple string run only the tests that have file names containing the given string. This filter is always case insensitive. You can use * for a wildcard match.
Pass --bail to stop running tests once a single unit test fails.
Pass --reporter=reporter to specify the reporter to use when running tests.
Pass --log to pass all console.log statements from your unit tests from PhantomJS to the Node console.
All options of js-test are optional, if you specify nothing, it will run all JavaScript files anywhere in your project directory, recursively matching *.unittests.js.
Type: String
Default: process.cwd()
Defines the root path to your project files. A static file web server is started on this path to allow your unit tests to load their dependencies.
Type: String|Array<String>
Default: **/*.unittests.js
Glob search pattern to locate your unit tests. For more information on glob patterns please see node-glob. This can optionally be an array of globs which will all be used to find a file matching any of the glob patterns.
Type: Array<String|RegExp>
Default: []
Array of simple string searches or regular expression used to whitelist tests. If a test does not match all of these filters it is ignored.
Type: Array<String|RegExp>
Default: ['/node_modules/']
Array of simple string searches or regular expressions used to blacklist tests. If a test matches one of these filters it is ignored.
Type: String
Default: /
Base path used when loading web assets.
Type: Array<String>
Default: []
A list of paths to JavaScript files relative to your baseUri you want loaded as global dependencies for each test. You can also include external dependencies, such as http://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.js.
Dependencies can be injected on a per test file basis using <reference> tags. See loading dependencies.
Type: Array<String>
Default: []
A list of paths to CSS files relative to your baseUri you want loaded for each test. You can also include external stylesheets.
Stylesheets can be injected on a per test file basis using <reference> tags. See loading dependencies.
Type: Boolean
Default: true
Look for <reference> tags within unit test files to automatically include additional dependencies. See loading dependencies. Usually never hurts to leave it on.
Type: String
Default: localhost
Hostname for web server when running the js-test-server grunt task.
Type: Number
Default: 8981
Port for web server when running the js-test-server grunt task.
Type: number
Default: 8982
Port used for static web server that serves up your unit test dependency files. Should never have to change this unless something else uses this port.
Type: number
Default: 8983
Port used for proxy web server that instruments your JavaScript files for code coverage reporting. Should never have to change this unless something else uses this port.
Type: Object
Default: {}
Object of options to pass to the grunt-mocha task. Hopefully you never need to override anything here.
Type: String
Default: Spec
Mocha reporter used by js-test when reporting to the console.
Supported reporters are Spec, Nyan, XUnit, Dot, List, Progress, JSON, Min and Doc. For a more complete list, see Mocha reporters. The reporter value is case sensitive. Min and Dot are very helpful when debugging a failing test.
Type: Boolean
Default: false
Should the test environment generate coverage reports? This can slow down running the tests, but will generate you code coverage reporting data.
Type: String
Default: istanbul
Choose between either jscover or istanbul for your coverage instrumentation and reporting service.
Type: String
Default: process.cwd() + '/coverage'
Specify a directory where coverage report data should be saved.
Type: Boolean
Default: false
This identifies your project as being a requirejs based project, which means that we do not include your test file directly but instead allow require.js to load it.
Type: String
Default: null
This defines the path your modules should be relative to, if it's different than your project's root directory. Only applicable when your project is a requirejs based project.
Type: String
Default: null
Optional query string data to add to URLs when unit tests are running via the js-test command. Format must be a string with no prefixed ampersand. Example: key=value&key2=value2.
Type: String
Default: null
Optional raw HTML string that added to all of the test pages generated by grunt-js-test. You can load files using this command by using the fs module, example: require('fs').readFileSync('tests/setup.html').
Type: String
Default: null
Optional web server address that provides HTML responses that should be injected into test pages. Similar to injectHTML. This can be used to inject rendered templates into your tests, if needed.
An example value would be: http://localhost:3000/dev/render
A request will be made to the url you provide and will provide the test file with it's path relative from the root directory as a query string paramater file. Example: ?file=test/example.unittests.js