mocha "Error: Timeout of 2000ms exceeded" only when the full suite runs in CI: how to find the slow hook

TL;DR

The timed-out test is usually innocent: a before or beforeEach hook (or an earlier test in the same file) eats most of the 2-second budget, and the named test just happens to be holding the bag when the timer fires. Run the full suite with the spec reporter to see per-test durations, find the hook or neighbor that is slow, and fix that instead of raising the timeout. The timeout is a messenger, not the problem.

mocha "Error: Timeout of 2000ms exceeded" only when the full suite runs in CI: how to find the slow hook

Steps

1. Run the full suite the way CI does, with the spec reporter: npx mocha --reporter spec. The reporter prints each test's duration in milliseconds. Expected: you get a full timing map and can see which tests and files are slow.
2. Look at the timed-out test's neighbors: a slow test just before it, or a before/beforeEach hook in the same file that does heavy setup (DB seeding, server boot, big fixture load). Expected: you identify a hook or sibling test consuming most of the budget.
3. Confirm by running the single file alone, then the single test alone with --grep. Expected: the test passes fast alone and slow (or timing out) in the file, which proves the cost comes from shared setup, not the test.
4. Fix the slow part: move one-time setup from beforeEach to before, shrink the seeded data, or split the heavy file so the hook cost is not shared by every test. Expected: the hook duration drops and the timeout disappears in the full run.
5. Rerun the full suite in CI. Expected: no timeout errors and the total suite time is lower.

Use this when

• Mocha reports "Timeout of 2000ms exceeded" only in the full CI run
• The same test passes quickly when run alone with --grep
• You suspect hooks or neighboring tests, not the failing test itself

Not for this skill when

• The test hangs forever even alone (that is an unresolved promise or missing done, not a slow hook)
• The test is genuinely slow and needs a longer timeout on its own merits
• The runner is jest or vitest, which attribute timeouts differently

Variant phrasings

• mocha timeout only when running full suite
• mocha 2000ms exceeded in CI but passes locally alone
• find slow mocha hook causing timeout

Why it happens

Mocha's timeout covers the test plus its hooks: a beforeEach that takes 1.9 seconds leaves 100ms for the test itself. In a full run, hooks accumulate shared state and contention (a database filling up, a port pool draining), so setup that is fast in isolation gets slow at suite scale. The timeout names the test, but the budget was spent before the test body ran.

Edge cases

• Root-level hooks (in a root hook plugin or a top-level beforeEach) affect every file; check those when many files time out at once.
• --parallel mode changes which tests share a process; a timeout that appears only in parallel mode is worker contention, not a slow hook.
• Do not raise the timeout globally to silence this. It hides the slow setup and makes the whole suite slower for everyone.

Provenance

Resolved from the public thread: https://vectle.com/posts/psttiiE1h9KBL4EYKHt7OwFA