eslint-plugin-mocha
Version:
Eslint rules for mocha.
172 lines (135 loc) ā¢ 12.2 kB
Markdown
[](https://www.npmjs.org/package/eslint-plugin-mocha)
[](https://github.com/lo1tuma/eslint-plugin-mocha/actions)
[](https://coveralls.io/r/lo1tuma/eslint-plugin-mocha)
[](https://www.npmjs.org/package/eslint-plugin-mocha)
# eslint-plugin-mocha
ESLint rules for [Mocha](https://mochajs.org/).
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.
```bash
npm install --save-dev eslint-plugin-mocha
```
## Configure
Use the plugin with ESLint's [flat config](https://eslint.org/docs/latest/use/configure/configuration-files-new). Apply it only to Mocha test files, and adjust `files` to match your project:
```js
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.
```js
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`](https://github.com/switchfly/ember-mocha), [`mocha-each`](https://github.com/ryym/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`.
```json
{
"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`:
```js
describeModule('example', function () {});
```
- Dotted name, such as `describe.modifier`:
```js
describe.modifier('example', function () {});
```
- Name with parentheses, such as `forEach().describe`:
```js
forEach([ 1, 2, 3 ]).describe('example', function (n) {});
```
- Combination, such as `forEach().describeModule.modifier`:
```js
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`.
<!-- dprint-ignore-start -->
<!-- begin auto-generated rules list -->
š¼ [Configurations](https://github.com/lo1tuma/eslint-plugin-mocha#configs) enabled in.\
ā ļø [Configurations](https://github.com/lo1tuma/eslint-plugin-mocha#configs) set to warn in.\
š« [Configurations](https://github.com/lo1tuma/eslint-plugin-mocha#configs) disabled in.\
ā
Set in the `recommended` [configuration](https://github.com/lo1tuma/eslint-plugin-mocha#configs).\
š§ Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
š” Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
| NameĀ Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā Ā | Description | š¼ | ā ļø | š« | š§ | š” |
| :-------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- | :- | :- | :- | :- | :- |
| [consistent-interface](documentation/rules/consistent-interface.md) | Enforces consistent use of mocha interfaces | | | ā
| š§ | |
| [consistent-spacing-between-blocks](documentation/rules/consistent-spacing-between-blocks.md) | Require consistent spacing between blocks | | | ā
| š§ | |
| [consistent-structure](documentation/rules/consistent-structure.md) | Require consistent structure for Mocha test entities | ā
| | | | |
| [handle-done-callback](documentation/rules/handle-done-callback.md) | Enforces handling of callbacks for async tests in every branch | ā
| | | | |
| [limit-retries](documentation/rules/limit-retries.md) | Enforce limits for Mocha retries | | | ā
| | |
| [limit-slow](documentation/rules/limit-slow.md) | Enforce limits for Mocha slow thresholds | | | ā
| | |
| [limit-timeout](documentation/rules/limit-timeout.md) | Enforce limits for Mocha timeouts | | | ā
| | |
| [max-top-level-suites](documentation/rules/max-top-level-suites.md) | Enforce the number of top-level suites in a single file | | | ā
| | |
| [no-async-and-done](documentation/rules/no-async-and-done.md) | Disallow async functions that also use a Mocha callback | ā
| | | | |
| [no-async-in-sync-tests](documentation/rules/no-async-in-sync-tests.md) | Disallow async operations in synchronous tests or hooks | ā
| | | | |
| [no-async-suite](documentation/rules/no-async-suite.md) | Disallow async functions passed to a suite | ā
| | | š§ | |
| [no-code-after-done](documentation/rules/no-code-after-done.md) | Disallow executing code after calling a Mocha callback | ā
| | | | |
| [no-conditional-tests](documentation/rules/no-conditional-tests.md) | Disallow conditional suite and test declarations | ā
| | | | |
| [no-done-twice](documentation/rules/no-done-twice.md) | Disallow calling a Mocha callback more than once | ā
| | | | |
| [no-empty-title](documentation/rules/no-empty-title.md) | Disallow empty suite and test descriptions | ā
| | | | |
| [no-exclusive-tests](documentation/rules/no-exclusive-tests.md) | Disallow exclusive tests | | ā
| | | š” |
| [no-exports](documentation/rules/no-exports.md) | Disallow exports from test files | ā
| | | | š” |
| [no-hooks](documentation/rules/no-hooks.md) | Disallow hooks | | | ā
| | |
| [no-hooks-for-single-child](documentation/rules/no-hooks-for-single-child.md) | Disallow hooks with a single direct child | | | ā
| | |
| [no-identical-title](documentation/rules/no-identical-title.md) | Disallow identical titles | ā
| | | | |
| [no-mocha-arrows](documentation/rules/no-mocha-arrows.md) | Disallow arrow functions as arguments to mocha functions | ā
| | | š§ | |
| [no-nested-suites](documentation/rules/no-nested-suites.md) | Disallow suites to be nested within other suites | | | ā
| | |
| [no-nested-tests](documentation/rules/no-nested-tests.md) | Disallow tests to be nested within other tests | ā
| | | | |
| [no-pending-tests](documentation/rules/no-pending-tests.md) | Disallow pending tests | | ā
| | | š” |
| [no-return-and-done](documentation/rules/no-return-and-done.md) | Disallow returning in a test or hook function that uses a callback | ā
| | | | |
| [no-return-from-async](documentation/rules/no-return-from-async.md) | Disallow returning from an async test or hook | | | ā
| | |
| [no-root-hooks](documentation/rules/no-root-hooks.md) | Disallow root hooks | | | ā
| | |
| [no-setup-in-suite](documentation/rules/no-setup-in-suite.md) | Disallow setup in suite blocks | | | ā
| | |
| [no-synchronous-tests](documentation/rules/no-synchronous-tests.md) | Disallow synchronous tests | | | ā
| | |
| [no-top-level-tests](documentation/rules/no-top-level-tests.md) | Disallow top-level tests | ā
| | | | |
| [prefer-arrow-callback](documentation/rules/prefer-arrow-callback.md) | Require using arrow functions for callbacks | | | ā
| š§ | |
| [valid-suite-title](documentation/rules/valid-suite-title.md) | Require suite descriptions to match a pre-configured regular expression | | | ā
| | |
| [valid-test-title](documentation/rules/valid-test-title.md) | Require test descriptions to match a pre-configured regular expression | | | ā
| | |
<!-- end auto-generated rules list -->
<!-- dprint-ignore-end -->