Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 142 lines (93 sloc) 5.171 kb
f4580d2 @cowboy Adding qunit task documentation.
authored
1 [Grunt homepage](https://github.com/cowboy/grunt) | [Documentation table of contents](toc.md)
2
3 # qunit (built-in task)
891f045 @cowboy Minor qunit task docs tweaks.
authored
4 Run [QUnit][qunit] unit tests in a headless [PhantomJS][phantom] instance.
5
6 [qunit]: http://docs.jquery.com/QUnit
7 [phantom]: http://www.phantomjs.org/
f4580d2 @cowboy Adding qunit task documentation.
authored
8
9 ## About
10
4ba671a @cowboy More docs.
authored
11 This task is a [multi task](tasks_creating.md), meaning that grunt will automatically iterate over all `qunit` targets if a target is not specified.
f4580d2 @cowboy Adding qunit task documentation.
authored
12
ccd251c @cowboy Docs tweaks.
authored
13 _Need some help getting started with grunt? See the [configuring grunt](configuring.md) page._
f4580d2 @cowboy Adding qunit task documentation.
authored
14
49a4ba0 @cowboy More docs.
authored
15 ## Project configuration
16
17 This example [gruntfile](configuring.md) shows a brief overview of the [config](api_config.md) properties used by the `qunit` task. For a more in-depth explanation, see the usage examples.
18
19 ```javascript
20 exports.config = function(grunt) {
21
22 // Project configuration.
23 grunt.initConfig({
24 // Lists of files or URLs to be unit tested with QUnit.
25 qunit: {},
26 });
27
28 };
29 ```
30
f4580d2 @cowboy Adding qunit task documentation.
authored
31 ## Usage examples
32
33 ### Wildcards
34
891f045 @cowboy Minor qunit task docs tweaks.
authored
35 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][qunit] is run for each URI.
f4580d2 @cowboy Adding qunit task documentation.
authored
36
37 ```javascript
20bfdaa @cowboy More docs.
authored
38 exports.config = function(grunt) {
39
40 // Project configuration.
41 grunt.initConfig({
42 qunit: {
43 all: ['test/*.html']
44 }
45 });
46
47 };
f4580d2 @cowboy Adding qunit task documentation.
authored
48 ```
49
50 With a slight modification, `grunt qunit` will test all `.html` files in the test directory _and all subdirectories_. See the [minimatch](https://github.com/isaacs/minimatch) module's documentation for more details on wildcard patterns.
51
52 ```javascript
20bfdaa @cowboy More docs.
authored
53 exports.config = function(grunt) {
54
55 // Project configuration.
56 grunt.initConfig({
57 qunit: {
58 all: ['test/**/*.html']
59 }
60 });
61
62 };
f4580d2 @cowboy Adding qunit task documentation.
authored
63 ```
64
65 ### Testing via http:// or https://
66
891f045 @cowboy Minor qunit task docs tweaks.
authored
67 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][qunit] as-specified.
f4580d2 @cowboy Adding qunit task documentation.
authored
68
69 In this example, `grunt qunit` will test two files, served from the server running at `localhost:8000`.
70
71 ```javascript
20bfdaa @cowboy More docs.
authored
72 exports.config = function(grunt) {
73
74 // Project configuration.
75 grunt.initConfig({
76 qunit: {
77 all: ['http://localhost:8000/test/foo.html', 'http://localhost:8000/test/bar.html']
78 }
79 });
80
81 };
f4580d2 @cowboy Adding qunit task documentation.
authored
82 ```
83
891f045 @cowboy Minor qunit task docs tweaks.
authored
84 _Note: grunt does NOT start a server at `localhost:8000` automatically. While grunt DOES have a [server](task_server.md) task that can be run before the qunit task to serve files statically, it must be started manually..._
f4580d2 @cowboy Adding qunit task documentation.
authored
85
86 ### Using the built-in static webserver
87
891f045 @cowboy Minor qunit task docs tweaks.
authored
88 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_server.md) task.
f4580d2 @cowboy Adding qunit task documentation.
authored
89
891f045 @cowboy Minor qunit task docs tweaks.
authored
90 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.
f4580d2 @cowboy Adding qunit task documentation.
authored
91
92 ```javascript
20bfdaa @cowboy More docs.
authored
93 exports.config = function(grunt) {
94
95 // Project configuration.
96 grunt.initConfig({
97 qunit: {
98 all: ['http://localhost:8000/test/foo.html', 'http://localhost:8000/test/bar.html']
99 },
100 server: {
101 port: 8000,
102 base: '.'
103 }
104 });
105
106 // A convenient task alias.
107 grunt.registerTask('test', 'server qunit');
108
109 };
f4580d2 @cowboy Adding qunit task documentation.
authored
110 ```
111
20bfdaa @cowboy More docs.
authored
112 _Note: in the above example, an [alias task](tasks_creating.md) called `test` was created that runs both the `server` and `qunit` tasks._
f4580d2 @cowboy Adding qunit task documentation.
authored
113
891f045 @cowboy Minor qunit task docs tweaks.
authored
114 ## QUnit
115
116 [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.
117
f4580d2 @cowboy Adding qunit task documentation.
authored
118 ## PhantomJS
119
120 [PhantomJS](http://www.phantomjs.org/) 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.
121
122 ### Installation
123
124 There are a number of ways to install PhantomJS.
125
126 * [PhantomJS and Mac OS X](http://ariya.ofilabs.com/2012/02/phantomjs-and-mac-os-x.html)
127 * [PhantomJS Installation](http://code.google.com/p/phantomjs/wiki/Installation) (PhantomJS wiki)
128
891f045 @cowboy Minor qunit task docs tweaks.
authored
129 ### Updating the system PATH
130
131 The `phantomjs` executable needs to be in the system `PATH` for grunt to see it.
f4580d2 @cowboy Adding qunit task documentation.
authored
132
133 * [How to set the path and environment variables in Windows](http://www.computerhope.com/issues/ch000549.htm)
134 * [Where does $PATH get set in OS X 10.6 Snow Leopard?](http://superuser.com/questions/69130/where-does-path-get-set-in-os-x-10-6-snow-leopard)
135 * [How do I change the PATH variable in Linux](https://www.google.com/search?q=How+do+I+change+the+PATH+variable+in+Linux)
136
137 ## Debugging
138
139 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.
140
24f2be1 @cowboy More docs.
authored
141 See the [qunit task source](../tasks/qunit.js) for more information.
Something went wrong with that request. Please try again.