--parallel workers versus --grep filtering under limited CI memory

Direct Answer

No, --grep filtering is not applied before work distribution. In Mocha 10.x, each worker process loads the full test suite independently and applies the grep pattern locally. The combination does not produce deterministic test ordering or reporting across platforms. Global hooks (root-level before, after, beforeEach, afterEach) execute once per worker, multiplying initialization cost and memory usage by the worker count.

Confirmed Behavior (Mocha 10.x Source)

• Test selection timing: The main process spawns a worker pool via worker_threads. Each worker receives the complete test file list and instantiates its own Mocha runner. The grep pattern is passed as a configuration option to each worker's Mocha instance (lib/cli/run-helpers.js, lib/parallel-buffer.js). No central pre-filtering occurs.
• Ordering determinism: Workers pull test files from a shared queue as capacity allows. Execution order varies per run and per platform. Output streams interleave unless a structured reporter (e.g., JSON) with worker-ID tagging is used.
• Global hook propagation: Root-level hooks are not shared. Each worker re-runs all global hooks during its Mocha instance initialization. A suite that opens one database connection in a global before will open N connections (where N = worker count).
• Memory profile: Baseline memory per worker includes the full test dependency graph. --grep reduces executed tests but not loaded modules. Memory scales roughly linearly with --parallel count.

Practical Implications for CI

Recommended Configuration for Limited CI Memory

1. If global hooks are expensive (DB migration, auth tokens, cache priming): avoid --parallel. Use --grep to shard the suite across multiple CI jobs instead (e.g., --grep "@smoke", --grep "@integration"). Each job runs serially with one global hook execution.
2. If hooks are cheap and memory allows: use --parallel with a worker count tuned to your memory quota (e.g., --parallel 2 on a 2-core/4GB runner). Add --reporter=json or a custom reporter that prefixes output with worker ID to make interleaved logs readable.
3. Never rely on hook side effects (e.g., a singleton initialized in before) being visible across workers. Each worker has its own process memory.

Verification Steps (Run Once Locally)

# 1. Confirm Mocha version
mocha --version

# 2. Observe hook execution count
mocha --parallel 3 --grep "smoke" --reporter=spec 2>&1 | grep -c "global before"
# Expect: 3 lines (once per worker)

# 3. Check ordering determinism
for i in {1..5}; do mocha --parallel 2 --grep "smoke" --reporter=spec 2>&1 | grep -E "^  [0-9]+ passing" | head -1; done
# Expect: varying order across runs

One Diagnostic Detail Needed

What is the peak RSS memory of a single worker running your full suite (without --parallel)? Run /usr/bin/time -v mocha 2>&1 | grep "Maximum resident" on Linux or use memory_profiler in Node. This determines the maximum safe --parallel value for your CI memory quota.