Mocha Test Framework

Mocha is a unopinionated, general-purpose testing framework for the JavaScript community. It is designed to be flexible and stable, focusing on providing a robust foundation for organizing and running tests rather than providing specific assertion or mocking logic.

Core Capabilities (In-Scope)

• Test APIs: Interfaces for writing and organizing tests in JavaScript or compile-to-JavaScript languages.
• Execution Environments: A command-line interface (CLI) for Node.js-based terminals and an API for running tests in browser environments.
• Reporters: Mechanisms to output test results and errors to the Terminal, Files, Browsers, or Memory.
• Extensibility: APIs to extend Mocha's functionality.
• Configuration: Support for both file-based and code-based configuration.
• Test Levels: Support for unit, integration, functional/end-to-end, and operational readiness tests.

Limitations (Out-of-Scope)

• Assertions and Mocks: Mocha does not include built-in test assertions or mocking libraries. You must use third-party libraries (like Chai or Sinon) for these tasks.
• Third-party Compatibility: While Mocha strives to maintain compatibility with popular tools, it does not explicitly support libraries not hosted under the mochajs GitHub organization unless stated otherwise.
• Environment Constraints: Mocha is not intended for use with unmaintained versions of Node.js or browsers that do not meet maintainer-defined thresholds.

In Serial Mode (the default), Mocha executes tests within a single process. The lifecycle follows these key stages:

1. Initialization: Mocha loads configuration files, processes command-line options, and optionally spawns a node child process if specific flags are detected.
2. Module Loading: Modules specified via --require are loaded. If these modules contain Mocha-specific exports (like root hook plugins), they are registered.
3. Discovery: Mocha finds test files (searching for .js, .mjs, or .cjs in the test directory by default).
4. Loading & Suite Construction: Test files are loaded via the chosen interface (e.g., bdd). During this phase, Mocha executes suites to find hooks and tests but does not execute the tests themselves. All top-level elements are attached to a single, invisible "root suite".
5. Execution:
   • Global setup fixtures are run.
   • Mocha executes the root suite's "before all" hooks.
   • For each test: "before each" hooks $\rightarrow$ the test $\rightarrow$ "after each" hooks.
   • Child suites inherit "before each" and "after each" hooks from their parents.
   • Root suite's "after all" hooks are run.
6. Teardown: A final summary is printed, and global teardown fixtures are executed.

In Parallel Mode, Mocha distributes test files across a pool of worker subprocesses to improve performance. The lifecycle differs from Serial Mode in several ways:

1. Main Process Setup: The main process handles configuration, module loading (--require), and discovery. It puts all found test files into a queue.
2. Worker Bootstrapping: When a worker is created, it bootstraps itself by loading --require'd modules and registering root hook plugins. Note: Workers ignore global fixtures and custom reporters.
3. Test Execution: Each worker creates a new Mocha instance specifically for the single test file it is assigned. It follows the standard execution loop (hooks $\rightarrow$ tests $\rightarrow$ hooks) but does not report results directly.
4. Result Reporting: Workers buffer test results in memory and return them to the main process upon completion. The main process is responsible for passing these results to the user-specified reporter.
5. Lifecycle: Global setup and teardown fixtures are managed by the main process, not the workers.

Mental Model

Global fixtures are designed for managing external resources that exist outside the JavaScript memory space of your tests.

Key Characteristics:

• Execution: Guaranteed to run exactly once.
• Consistency: Works in parallel, watch, and serial modes.
• Isolation: They do not share a context with tests, suites, or other hooks. You cannot access properties attached to this inside a global fixture from within a describe or it block.
• Context Sharing: mochaGlobalSetup and mochaGlobalTeardown do share a context (this), allowing you to pass data between setup and teardown.

When to use

Use global fixtures for spinning up external resources that tests access via I/O, such as:

• Web servers
• Sockets
• Databases (to start/stop the process)

When NOT to use

Do not use global fixtures to manage in-memory values (like file handles or database connection objects) that you need to access directly in your tests. Because tests cannot access the fixture's context, they won't be able to see these values.

Correct Pattern: Use a global fixture to start the external resource (e.g., the database process), and use root hook plugins or standard hooks to create the actual connection/client used by the tests.

// Example of the recommended pattern:
// 1. Global fixture starts the server
// 2. Test hooks connect to the server

// fixtures.mjs
let server;
export const mochaGlobalSetup = async () => {
  server = await startSomeServer({ port: process.env.TEST_PORT });
};

export const mochaGlobalTeardown = async () => {
  await server.stop();
};

// test.spec.mjs
import { connect } from "my-server-connector-thingy";

describe("my API", function () {
  let connection;

  before(async function () {
    connection = await connect({ port: process.env.TEST_PORT });
  });

  it("should be a nice API", function () {
    // assertions here
  });

  after(async function () {
    return connection.close();
  });
});