# grunt-mocha-phantomjs
> A simple wrapper to run client-side mocha tests using [mocha-phantomjs](http://metaskills.net/mocha-phantomjs/) core library
[](https://travis-ci.org/jdcataldo/grunt-mocha-phantomjs)
[](https://www.npmjs.com/package/grunt-mocha-phantomjs)
## Getting Started
This plugin requires Grunt `~0.4.0`
If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
```shell
npm install grunt-mocha-phantomjs --save-dev
```
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
```js
grunt.loadNpmTasks('grunt-mocha-phantomjs');
```
## The "mocha_phantomjs" task
_Run this task with the `grunt mocha_phantomjs` command._
Task targets, files and options may be specified according to the grunt [Configuring tasks](http://gruntjs.com/configuring-tasks) guide.
[PhantomJS][] is installed when installing using NPM.
[PhantomJS]: http://www.phantomjs.org/
### Options
#### reporter
Type: `String`
Default: `spec`
The reporter that should be used. See [the supported reporters](https://github.com/metaskills/mocha-phantomjs#supported-reporters) for more information.
#### output
Type: `String`
The file that the task should output the results to. If `output` is specified, the task will always complete and not throw an error code if errors are found. The CI will determine if the build failed or not.
#### failWithOutput
Type: `Boolean`
Setting `failWithOutput` to true when used with the `output` option will fail a build along with creating a test artifact. This is useful for CIs (CircleCI) that don't fail a build based on the test artifact.
#### silent
Type: `Boolean`
Setting `silent` to true will prevent the results from being printed using stdout.
#### urls
Type: `Array`
Default: `[]`
Absolute `http://` or `https://` urls to be passed to PhantomJS. Specified URLs will be merged with any specified `src` files first. Note that urls must be served by a web server, and since this task doesn't contain a web server, one will need to be configured separately. The [grunt-contrib-connect plugin](https://github.com/gruntjs/grunt-contrib-connect) provides a basic web server.
Additional arguments may be passed. See [mocha-phantomjs's](https://github.com/metaskills/mocha-phantomjs#usage) usage.
#### phantomConfig
Type: `Object`
Default: `{}`
Options to be passed directly to phantomjs. Eg:
```js
{
"--local-storage-path": "my/temp-phantom-files",
"--local-storage-quota": "20480"
}
```
See `phantomjs -h` for more full options list.
#### config
Type: `Object`
Default: `{ useColors: true }`
Options to be passed to mocha-phantomjs. See [mocha-phantomjs-core's](https://github.com/nathanboktae/mocha-phantomjs-core#usage) usage.
### Usage examples
#### Basic usage (CI checks for error code)
```js
// Project configuration.
grunt.initConfig({
mocha_phantomjs: {
all: ['test/**/*.html']
}
});
```
#### File output for CI
```js
// Project configuration.
grunt.initConfig({
mocha_phantomjs: {
options: {
reporter: 'xunit',
output: 'tests/results/result.xml'
},
all: ['test/**/*.html']
}
});
```
#### Passing options to mocha-phantomjs
```js
// Project configuration.
grunt.initConfig({
mocha_phantomjs: {
options: {
reporter: 'xunit',
output: 'tests/results/result.xml',
config: {
useColors: false,
viewportSize: {
width: 1024,
height: 768
},
grep: 'pattern'
}
},
all: ['test/**/*.html']
}
});
```
#### Local server
Include the [grunt-contrib-connect plugin][] to run a local server
[grunt-contrib-connect plugin]: https://github.com/gruntjs/grunt-contrib-connect
```js
// Project configuration.
grunt.initConfig({
mocha_phantomjs: {
all: {
options: {
urls: [
'http://localhost:8000/test/foo.html',
'http://localhost:8000/test/bar.html'
]
}
}
},
connect: {
server: {
options: {
port: 8000,
base: '.',
}
}
}
});
grunt.registerTask('test', ['connect', 'mocha_phantomjs']);
```
### Notes
This is a very basic implementation of mocha-phantomjs. Failed tests and errors do not bubble up for custom reporting. The idea of this is to be mainly used by a CI and let the CI manage the error reporting.