# grunt-mocha

> Grunt task for running client-side Mocha specs in PhantomJS

Latest version **1.2.0** (published 2019-01-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install grunt-mocha
pnpm add grunt-mocha
yarn add grunt-mocha
bun add grunt-mocha
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2019-01-17 |
| First published | 2012-04-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=6 |
| Dependencies | 3 |
| Unpacked size | 36 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | Kelly Miyashiro |
| Maintainers | byk, disqus-oss, kmiyashiro, tail |
| Keywords | gruntplugin, mocha, test, phantomjs |

## Links

- npm: https://www.npmjs.com/package/grunt-mocha
- Repository: https://github.com/disqus/grunt-mocha
- Issues: https://github.com/disqus/grunt-mocha/issues
- npm.io page: https://npm.io/package/grunt-mocha

## Dependencies (3)

- [mocha](https://npm.io/package/mocha.md) ^5.2.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.11
- [grunt-lib-phantomjs](https://npm.io/package/grunt-lib-phantomjs.md) ^1.1.0

## Alternatives

- [duck](https://npm.io/package/duck.md) — 4.2M weekly downloads
- [ava](https://npm.io/package/ava.md) — 560.2K weekly downloads
- [storybook-addon-module-mock](https://npm.io/package/storybook-addon-module-mock.md) — 71.7K weekly downloads
- [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) — 40.0K weekly downloads

## Recent versions

- 1.2.0 (latest) — 2019-01-17
- 0.2.0 (devel) — 2012-12-18
- 1.1.0 — 2018-06-18
- 1.0.5 — 2018-06-16
- 1.0.4 — 2017-01-30
- 1.0.3 — 2017-01-26
- 1.0.2 — 2016-05-01
- 1.0.1 — 2016-04-08
- 1.0.0 — 2016-03-27
- 0.4.15 — 2015-12-01
- 0.4.14 — 2015-12-01
- 0.4.13 — 2015-06-24
- 0.4.12 — 2015-02-27
- 0.4.11 — 2014-05-31
- 0.4.10 — 2014-01-21
- … 24 more at https://npm.io/package/grunt-mocha/versions

## README

# grunt-mocha [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url]

> Automatically run *client-side* mocha specs via grunt/mocha/PhantomJS

For a grunt task for server-side mocha tests, see [grunt-mocha-test](https://github.com/pghalliday/grunt-mocha-test) or [grunt-simple-mocha](https://github.com/yaymukund/grunt-simple-mocha)

## Getting Started

This plugin requires Grunt `~0.4.0`. Use a `0.1.x` tag of this plugin to use with Grunt `~0.3.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 --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');
```

## Mocha task
_Run this task with the `grunt mocha` command._

### Settings

#### files/src

Type: `String|Array`

This defines which HTML spec files to run using PhantomJS. These are the same files you would open to run tests in a browser.

There are a number of options available. Please review the [minimatch options here](https://github.com/isaacs/minimatch#options).

Example:
```js
mocha: {
  test: {
    src: ['tests/**/*.html'],
  },
},
```

#### dest
Type: `String`
Default: `undefined`

Write reporter output to a file. Useful if you need a file to feed your CI bot.

Example:
```js
mocha: {
  test: {
    options: {
      reporter: 'XUnit'
    },
    src: ['tests/**/*.html'],
    dest: './test/output/xunit.out',
  },
},
```

#### options.run
Type: `Boolean`
Default: `true`

grunt-mocha injects a script into the PhantomJS instance that loads your HTML spec files. The file sets up a reporter and listeners so the output can be output in the command line. This option will call `mocha.run()` after the script is injected, ensuring that the proper listeners are setup.

You may want to set this to false if your files are loaded asynchronously via AMD and call `mocha.run` in your own callback.

In HTML spec:
```html
<!-- run mocha after all test are loaded -->
<script type="text/javascript" charset="utf-8">
  // Only tests run in real browser, injected script run if options.run == true
  if (navigator.userAgent.indexOf('PhantomJS') < 0) {
    mocha.run();
  }
</script>
```

Gruntfile:
```js
mocha: {
  test: {
    src: ['tests/**/*.html'],
    options: {
      run: true,
    },
  },
},
```

#### options.urls
Type: `Array|String`
Default: `[]`

Instead of files, hit these URLs. Usually used in conjunction with the connect task to spin up a server for testing.

```js
connect: {
  server: {
    options: {
      port: 8888,
      base: '.',
    },
  },
},
mocha: {
  test: {
    options: {
      urls: [ 'http://localhost:8888/example/test/test2.html' ],
    },
  },
},
```

Then run:
```
grunt connect mocha
```

#### options.timeout
Type: `Number`
Default: `5000`

PhantomJS timeout in milliseconds. If nothing happens within 5 seconds, exit.

Example:
```js
mocha: {
  test: {
    src: ['tests/**/*.html'],
    options: {
      timeout: 10000,
    },
  },
},
```

#### options.bail
Type: `Boolean`
Default: `false`

Call `grunt.warn` and exit the grunt task on the first failed test. This only calls `grunt.warn` after the entire spec file is finished.

Example:
```js
mocha: {
  test: {
    src: ['tests/**/*.html'],
    options: {
      bail: true,
    },
  },
},
```

#### options.growlOnFail
Type: `Boolean`
Default: `true`

Display a Growl notification when tests fail.

Example:
```js
mocha: {
  test: {
    src: ['tests/**/*.html'],
    options: {
      growlOnFail: false,
    },
  },
},
```

#### options.growlOnSuccess
Type: `Boolean`
Default: `true`

Display a Growl notification when all tests successfully pass.

Example:
```js
mocha: {
  test: {
    src: ['tests/**/*.html'],
    options: {
      growlOnSuccess: false,
    },
  },
},
```

#### options.log
Type: `Boolean`
Default: `false`

Print any `console.log` calls from PhantomJS to the command line. Only used for very quick and dirty debugging. It is highly recommended that you open the failing spec file in a browser so you can use much richer debugging tools.

Example:
```js
mocha: {
  test: {
    src: ['tests/**/*.html'],
    options: {
      log: true,
    },
  },
},
```

#### options.logErrors
Type: `Boolean`
Default: `false`

Fail and output script errors.

Example:
```js
mocha: {
  test: {
    src: ['tests/**/*.html'],
    options: {
      logErrors: true,
    },
  },
},
```

#### options.mocha
Type: `Object`

A mocha options simple object. Very few options are currently supported. Actually, I think `grep` is the only one.

Example:
```js
mocha: {
  test: {
    src: ['tests/**/*.html'],
    options: {
      mocha: {
        grep: 'router*'
      }
    }
  },
},
```

#### options.reporter
Type: `String`
Default: `'Dot'`

The reporter to use. **Note:** XUnit and those types of reporters should probably use the `dest` option.

Example:
```js
mocha: {
  test: {
    files: ['tests/**/*.html'],
    options: {
      reporter: 'Nyan',
    }
  },
},
```

Custom reporter example:
Example:
```js
mocha: {
  test: {
    files: ['tests/**/*.html'],
    options {
      reporter: './path/to/custom/reporter', // included via require
    },
  },
},
```

### options.page
Type: `Object`

Set properties in the PhantomJS webpage instance used for tests, see http://phantomjs.org/api/webpage/

Example:
```js
mocha: {
  test: {
    options: {
      page: {
        settings: {
          webSecurityEnabled: false,  // disable cors checks in phantomjs
        },  
      },
    },
  },
},
```

## Hacks

The PhantomJS -> Grunt superdimensional conduit uses `alert`. If you have disabled or aliased alert in your app, this won't work. I have conveniently set a global `PHANTOMJS` on `window` so you can conditionally override alert in your app.

## Examples

### Vanilla JS

#### Option 1 (recommended)

- Write mocha task description in grunt config using and specify `run: true` option (see [this task's Gruntfile.js](Gruntfile.js) for details);
- Check for PhantomJS `userAgent` in a test html file and run tests only in a real browser (see [test2.html](example/test/test2.html) for details).

In this case you shouldn't include [bridge.js](phantomjs/bridge.js) (it will be included automatically) and tests will be run from [bridge.js](phantomjs/bridge.js).

#### Option 2

Alternatively, include `bridge.js` from `tasks/phantomjs` after you include `mocha.js` and run `mocha.setup` in your HTML file. The helper will override `mocha.setup` if it detects PhantomJS. See [test.html](example/test/test.html).

### AMD

Mocha **must** be included via script tag in the header. There is no need to load Mocha via AMD. You may load other testing libs via AMD if that gives you a fuzzy feeling.

Example setup with AMD (advanced): https://gist.github.com/2655876

## License
Licensed under the MIT license.

[npm-image]: https://img.shields.io/npm/v/grunt-mocha.svg?style=flat-square
[npm-url]: https://www.npmjs.com/package/grunt-mocha
[travis-image]: https://img.shields.io/travis/disqus/grunt-mocha/master.svg?style=flat-square
[travis-url]: https://travis-ci.org/disqus/grunt-mocha

---
_Source: https://npm.io/package/grunt-mocha · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._