# Development

Follow these steps to get going in local development.
If you are having trouble, don't be afraid to [ask for help](./CONTRIBUTING.md#❓-got-a-question).

## Prerequisites

- [Node.js](https://nodejs.org/en/download) `^20.19.0 || >=22.12.0` (Node >=22 LTS recommended).
  - If you're new to installing Node, a tool like [nvm](https://github.com/nvm-sh/nvm#install-script) can help you manage multiple version installations.
- npm (do not use yarn or pnpm for this repository).
- [Google Chrome](https://www.google.com/chrome) is required to run browser tests locally.

## Setup

1. Follow [GitHub's documentation](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) on setting up Git, forking, and cloning.
1. 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:

```sh
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 Playwright (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:

```sh
npx mocha --watch test/unit/
```

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

```sh
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:

```sh
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.
- **Playwright tests fail with `Test timeout of ___ms exceeded`:** Run `npm run build` first. Browser tests require the generated bundle. We recommend running `npm run test-browser` to automatically clean and build before each run.
