Mocha v3: Major Improvements to the Test Runner

Looking back from 2025 Mocha remains useful even with Jest and Vitest around. The corrected .only() behavior described here became ordinary test-runner behavior, which is exactly what a good compatibility fix should become.

I upgraded two repositories at work to Mocha v3. The migration was uneventful with the versions of Karma and Chai we used, and the fixed .only() behavior was reason enough to do it.

What Changed

Dropping Node.js v0.8 Support

Due to the increasing difficulty of applying security patches and looming incompatibilities with Node.js v7.0, Mocha no longer supports Node.js v0.8.

Node v0.8 shipped in 2012. Maintaining compatibility held back developer tool improvements. By the time v3 shipped, most teams had moved to newer Node versions.

The .only() Fix

.only() is no longer “fuzzy”, can be used multiple times, and works like you’d expect.

Before v3, .only() broke in confusing ways:

describe.only('Feature A', () => {
  it('test 1', () => { /* runs */ });
  it('test 2', () => { /* runs */ });
});

describe('Feature B', () => {
  it.only('test 3', () => { /* doesn't run?! */ });
});

In Mocha v2, a describe.only() anywhere prevented individual it.only() calls in other suites from running, which was unpredictable.

After v3, multiple .only() calls work correctly:

describe.only('Feature A', () => {
  it('test 1', () => { /* runs */ });
});

describe.only('Feature B', () => {
  it('test 3', () => { /* also runs */ });
});

During debugging, I want to isolate a few tests without commenting out entire suites. In v3, .only() finally behaved the way its name suggested.

Better Visual Feedback

The dot reporter now uses more distinct characters for “pending” and “failed” tests.

Sounds minor, but it matters when you stare at terminal output all day. Clear distinction between passing (.), pending (,), and failing (!) tests helps you spot problems faster.

Upgrading from v2

Compatibility notes:

• Works with Karma v1.x
• Works with Chai v3.x
• Node v0.8 projects need to upgrade Node first
• .only() behavior changes might reveal hidden test dependencies

If your tests relied on the old “fuzzy” .only(), you might see different tests running after upgrade. That may expose test isolation you thought was working before.

For my two repositories, the .only() fix justified the upgrade.

See the full changelog for complete details.