TDD with Browserify, Mocha, Headless Chrome and WebDriver
Browserifies ./test/*.js
, decorated with a Mocha test runner, runs it in
Headless Chrome and passes the output back to your console. Cleans up your
stack traces by mapping back to the original sources and removing lines from
the test framework.
This will install Mochify in your current project and add it to the
devDependencies
:
npm install mochify --save-dev
Puppeteer will download a recent version of Chromium. If you want to skip
the download and provide your own executable instead, define the
PUPPETEER_SKIP_CHROMIUM_DOWNLOAD
environment variable or add this to your
package.json
:
{
"config": {
"puppeteer_skip_chromium_download": true
}
}
For proxy settings and other environment variables, see the Puppeteer documentation.
Configure "scripts"
in your package.json
so that your project ships with
the testing infrastructure:
{
"scripts": {
"test": "mochify",
"watch": "mochify --watch",
"webdriver": "mochify --wd"
}
}
To run from the command line, either run npm install mochify -g
to have
mochify
available globally, or from within your project directory run:
node_modules/.bin/mochify
Place a debugger
statement in your source code and run mochify --debug
.
This will open a Chromium instance with developer tools opened and it will
break at the debugger
statement.
--watch
or -w
use watchify to watch your files and run the tests on
change.--reporter
or -R
changes the Mocha reporter (see further down).--grep
sets the Mocha grep option.--invert
sets the Mocha grep invert
flag.--recursive
include sub directories.--ui
or -U
changes the Mocha UI. Defaults to 'bdd'
.--timeout
or -t
changes the Mocha timeout. Defaults to 2000
.--colors
explicitly enables color output.--no-colors
explicitly disables color output.--outfile
or -o
writes output to this file. If unspecified, mochify
prints to stdout.--require
or -r
requires the given module.--debug
launches a non-headless chromium instance with developer tools.--chrome
uses a specific Chrome executable. If not specified, the built-in
chromium is used.--ignore-ssl-errors
tells Chrome whether or not to ignore ssl certificate
issues (default is false)--allow-chrome-as-root
allows Chrome to run as root--dumpio
passed to puppeteer to dump all IO--https-server
launches an HTTPS server on the specified port. If no port is given a random available port will be used.--viewport-width
tells Chrome to use a certain width for its viewport.--viewport-height
tells Chrome to use a certain height for its viewport.--cover
checks code coverage with coverify.--node
creates a bare bundle and runs test cases on node.--wd
use min-webdriver to run the tests in multiple real browsers.--url
runs the tests in the context of the given URL.--wd-file
(only with --wd
) specify the location of the .min-wd
config file.--consolify output.html
generate a standalone HTML page with consolify.--bundle
specify a separate JS file export when using --consolify
.--transform
specifies a Browserify transform to add. Can be specified
multiple times. Options can be passed with subargs.--global-transform
specifies a Browserify transform to add globally. Can be
specified multiple times. Options can be passed with subargs.--plugin
specifies a Browserify plugin to add. Can be specified multiple
times. Options can be passed with subargs.--extension
search for files with the extension in "require" statements.--no-browser-field
turns off package.json browser field resolution.--no-commondir
preserve original paths.--external
marks given path or module as external resource and
prevent from being loaded into the bundle.--yields
or -y
changes the yield interval to allow pending I/O to happen.--version
or -v
shows the Mochify version number.--help
or -h
shows usage and all available options.--async-polling
disables async polling when set to false (for use in Appium).--mocha-path
specifies path to a custom Mocha module--web-security
allows disabling same-origin policy (when set to false
, passes down --disable-web-security
to Chromium)To run builds in CI services like Travis or CircleCI, you must pass --allow-chrome-as-root
.
Here is a minimal .travis.yml
:
language: node_js
node_js:
- "16"
sudo: false
script:
- npm test -- --allow-chrome-as-root
java -jar selenium-server-standalone-2.39.0.jar
Create .min-wd
in your project root:
{
"hostname": "localhost",
"port": 4444,
"browsers": [{
"name": "internet explorer",
"version": "11"
}, {
"name": "chrome"
}, {
"name": "firefox"
}]
}
That's it! Now mochify --wd
will run your Mocha test cases in the configured
browsers simultaneously. If you installed mochify without -g
, you will have
to run node_modules/.bin/mochify --wd
.
Additional Selenium capabilities and browser-specific capabilities can be
specified with the capabilities
property:
{
"hostname": "localhost",
"port": 4444,
"browsers": [{
"name": "chrome",
"capabilities": {
"chromeOptions": {
"args": ["--headless", "--disable-gpu"]
}
}
}]
}
Export your SauceLabs credentials:
export SAUCE_USERNAME="your-user-name"
export SAUCE_ACCESS_KEY="your-access-key"
Enable SauceLabs in your .min-wd
file or in the "webdriver"
property in
your package.json
:
{
"sauceLabs": true
}
For more information about Selenium WebDriver and SourceLabs support can be found on the min-webdriver project page.
Note: This has only be tested on Mac OS X High Sierra with the iOS Simulator so far. If you have successfully tested with other configurations, please file an issue so that we can extend the docs.
Setup for iOS Simulator on Mac OS X (requires XCode):
npm install -g appium
brew install carthage
.min-wd
file or the "webdriver"
property in your
package.json
like this:{
"hostname": "localhost",
"port": 4723,
"browsers": [{
"name": "Safari",
"platformName": "iOS",
"platformVersion": "11.2",
"deviceName": "iPhone Simulator"
}]
}
appium --log-level error
which should start a server on port 4723
mochify --wd --async-polling false
It's important to use --async-polling false
here. The default asynchronous
polling does not work with this setup.
Export your BrowserStack credentials:
export BROWSERSTACK_USERNAME="your-user-name"
export BROWSERSTACK_ACCESS_KEY="your-access-key"
Example .min-wd
file:
module.exports = {
"hostname": "hub-cloud.browserstack.com",
"port": 80,
"browsers": [{
"name": "chrome",
"capabilities": {
"browser": "Chrome",
"browserstack.user": process.env.BROWSERSTACK_USERNAME,
"browserstack.key": process.env.BROWSERSTACK_ACCESS_KEY
}
}]
}
Mocha reporters known to work:
Note: Consuming the output of a machine readable reporter may not work as
expected with --wd
.
var mochify = require('mochify');
mochify('./test/*.js', {
reporter: 'tap'
}).bundle();
mochify()
uses default settings and runs tests in ./test/*.js
mochify(paths)
specifies the paths, a space delimited list of globsmochify(opts)
configures options as described belowmochify(paths, opts)
combines custom paths and optionsAll long form command line options can be used. E.g. --node
can be configured
as { node : true }
, --no-browser-field
as { 'browser-field': false }
,
--reporter tab
as { reporter : 'tab' }
and so on.
Additional API options:
output
a stream that receives the test output (e.g. through2)glob
options to pass to globreporterOptions
options to pass to mocha reporterThe mochify
function returns a Browserify instance. Please refer to the
Browserify API for details.
Install nyc
, the babelify
transform,
@babel/core
and babel-plugin-istanbul
:
$ npm install nyc babelify @babel/core babel-plugin-istanbul --save-dev
Using a package.json
script that can be run with npm run cover
:
{
"scripts" : {
"cover" : "nyc --instrument false mochify --transform [ babelify --ignore [ test ] --plugins [ babel-plugin-istanbul ] ]"
}
}
Puppeteer fails to launch on M1. Follow these steps to work around:
Define these environment variables:
export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
export PUPPETEER_EXECUTABLE_PATH=/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
MIT