mocha-web

2.6.1 verified Fri May 01 auth: no javascript

Runs Mocha tests in Chromium via Playwright, bundling test files with esbuild. Current stable version is 2.6.1, released quarterly with dependency upgrades and bug fixes. Unlike alternatives like karma or jest-electron, it integrates directly with esbuild for fast bundling and esbuild config support, and supports both ESM and CJS tests. Requires Mocha, Playwright Chromium, and esbuild as peer dependencies. Node >=20 required.

Common errors

error Error: Cannot find module 'mocha' ↓

cause Missing peer dependency mocha.

fix

npm install --save-dev mocha

error Error: Cannot find module 'esbuild' ↓

cause Missing peer dependency esbuild.

fix

npm install --save-dev esbuild

error Error: Cannot find module '@playwright/browser-chromium' ↓

cause Missing peer dependency @playwright/browser-chromium.

fix

npm install --save-dev @playwright/browser-chromium

error Error: The 'devtools' option is deprecated. Use 'open-devtools' instead. ↓

cause Using deprecated --devtools flag.

fix

Use --open-devtools instead of --devtools.

Warnings

breaking Node.js version 18 is no longer supported; require Node >=20 ↓

fix Upgrade Node.js to v20 or higher.

deprecated The --esbuild-config option works only with esbuild config files; inline config not supported. ↓

fix Use a separate esbuild config file if bundling options are needed.

gotcha Package does not expose a programmatic JavaScript API; only a CLI binary. ↓

fix Use shell commands or child_process to invoke mocha-web programmatically.

gotcha Peer dependencies (mocha, esbuild, @playwright/browser-chromium) must be installed manually; mocha-web does not install them automatically. ↓

fix Run npm install --save-dev mocha esbuild @playwright/browser-chromium alongside mocha-web.

gotcha ESM support in esbuild config requires format=esm, else default is CJS. ↓

fix Set format: 'esm' in your esbuild config file if you want ESM output.

breaking Removed deprecated 'devtools' launch option; use 'open-devtools' instead. ↓

fix Replace '--devtools' with '--open-devtools' in CLI arguments.

Install

npm install mocha-web

yarn add mocha-web

pnpm add mocha-web

Imports

default (CLI)
wrong
```
mocha-web
```
correct
```
npx mocha-web "test/**/*.spec.js"
```
CLI usage; no programmatic API exported.
default export
wrong
```
const mochaWeb = require('mocha-web')
```
correct
```
import mochaWeb from 'mocha-web'
```
Package does not export any JS symbols; only a CLI binary. Importing is a mistake unless you are using a bundler that resolves the main field.
mocha-web cli
```
mocha-web --version
```
Run as a command-line tool; no programmatic API.

Quickstart

Installs mocha-web with required peer deps, runs a basic Mocha test in Chromium via CLI.

// 1. Install dependencies
npm install --save-dev mocha-web mocha @playwright/browser-chromium esbuild

// 2. Create a test file test/example.spec.js
const assert = require('assert');
describe('Example', () => {
  it('should pass', () => {
    assert.strictEqual(1 + 1, 2);
  });
});

// 3. Run tests in Chromium
npx mocha-web "test/**/*.spec.js" -t 5000