Home

Awesome

Mochify

TDD with Browserify, Mocha, Headless Chrome and WebDriver

Build SemVer License

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.

Features

Install

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.

Usage

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

Debugging

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.

Command line options

Continuous Integration

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

Selenium WebDriver setup

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"]
      }
    }
  }]
}

SauceLabs setup

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.

Appium setup

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):

{
  "hostname": "localhost",
  "port": 4723,
  "browsers": [{
    "name": "Safari",
    "platformName": "iOS",
    "platformVersion": "11.2",
    "deviceName": "iPhone Simulator"
  }]
}

It's important to use --async-polling false here. The default asynchronous polling does not work with this setup.

BrowserStack 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
    }
  }]
}

Reporters

Mocha reporters known to work:

Note: Consuming the output of a machine readable reporter may not work as expected with --wd.

API

var mochify = require('mochify');

mochify('./test/*.js', {
  reporter: 'tap'
}).bundle();

All 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:

The mochify function returns a Browserify instance. Please refer to the Browserify API for details.

Code coverage with NYC

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 ] ]"
  }
}

Workaround for Apple Silicon

Puppeteer fails to launch on M1. Follow these steps to work around:

Compatibility

License

MIT