Limits of Global Hooks in Mocha's Parallel Test Execution

Hook Execution in Parallel Mode

In Mocha's parallel mode (--parallel), global before and after hooks execute once per worker process, not once per test suite or once per file. Because Mocha spawns separate worker processes to isolate test files, any hook defined in a root-level setup file is re-executed every time a new worker is initialized to handle a batch of tests.

The Impact of Process Isolation

Because each worker is a distinct Node.js process, the following behaviors apply:

• No Shared Memory: State initialized in a before hook (e.g., a global JavaScript object or variable) is local to that specific worker. Tests running in Worker A cannot access data initialized by Worker B.
• Resource Redundancy: If your global hook performs a heavy setup task, such as seeding a database or starting a server, that task will run multiple times (once for each worker spawned).
• Non-Deterministic Order: There is no guarantee regarding the order in which different workers execute their hooks relative to one another.

Managing Shared Resources

To handle setup and teardown across parallel workers without creating race conditions or redundant overhead, move shared logic outside of Mocha's internal hook system:

1. External State Management: Use a shared database, cache (like Redis), or a filesystem lock to coordinate state between workers.
2. Global Setup/Teardown Scripts: Use Mocha's --require or a custom wrapper script to execute a one-time setup before the Mocha process spawns its workers.
3. Idempotent Hooks: Ensure that hooks are idempotent. If multiple workers attempt to seed the same database table, use UPSERT or IF NOT EXISTS logic to prevent collisions.

Verification Method

You can verify this behavior by logging the process ID within a root-level hook. If you see multiple unique PIDs in your console output, the hook is running per worker:

before(() => {
  console.log(`Worker PID: ${process.pid}`);
});

Diagnostic Note: To provide a more specific architectural recommendation, please clarify if your hooks are modifying in-memory JavaScript state or interacting with an external resource (e.g., a SQL database or API).