Need private packages and team management tools?Check out npm Orgs. »


2.0.3 • Public • Published


npm license dependency status dev dependency status

This is the tool which runs client-side mocha tests in the command line through headless Chrome (puppeteer is used).

Node 6.4.0+ and Mocha 2.3.0+ are supported.

Getting Started

First you need to install mocha-headless-chrome:

npm i mocha-headless-chrome

Then prepare the test page (see the example).

Note. It is necessary to add the <meta charset="utf-8"> tag. Otherwise browser may use another encoding and test results will be shown incorrectly.

Then run the CLI and specify your test page path using -f parameter.

mocha-headless-chrome -f test-page.html


  • -f, --file - Path or URL of the page which contains tests (required)
  • -r, --reporter - Mocha reporter name (defaults to "spec")
  • -o, --out - Path to the file where test result will be saved
  • -c, --coverage - Path to the file where coverage info will be saved
  • -e, --executablePath - Chrome executable path
  • -v, --visible - Show Chrome window
  • -a, --args - Chrome arguments ('--' prefix will be added)
  • -w, --width - Viewport width
  • -H, --height - Viewport height
  • -t, --timeout - Timeout in ms (defaults to 60000)
  • -h, --help - Output usage information


Run test on the "test.html" page:

$ mocha-headless-chrome -f test.html

Run tests on the remote page:

$ mocha-headless-chrome -f http://localhost:8080

Output test results using "nyan" reporter:

$ mocha-headless-chrome -f test.html -r nyan

Pass the Chrome --no-sandbox and --disable-setuid-sandbox arguments:

$ mocha-headless-chrome -f test.html -a no-sandbox -a disable-setuid-sandbox

Mocha reporters

All mocha reporters are supported. Specify the reporter name through -r parameter. All reporter output (include cursor manipulations) will be redirected to stdout as like it works in console.

For usage of third-party reporter just include it's code to the page by <script> tag and specify it's name in the -r parameter.

Also special reporter named "none" is available which does not output anything. This reporter will be useful when you want to process test result without output to console (for example, when saving data to a file).

Programmatically usage

You can use mocha-headless-chrome programmatically. Just require the mocha-headless-chrome node module and pass proper parameters into it. Function result is a Promise.

const {runner} = require('mocha-headless-chrome');
const options = {
    file: 'test.html',                           // test page path
    reporter: 'dot',                             // mocha reporter name
    width: 800,                                  // viewport width
    height: 600,                                 // viewport height
    timeout: 120000,                             // timeout in ms
    executablePath: '/usr/bin/chrome-unstable',  // chrome executable path
    visible: true,                               // show chrome window
    args: ['no-sandbox']                         // chrome arguments
    .then(result => {
        let json = JSON.stringify(result);

See also the TypeScript example.


npm i mocha-headless-chrome

Downloadsweekly downloads









last publish


  • avatar
Report a vulnerability