Using Mocha programmatically

There are a lot of reasons why you might want to automate running the tests using Mocha. Using the command-line can run into some problems if you want to load specific files, for example.

Here is an example of using Mocha programmatically:

var Mocha = require('mocha'),
    fs = require('fs'),
    path = require('path');

// Instantiate a Mocha instance.
var mocha = new Mocha();

var testDir = 'some/dir/test'

// Add each .js file to the mocha instance
fs.readdirSync(testDir).filter(function(file) {
    // Only keep the .js files
    return file.substr(-3) === '.js';

}).forEach(function(file) {
    mocha.addFile(
        path.join(testDir, file)
    );
});

// Run the tests.
mocha.run(function(failures) {
  process.exitCode = failures ? 1 : 0;  // exit with non-zero status if there were failures
});

mocha.run() returns a Runner instance which emits many events of interest.

Note that run (via loadFiles, which it calls) relies on Node's require to execute the test interface functions. Thus, files loaded by Mocha will be stored in Node's require cache and therefore tests in these files will not be re-run if mocha.run() is called again. If you want to run tests multiple times, you may need to clear Node's require cache before subsequent calls in whichever manner best suits your needs. The upcoming Mocha-6.0 release will provide Mocha#unloadFiles, which will remove all files loaded by Mocha#loadFiles.

Unfortunately, event listeners in multiple places are not yet configured for restartability; for now, we recommend recreating the mocha instance before rerunning to ensure everything gets reset properly.

Find a fully working example here.

Set options

There are two ways to set the options to run the tests.

Firstly, you can set these options in the constructor object:

var mocha = new Mocha({
    ui: 'tdd',
    reporter: 'list'
});

Please check our API documentation for a complete list of these options.

Secondly, on the mocha object, there are some chainable methods allowing you to change some more options.

Here is an example:

// Change the reporter to "list" before running the tests
mocha.reporter('list').run();

// Change the UI to "tdd" before running the tests
mocha.ui('tdd').run();

// Or do both changes before running the tests
mocha.reporter('list').ui('tdd').run();

Please check our API documentation for more information.