eslint-plugin-mocha

What is eslint-plugin-mocha?

eslint-plugin-mocha is an ESLint plugin that provides linting rules specific to Mocha, a popular JavaScript test framework. It helps enforce best practices and coding standards for Mocha tests, ensuring consistency and reducing common errors.

What are eslint-plugin-mocha's main functionalities?

Disallow exclusive tests

This rule disallows the use of exclusive tests (e.g., `describe.only` and `it.only`) to prevent accidentally skipping other tests.

module.exports = { "rules": { "mocha/no-exclusive-tests": "error" } };

Disallow skipped tests

This rule warns against the use of skipped tests (e.g., `describe.skip` and `it.skip`) to ensure that all tests are being run.

module.exports = { "rules": { "mocha/no-skipped-tests": "warn" } };

Enforce test case titles

This rule enforces that test cases have valid descriptions, ensuring that test titles are meaningful and descriptive.

module.exports = { "rules": { "mocha/valid-test-description": "error" } };

Disallow synchronous tests

This rule disallows synchronous tests, encouraging the use of asynchronous tests to avoid blocking the event loop.

module.exports = { "rules": { "mocha/no-synchronous-tests": "error" } };

Limit the number of top-level suites

This rule limits the number of top-level suites in a test file, promoting better organization and structure of tests.

module.exports = { "rules": { "mocha/max-top-level-suites": ["error", { "limit": 1 }] } };

Other packages similar to eslint-plugin-mocha

eslint-plugin-jest

eslint-plugin-jest is an ESLint plugin for Jest, another popular JavaScript testing framework. It provides similar linting rules specific to Jest, helping enforce best practices and coding standards for Jest tests. While eslint-plugin-mocha is tailored for Mocha, eslint-plugin-jest is designed for Jest.

eslint-plugin-jasmine

eslint-plugin-jasmine is an ESLint plugin for Jasmine, a behavior-driven development framework for testing JavaScript code. It offers linting rules specific to Jasmine, ensuring best practices and consistency in Jasmine tests. Like eslint-plugin-mocha, it focuses on a different testing framework.

eslint-plugin-qunit

eslint-plugin-qunit is an ESLint plugin for QUnit, a powerful, easy-to-use JavaScript unit testing framework. It provides linting rules specific to QUnit, helping maintain best practices and coding standards in QUnit tests. It serves a similar purpose to eslint-plugin-mocha but for QUnit.

README

eslint-plugin-mocha

ESLint rules for mocha.

Install and configure

This plugin requires ESLint 9.0.0 or later.

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

Configuration via eslint.config.js

To use this plugin with eslint flat configuration format:

import mochaPlugin from "eslint-plugin-mocha";

export default [
    mochaPlugin.configs.recommended, // or `mochaPlugin.configs.all` to enable all
    // ... Your configurations here
];

Plugin Settings

This plugin supports the following settings, which are used by multiple rules:

• additionalCustomNames: This allows rules to check additional function names when looking for suites or test cases. This might be used with a custom Mocha extension, such as ember-mocha or mocha-each.

  Example:

  {
      "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"
              }
          ]
      }
  }
  

  The name property can be in any of the following forms:

  • A plain name e.g. describeModule, which allows:

    describeModule("example", function() { ... });
    

  • A dotted name, e.g. describe.modifier, which allows:

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

  • A name with parentheses, e.g. forEach().describe, which allows:

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

  • Any combination of the above, e.g. forEach().describeModule.modifier, which allows:

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

• interface: This allows to select either TDD, BDD (default) or exports. When using exports mocha variables are resolved from named import statements instead of global variables.

Rules

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

Name	Description	💼	⚠️	🚫	🔧
consistent-interface	Enforces consistent use of mocha interfaces
consistent-spacing-between-blocks	Require consistent spacing between blocks	✅			🔧
handle-done-callback	Enforces handling of callbacks for async tests	✅
max-top-level-suites	Enforce the number of top-level suites in a single file	✅
no-async-suite	Disallow async functions passed to a suite	✅			🔧
no-empty-title	Disallow empty test descriptions	✅
no-exclusive-tests	Disallow exclusive tests		✅
no-exports	Disallow exports from test files	✅
no-global-tests	Disallow global tests	✅
no-hooks	Disallow hooks			✅
no-hooks-for-single-case	Disallow hooks for a single test or test suite			✅
no-identical-title	Disallow identical titles	✅
no-mocha-arrows	Disallow arrow functions as arguments to mocha functions	✅			🔧
no-nested-tests	Disallow tests to be nested within other tests	✅
no-pending-tests	Disallow pending tests		✅
no-return-and-callback	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-setup-in-describe	Disallow setup in describe blocks	✅
no-sibling-hooks	Disallow duplicate uses of a hook at the same level inside a suite	✅
no-synchronous-tests	Disallow synchronous tests			✅
no-top-level-hooks	Disallow top-level hooks		✅
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			✅

Changelog

11.1.0 (May 24, 2025)

Bug Fixes

• Fix detecting mocha config calls in no-setup-in-describe (#387)
• Fix consistent-spacing-between-blocks when using timeout() modifier (#379)

Enhancements

• Include typescript declaration files in npm package (#378)

Documentation

• Fix valid-suite-title options documentation (#385)

Code Refactoring

• Add test to verify no-identical-title supports same titles in different suites (#388)
• Add test-case to verify generated tests work with consistent-spacing-between-blocks (#386)
• Add regression tests for no-setup-in-describe (#380)