eslint-plugin-mocha

ESLint rules for Mocha.

This plugin targets Mocha's current JavaScript interfaces documented for Mocha 11. It does not execute Mocha or require Mocha at runtime.

Install

This plugin requires ESLint 10.2.0 or later.

npm install --save-dev eslint-plugin-mocha

Configure

Use the plugin with ESLint's flat config. Apply it only to Mocha test files, and adjust files to match your project:

import mochaPlugin from 'eslint-plugin-mocha';

export default [
    {
        files: [ 'test/**/*.js' ],
        ...mochaPlugin.configs.recommended
    }
];

Configs

• mochaPlugin.configs.recommended: Practical defaults for most projects.
• mochaPlugin.configs.all: Enables every rule. This config may change when new rules are added, so it is better suited for trying the full rule set than for stable long-term lint output.

import mochaPlugin from 'eslint-plugin-mocha';

export default [
    {
        files: [ 'test/**/*.js' ],
        ...mochaPlugin.configs.all
    }
];

Plugin settings

These settings are shared by multiple rules.

• additionalCustomNames: Adds custom suite, test, or hook function names. This is useful for Mocha wrappers such as ember-mocha, mocha-each, or project-specific helpers that wrap setup and teardown. Use interface: "require" for wrappers that expose named imports from a helper module instead of importing directly from mocha.

{
    "rules": {
        "mocha/no-pending-tests": "error",
        "mocha/no-exclusive-tests": "error"
    },
    "settings": {
        "mocha/additionalCustomNames": [
            {
                "name": "describeModule",
                "type": "suite",
                "interface": "BDD"
            },
            {
                "name": "testModule",
                "type": "testCase",
                "interface": "TDD"
            },
            {
                "name": "prepareTestContexts",
                "type": "hook",
                "interface": "BDD"
            }
        ]
    }
}

The name field supports these forms:

• Plain name, such as describeModule:

describeModule('example', function () {});

• Dotted name, such as describe.modifier:

describe.modifier('example', function () {});

• Name with parentheses, such as forEach().describe:

forEach([ 1, 2, 3 ]).describe('example', function (n) {});

• Combination, such as forEach().describeModule.modifier:

forEach([ 1, 2, 3 ]).describeModule.modifier('example', function (n) {});

• type: Selects suite, testCase, or hook.
• interface: Selects BDD, TDD, or require. The default is BDD. With require, rule resolution uses named import statements instead of globals. mocha/consistent-interface also reports named imports of Mocha interface methods when this setting is BDD or TDD, which helps catch accidental require-style usage and interface misconfiguration earlier.

The plugin supports Mocha's BDD, TDD, and Require interfaces. It does not support Mocha's Exports or QUnit interfaces, or third-party UIs with different syntax. Many rules depend on suite, test, and hook calls being represented as nested call expressions, which those interfaces do not provide consistently.

For wrapper APIs that still expose suite, test, or hook call functions, use additionalCustomNames.

Rules

For maintainers: the rules table below is generated, and the headers in documentation/rules/*.md are partly generated. Refresh them with npx just update-eslint-docs. Run mutation testing with npx just test-mutation.

💼 Configurations enabled in.
⚠️ Configurations set to warn in.
🚫 Configurations disabled in.
✅ Set in the recommended configuration.
🔧 Automatically fixable by the --fix CLI option.
💡 Manually fixable by editor suggestions.

Name	Description	💼	⚠️	🚫	🔧	💡
consistent-interface	Enforces consistent use of mocha interfaces			✅	🔧
consistent-spacing-between-blocks	Require consistent spacing between blocks			✅	🔧
consistent-structure	Require consistent structure for Mocha test entities	✅
handle-done-callback	Enforces handling of callbacks for async tests in every branch	✅
limit-retries	Enforce limits for Mocha retries			✅
limit-slow	Enforce limits for Mocha slow thresholds			✅
limit-timeout	Enforce limits for Mocha timeouts			✅
max-top-level-suites	Enforce the number of top-level suites in a single file			✅
no-async-and-done	Disallow async functions that also use a Mocha callback	✅
no-async-in-sync-tests	Disallow async operations in synchronous tests or hooks	✅
no-async-suite	Disallow async functions passed to a suite	✅			🔧
no-code-after-done	Disallow executing code after calling a Mocha callback	✅
no-conditional-tests	Disallow conditional suite and test declarations	✅
no-done-twice	Disallow calling a Mocha callback more than once	✅
no-empty-title	Disallow empty suite and test descriptions	✅
no-exclusive-tests	Disallow exclusive tests		✅			💡
no-exports	Disallow exports from test files	✅				💡
no-hooks	Disallow hooks			✅
no-hooks-for-single-child	Disallow hooks with a single direct child			✅
no-identical-title	Disallow identical titles	✅
no-mocha-arrows	Disallow arrow functions as arguments to mocha functions	✅			🔧
no-nested-suites	Disallow suites to be nested within other suites			✅
no-nested-tests	Disallow tests to be nested within other tests	✅
no-pending-tests	Disallow pending tests		✅			💡
no-return-and-done	Disallow returning in a test or hook function that uses a callback	✅
no-return-from-async	Disallow returning from an async test or hook			✅
no-root-hooks	Disallow root hooks			✅
no-setup-in-suite	Disallow setup in suite blocks			✅
no-synchronous-tests	Disallow synchronous tests			✅
no-top-level-tests	Disallow top-level tests	✅
prefer-arrow-callback	Require using arrow functions for callbacks			✅	🔧
valid-suite-title	Require suite descriptions to match a pre-configured regular expression			✅
valid-test-title	Require test descriptions to match a pre-configured regular expression			✅