Grunt task to run Mocha tests against a Selenium grid
npm install grunt-mocha-webdriver
|39||downloads in the last day|
|175||downloads in the last week|
|435||downloads in the last month|
|Version||0.9.17 last updated a month ago|
|Dependencies||wd, async, mocha, sauce-tunnel|
A Grunt task that runs Mocha-based functional tests against a Webdriver-enabled source: specifically, PhantomJS for local testing and Sauce Labs for comprehensive cross-browser testing. This plugin is a combination of mocha-cloud and grunt-saucelabs. The former library doesn't have Grunt integration built in, and is designed for running tests inside the browser; the latter library can launch a grid of browsers on Sauce Labs, but doesn't support Mocha.
This plugin requires Grunt
>=0.4.0; connecting to Sauce Labs requires java.
Install the plugin with:
npm install grunt-mocha-webdriver --save-dev
Then add this line to your project's Gruntfile:
Using grunt-mocha-webdriver with Phantomjs
In version 0.9.4 and later, phantom is included via its NPM module. In order
to run tests against phantom, simply add the
usePhantom flag to the options hash.
The plugin defaults to hitting port 4444, but you can specify your own port via
Using grunt-mocha-webdriver with your own Selenium server
In version 0.9.15 and later, You can run your tests against your own Selenium server instance.
To do so, use
Don't forget to remove
Note that the Selenium server should be started and ready before starting the tests.
Run this task with the
mochaWebdriver grunt command. For this plugin, the Grunt
src property will specify which test files should be run with Mocha in
mochaWebdriver multitask. These tests should be structured as normal
Mocha tests, but should use
this.browser to refer to a WebDriver browser
which will be injected into the test's context. The browser can be driven
with the API specified in WD.js. The default
is to use the callback-enabled version of WD.js, but
usePromises can be passed
true to switch to the Promise-enabled version.
As of version
0.2.3 of WD.js, wd provides the ability
to add test methods to its default set of capabilities.
wd instance in the same way that
browser is exposed, so that
you can easily add your own test methods to wd.
Also, Mocha options are exposed to tests. This is especially helpful if you want to reuse the defined Mocha timeout for your Webdriver tests. For example you can do this in your Webdriver based E2E tests:
this.browser.waitForElementByCss('.aClass', this.mochaOptions.timeout, cb);
Please look at this project's Gruntfile and tests to see all that in action.
The usual Mocha options are passed through this task to a new Mocha instance. Please note that while it's possible to specify the Mocha reporter for tests running on Phantom, there's only one reporter currently supported for tests against Sauce Labs. This restriction is in place to handle concurrent Sauce Labs testing sessions, which could pollute the log.
The following options can be supplied to the task:
Specifies whether the task should test against a PhantomJS instance instead of Sauce Labs. Defaults to false. If true, the tests will run against Phantom INSTEAD of running against Sauce Labs.
Type: Int (Default: 4444)
if testing against PhantomJS with the
usePhantom flag, specify the port
to test against.
Specifies whether to use the Promise chain version of the WD.js API. Defaults to false (the callback version).
A passthrough to the Phantom CLI runner to ignore errors with SSL certs.
An array of paths for requiring before running Mocha tests. Useful for pre-requires that manipulate Mocha's global environment (e.g.g making Sinon globally available).
The Sauce Labs username to use. Defaults to value of env var
The Sauce Labs API key to use. Defaults to value of env var
Type: Boolean (Default: false)
If true, it will use saucelabs, with default
hostname set to
port set to
in order to send selenium commands through Sauce Connect tunnel (more info
If specified, it will connect that selenium server instead of
Selenium server port. Should be used in conjonction with
A Unique identifier for the generated tunnel to Sauce Labs. Will be automatically generated if not specified. Useful for connected to existing Sauce tunnels.
The number of concurrent browser sessions to spin up on Sauce Labs. Defaults to 1.
Type: Array An array of option flags for Sauce Connect. See the list of available options here.
The name of the test, as reported to Sauce Labs.
An array of tags to associate with the test, as reported to Sauce Labs.
An array of objects specifying which browser options should be passed to Sauce Labs.
Unless a test is run against Phantom (e.g.
usePhantom is true), this option
must be specified. Each browser hash should specify:
browserName. For saucelabs tests,
version are also required.
In lieu of a formal styleguide, take care to maintain the existing coding style. Add
unit tests for any new or changed functionality. Lint and test your code using
- Initial release
- Setup Travis for CI
- Improve SauceLabs test failure handling
- Test count was off by 1
- Update docs
- Add initial promise support (Phantom only)
- Enable Promise support (Phantom and SauceLabs)
- Run phantom from grunt-mocha-webdriver directly
requireoption for pre-require hook
- PhantomJS integration failed to report the correct status code when exiting Grunt after tests failed.
- Prevent errors from causing Phantom to exit early
- Better error messages via wd.js
ignoreSslErrorsoption added as a phantom CLI passthrough
- Update wd.js to 0.2.0, and switch to the new
- Fix #8, async failures were causing grunt exit
- Bump to latst sauce-tunnel
- Bump to 0.2.3 of WD, and expose the wd instance to tests
- Bump to 1.15.1 of Mocha, and expose mocha options to tests
- Add Selenium support (thanks to @saadtazi)
tunnelFlagsoptions, courtesy of @saadtazi
Copyright (c) 2013 Justin Reidy
Licensed under the MIT license.