Skip to content
Get packs

Guide · Open source

How to use Mocha: install, write and run JavaScript tests

Updated · written with AI from the project's own documentation and checked against our catalogue data

Mocha is a testing framework for JavaScript. You write test files, Mocha runs them and reports which checks pass or fail, and it works on both Node.js and in web browsers. This guide is for developers who want automated tests for their JavaScript code. By the end you will know how to install Mocha as a dev dependency, where its prerequisites come from, and what its role is compared with other tools.

Mochamochajs/mocha · ★ 22.9k · MIT

Quick start

  1. 1Install Node.js. Install Node.js, which Mocha requires. Confirm it is available in your terminal before continuing.
  2. 2Open your project folder. Move into the JavaScript project where you want to add tests.
  3. 3Install Mocha. Run npm install --save-dev mocha to add Mocha as a dev dependency.
  4. 4Write test files. Create test files for the code you want to check, following the usage in the Mocha documentation.
  5. 5Run the tests. Run Mocha on your test files and read which checks pass or fail.
  6. 6Check the documentation. Visit https://mochajs.org for full usage, including browser setup.

What you need before you install Mocha

The main prerequisite for Mocha is Node.js. Install Node.js first, then add Mocha to your project with npm.

Mocha is a test runner, not a full toolkit. The README presents it as a runner and does not describe built-in assertions or mocking, so you choose your own assertion library and other tools.

  • Node.js installed on your machine
  • A JavaScript project where you want tests
  • Your choice of assertion library, if you want one

Install Mocha as a dev dependency

Mocha is installed with npm as a development dependency, so it is used for testing and not shipped as part of your application's runtime code. Run the command from your project folder.

npm install --save-dev mocha

Run your tests and read the results

Once you have test files, Mocha runs them and reports which checks pass or fail. The README on this page does not show the full set of run commands or test file layout, so check the documentation at https://mochajs.org for the exact usage, including how to write tests and where Mocha looks for test files by default.

  • Mocha reports which checks pass or fail after each run
  • Documentation with full usage: https://mochajs.org

Use Mocha in the browser

Mocha is not limited to Node.js. The project describes itself as a test framework for Node.js and the browser, which makes it useful for teams maintaining browser-based JavaScript that needs tests run in a real browser. Browser setup details are in the documentation rather than the README.

Choose Mocha or another test runner

Mocha is a long-established, widely used runner. The README says it is one of the most-depended-upon modules on npm and is maintained by volunteers under the OpenJS Foundation. If you want a runner with bundled assertions and mocking, Mocha is not that tool, and you may prefer a comparable project such as Jest, Vitest, Jasmine or Ava.

  • Pick Mocha if you want a classic runner and to choose your own assertion library
  • Pick an all-in-one tool if you want assertions and mocking built in

What people use it for

  • Automated tests for Node.js code in a JavaScript project
  • Running tests for browser-based JavaScript in a real browser
  • Maintaining a long-lived project that needs a widely used test runner
  • Pairing a runner with your own choice of assertion library

Frequently asked questions

Is Mocha free to use?

Yes. Mocha is licensed under the MIT licence, as stated in the README. Copyright is held by the OpenJS Foundation and contributors.

What do I need to install Mocha?

The README lists Node.js as the prerequisite. Install it, then add Mocha to your project with npm install --save-dev mocha.

How do I install Mocha?

Run npm install --save-dev mocha from your project folder. This adds Mocha as a dev dependency using npm.

Does Mocha work in the browser?

The README says Mocha is a test framework for Node.js and the browser. Browser setup details are in the documentation at https://mochajs.org.

Does Mocha include assertions and mocking?

The README presents Mocha as a runner and does not describe bundled assertions or mocking. You pick your own assertion library and other tools.

What are alternatives to Mocha?

Comparable projects listed for this item are Jest, Vitest, Jasmine and Ava. Jest and Vitest are closer to all-in-one options, while Mocha is a runner you combine with your own tools.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Mocha suits JavaScript and Node.js developers who want a classic, widely trusted test runner, including teams testing code in the browser, and who are happy to choose their own assertion library. If you want built-in assertions and mocking, or you are not yet comfortable writing code, consider an all-in-one tool such as Jest or Vitest instead.

Install options & downloads