---
description: Using Mocha programmatically
title: Programmatic usage
---

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:

```javascript
import Mocha from "mocha";
import fs from "node:fs";
import path from "node:path";

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

const 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.endsWith(".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](https://github.com/mochajs/mocha/blob/main/lib/runner.cjs) of interest, exposed as `Mocha.Runner.constants` (e.g. `EVENT_TEST_PASS`, `EVENT_TEST_FAIL`, `EVENT_RUN_END`).

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. `Mocha#unloadFiles` is also available and 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](https://github.com/mochajs/mocha-examples/tree/main/packages/programmatic-usage).

## Set options

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

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

```javascript
const mocha = new Mocha({
  ui: "tdd",
  reporter: "list",
});
```

Please check our [API documentation](https://mochajs.org/api/mocha) 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:

```javascript
// 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](https://mochajs.org/api/mocha) for more information.
