mocha

library0.12.1jsnpmunverified

Mocha is a highly flexible and feature-rich JavaScript test framework designed for both Node.js environments and browsers. It facilitates writing and running tests with support for various styles, including Behavior Driven Development (BDD) and Test Driven Development (TDD). The current stable version is 11.7.5, with frequent beta releases for version 12 indicating active development. Mocha differentiates itself by being unopinionated about the assertion library, allowing developers to choose their preferred tools (e.g., Chai, Node's built-in `assert`). It provides robust capabilities for asynchronous testing, hooks for setup/teardown, and comprehensive reporting, making it a popular choice for defining test suites and individual test cases.

testing

npm install mocha

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MOCHA

mocha

testingjavascriptv0.12.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

describe, it, beforeEach, afterEach

✓ // No import needed, these are global by default in Mocha tests. // For TypeScript, install @types/mocha and configure tsconfig for 'types'.

✗ import { describe, it } from 'mocha';

Mocha injects these functions into the global scope when running tests. Explicit imports are not typically required for writing test files unless using a specific TypeScript configuration or linter that enforces it. Installing `@types/mocha` is crucial for TypeScript users to get correct type definitions.

Mocha (programmatic API)

✓ import Mocha from 'mocha'; // or const Mocha = require('mocha');

For programmatic use, Mocha can be imported as a default export in ESM or required in CommonJS. This is typically used when building custom test runners or integrating Mocha into build systems.

ES Module test files (e.g., .mjs or with `"type": "module"`)

✓ // In package.json: { "type": "module" } import { myFunction } from './myModule.js'; describe('ESM Test', () => { it('should run an ES module test', () => { // ... }); });

✗ const { myFunction } = require('./myModule');

Since v8, Mocha supports ES modules natively. Test files can use `.mjs` extension or have `"type": "module"` in `package.json`. Mixing `require()` and `import` in the same file for test code can lead to `ERR_REQUIRE_ESM` errors in newer Node.js versions.

This quickstart demonstrates how to set up a basic Mocha test file using TypeScript and Chai for assertions. It includes synchronous and asynchronous test examples with `describe` and `it` blocks, illustrating common testing patterns.

import { expect } from 'chai'; // A simple utility function to test function add(a: number, b: number): number { return a + b; } function subtract(a: number, b: number): number { return a - b; } describe('Math Operations', () => { it('should correctly add two numbers', () => { expect(add(2, 3)).to.equal(5); expect(add(-1, 1)).to.equal(0); }); it('should correctly subtract two numbers', () => { expect(subtract(5, 2)).to.equal(3); expect(subtract(10, 20)).to.equal(-10); }); it('should handle zero correctly in addition', () => { expect(add(0, 7)).to.equal(7); }); // Demonstrate an asynchronous test using Promises it('should eventually return a value after a delay', async () => { const delayedAdd = (a: number, b: number, delay: number) => { return new Promise<number>((resolve) => { setTimeout(() => resolve(a + b), delay); }); }; const result = await delayedAdd(1, 1, 50); expect(result).to.equal(2); }).timeout(100); // Set a specific timeout for this async test });

mocha --version

Debug

Known issues

breakingMocha v12 will raise the minimum Node.js version requirement to `^20.19.0 || >=22.12.0`. This means older Node.js versions (e.g., 18.x) will no longer be supported, primarily to enable unflagged `require(ESM)` support and update internal dependencies.

fix

Upgrade your Node.js environment to version 20.19.0 or newer, or version 22.12.0 or newer, before upgrading to Mocha v12.

affects: >=12.0.0-beta

breakingMocha v9.0.0 introduced 'ESM-first' loading of test files, meaning it attempts `import()` before `require()`. While it includes a fallback, reliance on CommonJS-specific patterns (like `require`ing an ES Module) can lead to issues. Custom reporters and interfaces currently must be CommonJS files.

fix

Migrate test files and any test-related utility modules to ES module syntax (`import`/`export`) or ensure they are correctly configured for CommonJS (`.cjs` extension or no `"type": "module"` in `package.json`). For mixed environments, understand Node.js's module resolution rules, possibly using dynamic `import()` for ESM from CJS.

affects: >=9.0.0

gotchaWhen writing asynchronous tests, either return a Promise or call the `done()` callback. Doing both, or forgetting to do either, will lead to unexpected behavior or test timeouts. Since Mocha v3.0.0, returning a Promise and calling `done()` throws an exception.

fix

For promise-based async tests, return the Promise. For callback-based async tests, ensure `done()` is called exactly once when the asynchronous operation completes (or with an error). Do not mix these patterns.

affects: >=3.0.0

breakingMocha v10 dropped support for Node.js v12.x and Internet Explorer 11. It also removed AMD/RequireJS support and renamed the executable from `bin/mocha` to `bin/mocha.js`.

fix

Ensure your environment meets the updated Node.js requirements. For older browser testing, use an earlier Mocha version. Update any scripts or tooling that directly invoke `bin/mocha` to `bin/mocha.js`.

affects: >=10.0.0

gotchaThe `describe`, `it`, `beforeEach`, etc., functions are globally available in Mocha test files by default. If using TypeScript, you need to install `@types/mocha` to provide global type definitions. Without it, your IDE or TypeScript compiler will report `ReferenceError: describe is not defined` or similar type errors.

fix

For TypeScript projects, run `npm install --save-dev @types/mocha`. Ensure your `tsconfig.json` includes `@types/mocha` in the `types` array or `compilerOptions.typeRoots`.

affects: all

Errors

Common errors & fixes

ReferenceError: describe is not defined

Mocha's test runner was not used to execute the test file, or `@types/mocha` is missing in a TypeScript project.

fix

Run your tests using the `mocha` command (e.g., `mocha your-test-file.js`) instead of `node your-test-file.js`. For TypeScript, ensure `@types/mocha` is installed and properly configured in `tsconfig.json`.

Mocha timeout of 2000ms exceeded.

An asynchronous test or hook took longer than the default 2-second timeout, or was not properly signaled as complete (e.g., `done()` not called, Promise not resolved).

fix

Increase the timeout for the specific test (`it('...', function() { ... }).timeout(5000);`) or the entire suite (`this.timeout(5000);`). Ensure all asynchronous operations correctly complete by calling `done()` or resolving/rejecting the returned Promise.

Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.

A CommonJS module (`.js` without `"type": "module"` or `.cjs`) attempted to `require()` an ES Module (`.mjs` or `.js` with `"type": "module"`).

fix

Ensure consistent module types. If using ESM, adopt `import` statements. If using CJS, stick to `require()` or use dynamic `import()` for ESM dependencies. Consider renaming `.js` files that are ESM to `.mjs` or setting `"type": "module"` in `package.json` for ESM projects.

TypeError: describe is not a function

This error often occurs when an incorrect test interface is configured (e.g., using BDD syntax `describe` with the TDD interface `mocha --ui tdd`), or when Mocha's globals are not correctly exposed.

fix

Ensure you are using the correct test interface for your syntax. If you're using `describe`/`it`, use the default BDD interface or explicitly specify `mocha --ui bdd`. Check your Mocha configuration files (`.mocharc.js`, `package.json`) for conflicting `ui` settings.

Upgrade

Version history

0.12.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/mochajs/mocha ↗

packagehttps://www.npmjs.com/package/mocha ↗

homepagehttps://mochajs.org ↗