Mocha Test Framework

Common errors

• Timeout of 2000ms exceeded. For async tests and hooks, ensure "done()" is called or a Promise is returned.

  cause An asynchronous test or hook executed longer than the default 2-second timeout.
  fix Increase the timeout for the test/suite using `this.timeout(5000)` or globally with `mocha --timeout 5000`. Ensure asynchronous operations return a Promise or call `done()`.

• Error: No tests found

  cause Mocha could not find any test files matching the configured patterns or paths.
  fix Double-check the test file paths and glob patterns specified in your `mocha` command or configuration file. Ensure files exist and are correctly named.

• ReferenceError: describe is not defined

  cause The test file is being run outside the Mocha test runner, or Mocha's global test functions are not exposed.
  fix Execute your test file using the `mocha` command (e.g., `npx mocha my-test.js`). Ensure Mocha is installed and correctly configured to expose globals.

• TypeError: Cannot read properties of undefined (reading 'timeout')

  cause Attempted to use `this.timeout()` or other Mocha context methods within an arrow function, which does not correctly bind `this`.
  fix Change the arrow function to a traditional `function` declaration: `it('...', function() { this.timeout(5000); /* ... */ });`.

• Mocha exited with code 1

  cause A general failure occurred, often due to a test failure, uncaught exception, unhandled promise rejection, or a critical configuration error.
  fix Review the console output immediately preceding the exit code for more specific error messages. Use `mocha --full-trace` for detailed stack traces to pinpoint the issue.

Warnings

• gotcha Mocha tests have a default timeout of 2000ms. Asynchronous tests or complex operations exceeding this can lead to 'Timeout of 2000ms exceeded' errors, especially in CI environments or slower machines.
  Fix: Increase the timeout for individual tests or suites using `this.timeout(5000)` (inside a regular function, not an arrow function) or globally via the CLI (`mocha --timeout 5000`).
• gotcha Using arrow functions for Mocha hooks (`before`, `afterEach`, `it`, etc.) prevents access to the Mocha context (`this`), which is necessary for methods like `this.timeout()`, `this.retries()`, or `this.skip()`. Arrow functions do not bind their own `this` context.
  Fix: Use traditional `function` declarations for hooks and tests that require access to the Mocha context (e.g., `before(function() { this.timeout(5000); })`).
• breaking Mocha v12 (currently in beta) introduces robust ESM support, including direct `.mjs` exports and ESM configuration files. Projects relying on CommonJS modules might require configuration adjustments and code changes when upgrading to v12.
  Fix: Review the Mocha v12 release notes and documentation for guidance on migrating existing CommonJS setups to ESM, including `package.json` type field and file extensions.
• gotcha If Mocha reports 'No tests found' and exits with an error, it often indicates an issue with the specified test file paths or glob patterns in the CLI command or configuration. It can also happen if test files are not accessible or contain syntax errors preventing their loading.
  Fix: Verify the glob pattern (e.g., `mocha 'test/**/*.test.ts'`). Ensure test files are correctly named and located in the specified directories. Use `--recursive` if tests are in subdirectories.

Install

• npm install mocha npm
• yarn add mocha yarn
• pnpm add mocha pnpm

Imports

• describe

  import { describe } from 'mocha';

  When running tests via the Mocha CLI, `describe`, `it`, and other test functions are typically made available as globals. Explicit imports are useful for ESM environments or improved static analysis.

Quickstart

This quickstart demonstrates a basic Mocha test suite using `describe` and `it` with the Chai assertion library. To run, save this code as `test.ts`, install dependencies (`npm install mocha chai ts-node`), and execute with `npx mocha --require ts-node/register test.ts`.

import { describe, it } from 'mocha';
import { expect } from 'chai';

describe('Array', () => {
  it('should return -1 when the value is not present', () => {
    expect([1, 2, 3].indexOf(4)).to.equal(-1);
  });

  it('should return the correct index when present', () => {
    expect([1, 2, 3].indexOf(2)).to.equal(1);
  });
});