Development

Follow these steps to get going in local development. If you are having trouble, don't be afraid to ask for help.

Prerequisites

• Node.js ^20.19.0 || >=22.12.0 (Node >=22 LTS recommended).
  • If you're new to installing Node, a tool like nvm can help you manage multiple version installations.
• npm (do not use yarn or pnpm for this repository).
• Google Chrome is required to run browser tests locally.

Setup

1. Follow GitHub's documentation on setting up Git, forking, and cloning.
2. Run npm install from the repository root to install dependencies.
   • Some optional dependencies may fail; you can safely ignore these unless you are trying to build the documentation.
   • If you're sick of seeing the failures, run npm install --ignore-scripts.

Running Tests

You can (and should) run the test suite of Mocha itself before committing, and ideally confirm that your changes give the expected result on another project's test suite too.

To run all code validations (linting, testing in both Node.js and browsers), run:

npm test

For faster feedback during development, you can directly use targeted commands:

Command	What it runs
npm run test-smoke	Quick smoke test to confirm Mocha boots
npm run test-node:unit	Unit tests
npm run test-node:integration	Integration tests (includes build)
npm run test-node:interfaces	Interface tests (BDD, TDD, QUnit, exports)
npm run test-node:reporters	Reporter tests
npm run test-browser	Browser tests via Karma + Chrome (includes build)
npm run tsc	TypeScript type checking
npm run lint	Linting and formatting checks

A typical edit-test cycle uses --watch to re-run tests automatically as you change files:

npx mocha --watch test/unit/

If your change touches browser code or reporters, also run:

npm run test-browser

Building

Mocha's browser bundle (mocha.js) is generated by Rollup. You normally don't need to build manually — npm run test-browser handles it. If you do need to build:

npm run clean
npm run build

Note: Do not edit mocha.js or mocha.js.map directly — they are generated files.

Troubleshooting

• npm test fails right away with lint errors: Run npm run format:fix to auto-fix formatting, then re-run.
• Browser tests fail with "Cannot find module 'mocha'": Run npm run build first. Browser tests require the generated bundle.
• Chrome not found during browser tests: Install Google Chrome. Karma looks for it automatically.