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.

This plugin requires ESLint 10.2.0 or later.

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

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
    }
];

• 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
    }
];

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.

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.