eslint-plugin-mocha weekly downloads statistics

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.

Configure

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

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.

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.

The name field supports these forms:

• Plain name, such as describeModule: • Dotted name, such as describe.modifier: • Name with parentheses, such as forEach().describe: • Combination, such as forEach().describeModule.modifier: • 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 | | | ✅ | | |