esmocha

5.0.0 verified Fri May 01 auth: no javascript

Mocha wrapper with built-in TypeScript support via esbuild, integrated Jest-compatible expect, mock, and snapshot testing. Current stable version is v5.0.0, released in 2025. Release cadence is irregular with major versions marking breaking changes. Key differentiators include zero-config TypeScript execution, Jest-compatible API for familiar testing patterns, and automatic ESM support for Node >=18.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module esmocha not supported. ↓

cause Attempted to use require with ESM-only package.

fix

Change to import { expect } from 'esmocha' and enable ESM in your project.

error TypeError: Expect is not a function ↓

cause Misconfigured import: using default import instead of named import.

fix

Use import { expect } from 'esmocha' rather than import expect from 'esmocha'.

error Error: Cannot find module '@node-loaders/esbuild' ↓

cause Missing peer dependency @node-loaders/esbuild.

fix

Run npm install @node-loaders/esbuild --save-dev.

Warnings

breaking v5.0.0 makes loader optional; if you relied on automatic esbuild loader, you may need to register it manually. ↓

fix Use --loader @node-loaders/esbuild or configure in mocha options.

breaking v4.0.0 updated mocha-expect-snapshot and jest-mock, potentially breaking snapshot file formats. ↓

fix Update snapshots with npx esmocha --update-snapshot.

gotcha esmocha is ESM-only; require() will fail. ↓

fix Use import syntax and ensure package.json has type: module.

gotcha Node.js version must be ^18.19.0 || ^20.9.0 || ^22.0.0 || >=24.0.0; older versions may not work. ↓

fix Upgrade Node to supported version.

Install

npm install esmocha

yarn add esmocha

pnpm add esmocha

Imports

expect
```
import { expect } from 'esmocha'
```
ESM-only since v1; no CommonJS support.
mock
```
import { mock } from 'esmocha'
```
resetAllMocks
```
import { resetAllMocks } from 'esmocha'
```
afterAll
wrong
```
import { afterAll } from 'mocha'
```
correct
```
import { afterAll } from 'esmocha'
```
Re-exported from mocha; prefer importing from esmocha for consistency.

Quickstart

Installs esmocha, creates a simple TypeScript module and test, then runs the test using esmocha.

npm install esmocha --save-dev
echo "export function add(a: number, b: number) { return a + b; }" > add.ts
echo "import { expect } from 'esmocha';
import { add } from './add.js';
describe('add', () => {
  it('should add two numbers', () => {
    expect(add(1, 2)).toBe(3);
  });
});" > test.spec.ts
npx esmocha