Mocha

Mocha is a flexible JavaScript test framework. Unlike Jest, it does not come with an assertion library, mocking, or snapshotting built-in. It is a runner that allows you to choose your own tools (usually Chai + Sinon).

When to Use

• Flexible Node.js & Browser Testing: A customizable test runner providing BDD (describe/it) and TDD test interfaces.
• Customizable Assertion & Mocking Pairs: Pairing with preferred assertion libraries (Chai) and mocking toolkits (Sinon.js).
• Asynchronous Execution Control: Testing callbacks, promises, and async/await with granular timeout controls.
• Established Node.js Codebases: Maintaining and extending mature enterprise backend JavaScript services.

Quick Start

// npm install --save-dev mocha chai
const assert = require("chai").assert;

describe("Array", function () {
  describe("#indexOf()", function () {
    it("should return -1 when the value is not present", function () {
      assert.equal([1, 2, 3].indexOf(4), -1);
    });
  });
});

Core Concepts

BDD Interface & Hooks Lifecycle

Coordinates test execution and lifecycle fixtures cleanly:

import { expect } from "chai";

describe("Payment Gateway Service", () => {
  before(async () => {
    // Run once before all tests in this block (e.g. connect to DB)
  });

  beforeEach(() => {
    // Run before each test (e.g. reset state)
  });

  it("successfully processes valid card charge", async () => {
    const receipt = await processCharge(100);
    expect(receipt.status).to.equal("SUCCESS");
  });

  after(() => {
    // Run once after all tests (e.g. close connection)
  });
});

Granular Timeout & Retry Configuration

Controls timeouts for slow network or integration operations:

it("completes slow third-party reconciliation", function (done) {
  this.timeout(5000); // Override default 2000ms timeout
  this.retries(2); // Retry up to 2 times on intermittent failure

  reconcileLedgers()
    .then(() => done())
    .catch(done);
});

Declarative .mocharc.json Configuration

{
  "extension": ["ts"],
  "spec": "tests/**/*.spec.ts",
  "require": "ts-node/register",
  "timeout": 4000,
  "reporter": "spec"
}

Common Patterns

Test Fixture Hooks with Cleanup

Problem: Leaked database state across test suites causes cascading false-positive failures.

Solution: Use before, beforeEach, and afterEach lifecycle hooks:

describe("Order Processing Service", () => {
  let dbConnection;

  before(async () => {
    dbConnection = await createTestDatabase();
  });

  after(async () => {
    await dbConnection.close();
  });

  beforeEach(async () => {
    await dbConnection.truncateAll();
  });

  it("creates an order successfully", async () => {
    const order = await createOrder({ item: "book" });
    assert.strictEqual(order.status, "CONFIRMED");
  });
});

Best Practices

Do:

• Use Regular Functions When Accessing this.timeout(): Arrow functions bind lexical context and break Mocha's this context binding.
• Commit a .mocharc.json Config: Centralize timeout, reporter, and file patterns in a committed configuration file.
• Use Parallel Test Execution: Enable --parallel in .mocharc.json on multi-core CI runners to accelerate test runs.
• Pair with Sinon for Stubs: Use sinon.stub() and sinon.spy() for isolated unit test dependencies.

Don't:

• Mix callback done() and async/await: Mixing both causes multiple callback invocation errors.
• Leave .only() committed: Use ESLint rules (no-exclusive-tests) to prevent committed .only blocks from skipping test suites.
• Rely on arbitrary static delays: Use explicit polling helpers rather than setTimeout delays.

Troubleshooting

| Error | Cause | Solution | | :------------------------------------ | :-------------------------------------------------------------------- | :----------------------------------------------------------------------------- | | Error: Timeout of 2000ms exceeded | Asynchronous test did not complete within default 2-second timeout. | Increase timeout using this.timeout(5000) or pass --timeout 5000 CLI flag. | | Error: done() called multiple times | Callback-style test invoked done() both in success and error paths. | Return a Promise instead of using the done callback. | | TypeError: describe is not defined | Executing test file with node instead of npx mocha. | Run using npx mocha path/to/test.js. |

References

• Mocha Documentation