Norse Polytheistic Mythology


    2.0.3 • Public • Published

    Grunt JavaScript Test Runner Build Status Dependency Status

    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.

    Getting Started

    This plugin requires Grunt '~0.4.0'

    npm install grunt-js-test --save-dev

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


    Configure your Grunt task

    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.

    Write your tests

    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).

    Loading dependencies

    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:


    /// <reference path="test.setup.html" />
    /// <reference path="dosomething.js" />


    /// <reference path="library.js" />
    /// <reference path="app.css" />

    and so on. Until a tree is built like:

    - js:
    - css:
    - 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.

    Adding custom HTML to test pages

    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" />

    Adding CSS stylesheets to test pages

    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" />

    Grunt tasks


    Run this task with the grunt js-test command.

    Run all test files with PhantomJS. The minimal config would be:

        'js-test': {
            'default': {
                'options': {}
      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.


    Command Line Interface Options


    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.

    --identifier="commit deadbeef"

    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.

    Task Options

    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

    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: phantomOptions: { timeout: 20000 }

    Object of options to pass to PhantomJS


    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


    npm i grunt-js-test

    DownloadsWeekly Downloads






    Unpacked Size

    2.52 MB

    Total Files


    Last publish


    • texclayton