eslint-node-test

ESLint rules for the Node.js built-in test runner (node:test)

This plugin helps you avoid common mistakes and write more consistent tests with node:test, the test runner built into Node.js.

Install

npm install --save-dev eslint eslint-node-test

Requires ESLint >=10.4, flat config, and ESM.

Usage

Use a preset config or configure each rule in eslint.config.js.

import eslintNodeTest from 'eslint-node-test';
import {defineConfig} from 'eslint/config';

export default defineConfig([
	eslintNodeTest.configs.recommended,
]);

Or configure rules individually:

import eslintNodeTest from 'eslint-node-test';
import {defineConfig} from 'eslint/config';

export default defineConfig([
	{
		plugins: {
			'node-test': eslintNodeTest,
		},
		rules: {
			'node-test/no-only-test': 'error',
			'node-test/no-identical-title': 'error',
		},
	},
]);

The rules only activate in files that import from node:test (and assertion rules also activate for Node's built-in assert module), so you can safely apply the plugin across your whole project.

Rules

💼 Configurations enabled in.
✅ Set in the recommended configuration.
☑️ Set in the unopinionated configuration.
🔧 Automatically fixable by the --fix CLI option.
💡 Manually fixable by editor suggestions.

Name	Description	💼	🔧	💡
assertion-arguments	Enforce the correct number of arguments for node:assert assertions.	✅ ☑️
consistent-assert-style	Enforce a consistent truthiness assertion style.	✅	🔧
consistent-assert-throws-callback-style	Enforce a consistent body style for assert.throws() arrow callbacks.		🔧
consistent-modifier-style	Enforce a consistent style for test modifiers.
consistent-test-context-name	Enforce a consistent name for the test context parameter.	✅ ☑️
consistent-test-filename	Enforce a consistent test file name pattern.
consistent-test-it	Enforce consistent use of test or it.
hooks-order	Enforce a consistent order of hook declarations.	✅ ☑️	🔧
max-assertions	Enforce a maximum number of assertions in a test.
max-nested-describe	Enforce a maximum depth for nested describe blocks.	✅
no-assert-in-describe	Disallow assertions directly inside a describe body.	✅
no-assert-in-hook	Disallow assertions inside hooks.
no-assert-match-string	Disallow strings as the regexp argument of assert.match()/assert.doesNotMatch().	✅ ☑️		💡
no-assert-throws-async	Disallow passing an async function to assert.throws()/assert.doesNotThrow().	✅ ☑️		💡
no-assert-throws-call	Disallow calling the function passed to assert.throws().	✅ ☑️		💡
no-assert-throws-multiple-statements	Disallow multiple statements in assert.throws()/assert.rejects() callbacks.	✅
no-assert-throws-string	Disallow a string as the error matcher of assert.throws()/assert.rejects().	✅ ☑️		💡
no-async-describe	Disallow async describe callbacks.	✅ ☑️
no-async-fn-without-await	Disallow async test/hook functions that have no await expression.	✅ ☑️		💡
no-callback-and-promise	Disallow a test or hook from using both a callback and a Promise.	✅ ☑️
no-commented-tests	Disallow commented-out tests.
no-compound-assertion	Disallow compound truthiness assertions.	✅ ☑️	🔧
no-conditional-assertion	Disallow assertions inside conditional code within a test.	✅ ☑️
no-conditional-in-test	Disallow conditional logic inside tests.
no-conditional-tests	Disallow conditionally registering tests, suites, and hooks.	✅
no-conflicting-modifiers	Disallow conflicting test modifiers.	✅ ☑️
no-constant-assertion	Disallow assertions with constant outcomes.	✅ ☑️
no-done-callback	Disallow callback (done) parameters in tests and hooks.
no-duplicate-assertions	Disallow adjacent duplicate assertions.	✅ ☑️
no-duplicate-hooks	Disallow duplicate hooks within the same scope.	✅
no-duplicate-mock-timers-enable	Disallow enabling mock timers more than once without resetting them.	✅ ☑️
no-duplicate-plan	Disallow setting a test plan more than once in the same test.	✅ ☑️
no-expect-failure-without-reason	Require a reason when marking a test or suite as expected to fail.	✅
no-export	Disallow exports from test files.	✅
no-identical-assertion-arguments	Disallow comparing a value to itself in an assertion.	✅ ☑️
no-identical-title	Disallow identical test titles within the same scope.	✅ ☑️
no-import-test-files	Disallow imports of Node.js test files.	✅ ☑️
no-incorrect-deep-equal	Disallow deepEqual/deepStrictEqual (and their notDeep* variants) when comparing with primitives.	✅ ☑️	🔧
no-incorrect-strict-equal	Disallow strictEqual/equal (and their not* variants) when comparing with an object or array literal.	✅ ☑️	🔧
no-late-test-activity	Disallow test activity inside detached asynchronous callbacks.	✅ ☑️	🔧
no-loop-static-title	Disallow a static test or suite title inside a loop.	✅ ☑️
no-misused-concurrency	Disallow the concurrency option on a test without subtests.	✅ ☑️
no-misused-context-hook	Disallow context hooks without runnable subtests.	✅ ☑️
no-mock-module-after-import	Disallow mocking a module after statically importing it.	✅ ☑️
no-mock-timers-destructured-import	Disallow destructured timer imports when using mock.timers.	✅ ☑️
no-nested-tests	Disallow tests and suites nested inside a test body.	✅ ☑️
no-only-test	Disallow the .only test modifier.	✅ ☑️		💡
no-parent-test-context	Disallow references to parent test contexts inside subtests.	✅ ☑️		💡
no-process-chdir-in-test	Disallow changing the working directory inside tests.	✅
no-process-env-mutation	Disallow mutating process.env inside tests.	✅
no-process-exit-in-test	Disallow process exit control in test files.	✅ ☑️
no-skip-test	Disallow the .skip test modifier.	✅		💡
no-skip-without-reason	Require a reason when skipping or marking a test as todo.
no-skip-without-return	Disallow t.skip()/t.todo() without returning afterwards.	✅		💡
no-sleep-in-test	Disallow sleeping in tests with setTimeout.
no-snapshot-in-loop	Disallow snapshot assertions inside loop bodies.
no-standalone-assert	Disallow assertions outside of a test.	✅ ☑️
no-test-global-configuration	Disallow process-wide node:test configuration inside tests.	✅
no-test-inside-hook	Disallow defining tests and suites inside a hook.	✅ ☑️
no-test-return-statement	Disallow returning a concrete non-Promise value from a test or hook.	✅
no-todo-test	Disallow the .todo test modifier.			💡
no-unawaited-promise-assertion	Disallow assertions inside unawaited Promise callbacks.	✅ ☑️	🔧
no-unawaited-rejects	Require assert.rejects()/assert.doesNotReject() to be awaited or returned.	✅ ☑️	🔧
no-unawaited-subtest	Require subtests created with the test context to be awaited or returned.	✅	🔧
no-unknown-test-options	Disallow unknown options in test and hook option objects.	✅
no-unneeded-async-rejects-callback	Disallow unneeded async callbacks passed to assert.rejects().			💡
no-useless-assertion	Disallow assert.doesNotThrow() and assert.doesNotReject().	✅
prefer-assert-match	Prefer assert.match()/assert.doesNotMatch() over asserting RegExp#test() / String#match() results.	✅ ☑️	🔧
prefer-assert-throws	Prefer assert.throws()/assert.rejects() over try/catch with an assertion.	✅
prefer-async-await	Prefer async/await over returning a Promise.	✅
prefer-context-mock	Prefer the test context t.mock over the global mock.	✅
prefer-diagnostic	Prefer the test context diagnostic() over console inside tests.			💡
prefer-equality-assertion	Prefer an equality assertion over a truthiness assertion on a comparison.	✅ ☑️	🔧
prefer-hooks-on-top	Require hooks to be declared before the tests in their scope.	✅
prefer-lowercase-title	Enforce lowercase test titles.		🔧
prefer-mock-accessor	Prefer mock.getter() and mock.setter() over mock.method() with accessor options.	✅	🔧
prefer-mock-call-count	Prefer mock.callCount() over mock.calls.length.	✅ ☑️	🔧
prefer-mock-method	Prefer mock.method() over assigning mock.fn() to an object property.	✅		💡
prefer-strict-assert	Prefer strict assertion methods over their legacy loose counterparts.	✅ ☑️	🔧
prefer-test-context-assert	Prefer the test context t.assert over the imported node:assert.	✅		💡
prefer-todo	Prefer .todo for empty placeholder tests.	✅		💡
require-assertion	Require that each test contains at least one assertion.	✅
require-await-concurrent-subtests	Require subtests created in a loop callback to be awaited.	✅ ☑️
require-context-assert-with-plan	Require assertions to use the test context when the test sets a plan.	✅ ☑️
require-hook	Require setup and teardown code to be inside a hook.
require-mock-timers-advance	Require mock timers to be advanced after enabling timer APIs.	✅
require-mock-timers-apis	Require an explicit apis option when enabling mock.timers.	✅ ☑️
require-throws-expectation	Require an error matcher for assert.throws()/assert.rejects().	✅ ☑️
require-throws-validator-return-true	Require validator functions in assert.throws()/assert.rejects() to return true.	✅ ☑️
require-top-level-describe	Require tests and hooks to be inside a top-level describe.
test-title	Require tests to have a title.	✅	🔧
test-title-format	Require test titles to match a configured pattern.
valid-describe-callback	Enforce valid describe callbacks.	✅ ☑️
valid-test-tags	Require valid test tags.	✅ ☑️	🔧

Preset configs

This plugin exports these configs:

• recommended — Enables the recommended rules.
• unopinionated — A subset of recommended with only the most uncontroversial rules.
• all — Enables every rule (not recommended for general use; useful to discover new rules).

import eslintNodeTest from 'eslint-node-test';
import {defineConfig} from 'eslint/config';

export default defineConfig([
	eslintNodeTest.configs.recommended,
]);

Related

• eslint-plugin-unicorn — Lots of awesome ESLint rules.
• eslint-package-json — Powerful ESLint rules for package.json.
• eslint-plugin-ava — ESLint rules for AVA.
• test-extras — Assertions and utilities that make node:test better.