eslint-plugin-mocha

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