Mocha — Global Setup and Teardown (before/after)

Mocha is a powerful testing framework for Node.js. It gives you dozens of helpful utilities to create a convenient testing setup.

Mocha also provides an interceptable testing lifecycle. If you need to run setup and teardown tasks for your test suite, make sure to read on!

Testing Setup Before Starting Your Test Suite

Creating a solid test suite for your application may require one or more setup steps before running the tests.

Mocha offer two ways for this:

  1. global hooks
  2. root-level hooks in single test files that run before tests or beforeEach individual test

Global Setup

A global setup hook may run before any of your tests. The global hook requires one or more setup files. If you need setup steps that rely on each other, you can tell Mocha to import them sequentially and process in the expected order.

Imagine that you need to ensure existing database tables. The following example uses Elasticsearch indices and uses a global hook to ensure existing indices when running the tests.

To create missing indices in a global setup, you need to create a before function in one of your setup files. This example uses the test-setup-elastic.js file.


before(async () => {  
  await Elastic.ensureIndices()

Mocha will pick up and process this before function when running the test suite. You can also use beforeEach, after, or afterEach here. We’ll look at the after hooks in the teardown section below.

The next step is to tell Mocha where to find the file. Use the --file argument when calling Mocha via NPM scripts or use a mocha.opts file. A mocha.opts file contains Mocha’s configuration while running your test suite.

Here’s the content of your mocha.opts file that references the Elasticsearch setup file.


--file ./test/setup-elastic.js
--file ./test/another-setup-that-runs-after-elastic.js

Each --file argument references a single file. Add more references when needed and Mocha will process them in the defined order.

Per Test File Setup

For individual setups that should run before any test in a selected file, you can use the root-level pre-hooks. These root-level hooks live outside your describe method.


before(async () => {  
  await Special.setupForThisFile()

describe('descriptive group title', () => {  
  it('test title', …)

Mocha notices the methods outside the describe block and processes them when running the tests in this file.

Testing Teardown

Related to a global setup, Mocha provides the same approach for teardowns. Like the testing setup, you have two options for the teardown:

  1. a global hook
  2. root-level hooks in single test files that run after tests or afterEach individual test

Here’s an example of a global after hook that runs once after the whole test suite was processed.


after(async () => {  
  await Users.deleteAll()

A root-level hook is part of a single test file and lives outside the first describe block:


after(async () => {  
  await Special.testingTeardown()

describe('descriptive title', () => { … })  

Tell Mocha to pick up your testing teardown file via the --file argument.

Remember that Mocha processes all referenced --file imports in the defined order. Ensure the correct execution plan if you have more than one teardown steps.


--file ./test/teardown.js
--file ./test/teardown-that-runs-second.js

Mocha Arguments or Mocha.Opts

Mocha offers two options to reference the setup and teardown files. You can add them as arguments in your NPM scripts or in your mocha.opts file.

Here’s an example when adding the files to your test script in NPM’s package.json file:

"scripts": {
  "test": "mocha --file ./test/setup-elastic.js --file ./test/setup-after-elastic.js --file ./test/teardown.js",

We recommend using the mocha.opts file to avoid duplications when having NPM scripts that reference Mocha. The npm test command may become long when adding more flags.

Here’s an example when using the mocha.opts file with the same flags as the NPM script:

--file ./test/setup-elastic.js
--file ./test/teardown.js
--file ./test/teardown-that-runs-second.js

Enjoy testing with Mocha!

Mentioned Resources

Explore the Library

Find interesting tutorials and solutions for your problems.