qunit (built-in task)

Run QUnit unit tests in a headless PhantomJS instance.

About

This task is a multi task, meaning that grunt will automatically iterate over all qunit targets if a target is not specified.

Need some help getting started with grunt? Visit the getting started page. And if you're creating your own tasks or helpers, be sure to check out the types of tasks page as well as the API documentation.

QUnit

QUnit is a powerful, easy-to-use, JavaScript test suite. It's used by the jQuery project to test its code and plugins but is capable of testing any generic JavaScript code.

PhantomJS

PhantomJS is a headless WebKit with JavaScript API. It has fast and native support for various web standards: DOM handling, CSS selector, JSON, Canvas, and SVG. PhantomJS is required for the qunit task to work.

See the FAQ for instructions on installing PhantomJS.

A Very Important Note

Your grunt.js gruntfile must contain this code, once and only once. If it doesn't, grunt won't work. For the sake of brevity, this "wrapper" code has been omitted from all examples on this page, but it needs to be there.

module.exports = function(grunt) {
  // Your grunt code goes in here.
};

Project configuration

This example shows a brief overview of the config properties used by the qunit task. For a more in-depth explanation, see the usage examples.

// Project configuration.
grunt.initConfig({
  // Lists of files or URLs to be unit tested with QUnit.
  qunit: {}
});

Usage examples

Wildcards

In this example, grunt qunit will test all .html files in the test directory. First, the wildcard is expanded to match each individual file. Then, each matched filename is converted to the appropriate file:// URI. Finally, QUnit is run for each URI.

// Project configuration.
grunt.initConfig({
  qunit: {
    all: ['test/*.html']
  }
});

With a slight modification, grunt qunit will test all .html files in the test directory and all subdirectories. See the minimatch module's documentation for more details on wildcard patterns.

// Project configuration.
grunt.initConfig({
  qunit: {
    all: ['test/**/*.html']
  }
});

Testing via http:// or https://

In circumstances where running unit tests from file:// URIs is inadequate, you can specify http:// or https:// URIs instead. If http:// or https:// URIs have been specified, those URIs will be passed directly into QUnit as-specified.

In this example, grunt qunit will test two files, served from the server running at localhost:8000.

// Project configuration.
grunt.initConfig({
  qunit: {
    all: ['http://localhost:8000/test/foo.html', 'http://localhost:8000/test/bar.html']
  }
});

Note: grunt does NOT start a server at localhost:8000 automatically. While grunt DOES have a server task that can be run before the qunit task to serve files statically, it must be started manually...

Using the built-in static webserver

If a web server isn't running at localhost:8000, running grunt qunit with http://localhost:8000/ URIs will fail because grunt won't be able to load those URIs. This can be easily rectified by starting the built-in static web server via the server task.

In this example, running grunt server qunit will first start a static web server on localhost:8000, with its base path set to the gruntfile's directory. Then, the qunit task will be run, requesting the specified URIs from that server.

// Project configuration.
grunt.initConfig({
  qunit: {
    all: ['http://localhost:8000/test/foo.html', 'http://localhost:8000/test/bar.html']
  },
  server: {
    port: 8000,
    base: '.'
  }
});

// A convenient task alias.
grunt.registerTask('test', 'server qunit');

Note: in the above example, an alias task called test was created that runs both the server and qunit tasks.

Debugging

Running grunt with the --debug flag will output a lot of PhantomJS-specific debugging information. This can be very helpful in seeing what actual URIs are being requested and received by PhantomJS.

See the qunit task source for more information.

4.6 KiB Raw Blame History