Wondering what’s next for npm?Check out our public roadmap! »

    TypeScript icon, indicating that this package has built-in type declarations

    3.1.0 • 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 10.18.1+ 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)
    • -p, --polling - Puppeteer polling mechanism
    • -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
        polling: 'raf',                              // polling mechanism
        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






    Unpacked Size

    19.2 kB

    Total Files


    Last publish


    • avatar