ESLint Plugin Mocha

11.2.0 verified Sat Apr 25 auth: no javascript

ESLint plugin providing rules specific to Mocha test suites, such as enforcing best practices, limiting nested describes, and requiring valid test titles. Current version 11.2.0 (January 2025) with a major breaking change in 11.0.0 that renamed several rules (e.g., *-description to *-title) and switched to ESM-only. The plugin ships TypeScript declarations now. It is maintained and released roughly every few months. Compared to other Mocha linting solutions, this is the official and most widely used plugin with ~1M weekly downloads.

Common errors

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

cause Using require() to load eslint-plugin-mocha v11+ which is ESM-only.

fix

Use import statement in an ESM context, or downgrade to v10.x: npm install eslint-plugin-mocha@^10

error Configuration for rule "mocha/valid-suite-description" is invalid: Rule has been removed or renamed. ↓

cause Rule renamed in v11.0.0 from *-description to *-title.

fix

Replace 'mocha/valid-suite-description' with 'mocha/valid-suite-title' in your ESLint config

error ESLint couldn't find the plugin "eslint-plugin-mocha" in flat config. ↓

cause Flat config format not used or plugin not imported correctly.

fix

Import the plugin and spread it in your config array: export default [...mochaPlugin.configs.recommended, ...]

error TypeError: Cannot read properties of undefined (reading 'recommended') ↓

cause Using mochaPlugin.configs.recommended on v10.x without flat config support (v10 prior to 10.4.0).

fix

Update eslint-plugin-mocha to v10.4.0 or later, or use legacy .eslintrc format with v10.x

Warnings

breaking Rules *-description renamed to *-title in v11.0.0 (e.g., valid-suite-description → valid-suite-title) ↓

fix Update all rule names: replace '-description' with '-title' in configs

breaking no-async-describe renamed to no-async-suite in v11.0.0 ↓

fix Replace 'mocha/no-async-describe' with 'mocha/no-async-suite' in your config

breaking CommonJS support dropped in v11.0.0 for no-exports rule ↓

fix Switch to ESM imports or disable the no-exports rule if using CJS

breaking Switched to ESM-only in v11.0.0; require() will fail ↓

fix Convert your project to ESM or use dynamic import(). Alternatively, pin to v10.x

gotcha Flat config format (eslint.config.js) supported from v10.4.0; legacy .eslintrc not supported in v11 ↓

fix Use flat config format. If you need legacy configs, stay on v10.x

deprecated The 'recommended' config in flat configs is available as mochaPlugin.configs.recommended ↓

fix Use flat configs for better compatibility moving forward

Install

npm install eslint-plugin-mocha

yarn add eslint-plugin-mocha

pnpm add eslint-plugin-mocha

Imports

default

wrong

const mochaPlugin = require('eslint-plugin-mocha')

correct

import mochaPlugin from 'eslint-plugin-mocha'

ESM-only since v11; CJS require() will fail at runtime

configs
```
import { configs } from 'eslint-plugin-mocha'
```
Access flat configs (recommended, all) via named export
rules
```
import { rules } from 'eslint-plugin-mocha'
```
Access individual rule definitions for custom configs

Quickstart

Sets up eslint-plugin-mocha with recommended rules and custom overrides using flat config format.

// eslint.config.js (flat config)
import mochaPlugin from 'eslint-plugin-mocha';

export default [
  mochaPlugin.configs.recommended,
  {
    rules: {
      'mocha/no-exclusive-tests': 'error',
      'mocha/no-nested-tests': 'error',
    },
  },
];