eslint-node-test 0.0.1

package/rules/hooks-order.js

@@ -0,0 +1,132 @@
+import {resolveImports, parseTestCall} from './utils/node-test.js';
+
+const MESSAGE_ID = 'hooks-order/error';
+
+const messages = {
+	[MESSAGE_ID]: 'Hook `{{current}}` must come before `{{invalid}}`.',
+};
+
+// Canonical order for node:test hooks.
+const HOOK_ORDER = ['before', 'beforeEach', 'afterEach', 'after'];
+const HOOK_ORDER_INDEX = Object.fromEntries(HOOK_ORDER.map((name, index) => [name, index]));
+
+/*
+Build the fix that reorders a block's hooks into canonical order in a single pass. Returns
+`undefined` (no fix) when the hooks are not a contiguous run of statements, or a comment sits
+between them — reordering would otherwise drop or misattribute code.
+*/
+function getReorderFix(block, hooks, sourceCode) {
+	const positions = hooks.map(hook => block.body.indexOf(hook.statement));
+	const min = Math.min(...positions);
+	const max = Math.max(...positions);
+
+	// Non-hook statements interleaved with the hooks.
+	if (max - min + 1 !== hooks.length) {
+		return undefined;
+	}
+
+	// A comment anywhere between consecutive hooks must not be moved.
+	for (let index = min; index < max; index += 1) {
+		if (sourceCode.getTokensBetween(block.body[index], block.body[index + 1], {includeComments: true}).length > 0) {
+			return undefined;
+		}
+	}
+
+	// Stable sort preserves the original order of same-named hooks.
+	const sorted = hooks.toSorted((a, b) => HOOK_ORDER_INDEX[a.name] - HOOK_ORDER_INDEX[b.name]);
+
+	return function * (fixer) {
+		for (const [index, hook] of hooks.entries()) {
+			if (sorted[index].statement !== hook.statement) {
+				yield fixer.replaceText(hook.statement, sourceCode.getText(sorted[index].statement));
+			}
+		}
+	};
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// Group bare-statement hooks by their containing block, in source order. Hooks used as a
+	// sub-expression (`const x = before(…)`, `await before(…)`) cannot be moved safely and are
+	// skipped. The containing block (a `describe` body or the program) is the ordering scope.
+	const hooksByBlock = new Map();
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (parsed?.kind !== 'hook' || node.parent.type !== 'ExpressionStatement') {
+			return;
+		}
+
+		const block = node.parent.parent;
+		if (block?.type !== 'BlockStatement' && block?.type !== 'Program') {
+			return;
+		}
+
+		let hooks = hooksByBlock.get(block);
+		if (!hooks) {
+			hooks = [];
+			hooksByBlock.set(block, hooks);
+		}
+
+		hooks.push({name: parsed.name, statement: node.parent});
+	});
+
+	context.onExit('Program', () => {
+		const problems = [];
+
+		for (const [block, hooks] of hooksByBlock) {
+			let fix;
+			let fixComputed = false;
+
+			for (const [position, hook] of hooks.entries()) {
+				const index = HOOK_ORDER_INDEX[hook.name];
+				// A hook that appears before the current one but belongs later means the current hook
+				// is out of order and should have come first.
+				const earlierConflict = hooks.slice(0, position).find(other => HOOK_ORDER_INDEX[other.name] > index);
+				if (!earlierConflict) {
+					continue;
+				}
+
+				// Compute the single block-wide reorder fix once, lazily, and share it across the
+				// block's problems; ESLint applies it once and the re-lint finds the block sorted.
+				if (!fixComputed) {
+					fix = getReorderFix(block, hooks, sourceCode);
+					fixComputed = true;
+				}
+
+				problems.push({
+					node: hook.statement.expression,
+					messageId: MESSAGE_ID,
+					data: {current: hook.name, invalid: earlierConflict.name},
+					fix,
+				});
+			}
+		}
+
+		return problems;
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a consistent order of hook declarations.',
+			recommended: 'unopinionated',
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/index.js

@@ -0,0 +1,66 @@
+// Generated file, DO NOT edit
+
+export {default as 'assertion-arguments'} from './assertion-arguments.js';
+export {default as 'consistent-modifier-style'} from './consistent-modifier-style.js';
+export {default as 'consistent-test-context-name'} from './consistent-test-context-name.js';
+export {default as 'consistent-test-filename'} from './consistent-test-filename.js';
+export {default as 'consistent-test-it'} from './consistent-test-it.js';
+export {default as 'hooks-order'} from './hooks-order.js';
+export {default as 'max-assertions'} from './max-assertions.js';
+export {default as 'max-nested-describe'} from './max-nested-describe.js';
+export {default as 'no-assert-in-describe'} from './no-assert-in-describe.js';
+export {default as 'no-assert-in-hook'} from './no-assert-in-hook.js';
+export {default as 'no-assert-throws-async'} from './no-assert-throws-async.js';
+export {default as 'no-assert-throws-string'} from './no-assert-throws-string.js';
+export {default as 'no-async-describe'} from './no-async-describe.js';
+export {default as 'no-async-fn-without-await'} from './no-async-fn-without-await.js';
+export {default as 'no-callback-and-promise'} from './no-callback-and-promise.js';
+export {default as 'no-commented-tests'} from './no-commented-tests.js';
+export {default as 'no-conditional-assertion'} from './no-conditional-assertion.js';
+export {default as 'no-conditional-in-test'} from './no-conditional-in-test.js';
+export {default as 'no-conditional-tests'} from './no-conditional-tests.js';
+export {default as 'no-conflicting-modifiers'} from './no-conflicting-modifiers.js';
+export {default as 'no-done-callback'} from './no-done-callback.js';
+export {default as 'no-duplicate-hooks'} from './no-duplicate-hooks.js';
+export {default as 'no-export'} from './no-export.js';
+export {default as 'no-identical-assertion-arguments'} from './no-identical-assertion-arguments.js';
+export {default as 'no-identical-title'} from './no-identical-title.js';
+export {default as 'no-incorrect-deep-equal'} from './no-incorrect-deep-equal.js';
+export {default as 'no-incorrect-strict-equal'} from './no-incorrect-strict-equal.js';
+export {default as 'no-loop-static-title'} from './no-loop-static-title.js';
+export {default as 'no-misused-concurrency'} from './no-misused-concurrency.js';
+export {default as 'no-mock-timers-destructured-import'} from './no-mock-timers-destructured-import.js';
+export {default as 'no-nested-tests'} from './no-nested-tests.js';
+export {default as 'no-only-test'} from './no-only-test.js';
+export {default as 'no-skip-test'} from './no-skip-test.js';
+export {default as 'no-skip-without-reason'} from './no-skip-without-reason.js';
+export {default as 'no-skip-without-return'} from './no-skip-without-return.js';
+export {default as 'no-standalone-assert'} from './no-standalone-assert.js';
+export {default as 'no-test-inside-hook'} from './no-test-inside-hook.js';
+export {default as 'no-test-return-statement'} from './no-test-return-statement.js';
+export {default as 'no-todo-test'} from './no-todo-test.js';
+export {default as 'no-unawaited-rejects'} from './no-unawaited-rejects.js';
+export {default as 'no-unawaited-subtest'} from './no-unawaited-subtest.js';
+export {default as 'no-unknown-test-options'} from './no-unknown-test-options.js';
+export {default as 'no-useless-assertion'} from './no-useless-assertion.js';
+export {default as 'prefer-assert-match'} from './prefer-assert-match.js';
+export {default as 'prefer-assert-throws'} from './prefer-assert-throws.js';
+export {default as 'prefer-async-await'} from './prefer-async-await.js';
+export {default as 'prefer-context-mock'} from './prefer-context-mock.js';
+export {default as 'prefer-diagnostic'} from './prefer-diagnostic.js';
+export {default as 'prefer-equality-assertion'} from './prefer-equality-assertion.js';
+export {default as 'prefer-hooks-on-top'} from './prefer-hooks-on-top.js';
+export {default as 'prefer-lowercase-title'} from './prefer-lowercase-title.js';
+export {default as 'prefer-mock-method'} from './prefer-mock-method.js';
+export {default as 'prefer-strict-assert'} from './prefer-strict-assert.js';
+export {default as 'prefer-test-context-assert'} from './prefer-test-context-assert.js';
+export {default as 'prefer-todo'} from './prefer-todo.js';
+export {default as 'require-assertion'} from './require-assertion.js';
+export {default as 'require-await-concurrent-subtests'} from './require-await-concurrent-subtests.js';
+export {default as 'require-context-assert-with-plan'} from './require-context-assert-with-plan.js';
+export {default as 'require-hook'} from './require-hook.js';
+export {default as 'require-throws-expectation'} from './require-throws-expectation.js';
+export {default as 'require-top-level-describe'} from './require-top-level-describe.js';
+export {default as 'test-title-format'} from './test-title-format.js';
+export {default as 'test-title'} from './test-title.js';
+export {default as 'valid-describe-callback'} from './valid-describe-callback.js';

package/rules/max-assertions.js

@@ -0,0 +1,87 @@
+import {
+	resolveImports,
+	parseTestCall,
+	parseAssertionCall,
+	createContextTracker,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'max-assertions';
+
+const messages = {
+	[MESSAGE_ID]: 'Too many assertions ({{count}}). Maximum allowed is {{max}}.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const {max} = context.options[0];
+	const tracker = createContextTracker(imports);
+
+	// One frame per enclosing test/subtest; assertions count toward the innermost.
+	const frames = [];
+
+	context.on('CallExpression', node => {
+		const isTest = parseTestCall(node, imports)?.kind === 'test' || tracker.isSubtestCall(node);
+		tracker.update(node);
+
+		if (isTest) {
+			frames.push({node, count: 0});
+			return;
+		}
+
+		if (frames.length > 0 && parseAssertionCall(node, imports)) {
+			frames.at(-1).count += 1;
+		}
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+
+		if (frames.at(-1)?.node !== node) {
+			return;
+		}
+
+		const {count} = frames.pop();
+		if (count > max) {
+			return {
+				node,
+				messageId: MESSAGE_ID,
+				data: {count, max},
+			};
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a maximum number of assertions in a test.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					max: {
+						type: 'integer',
+						minimum: 1,
+						description: 'The maximum number of assertions allowed in a test.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{max: 5}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/max-nested-describe.js

@@ -0,0 +1,70 @@
+import {resolveImports, parseTestCall, createSuiteDepthTracker} from './utils/node-test.js';
+
+const MESSAGE_ID = 'max-nested-describe';
+
+const messages = {
+	[MESSAGE_ID]: 'Describe blocks are nested too deeply ({{depth}}). Maximum allowed is {{max}}.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const {max} = context.options[0];
+
+	const tracker = createSuiteDepthTracker();
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (parsed?.kind !== 'suite') {
+			return;
+		}
+
+		tracker.enterSuite(node);
+
+		if (tracker.depth > max) {
+			return {
+				node,
+				messageId: MESSAGE_ID,
+				data: {depth: tracker.depth, max},
+			};
+		}
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.exitSuite(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a maximum depth for nested `describe` blocks.',
+			recommended: true,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					max: {
+						type: 'integer',
+						minimum: 1,
+						description: 'The maximum allowed depth of nested `describe` blocks.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{max: 5}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-assert-in-describe.js

@@ -0,0 +1,51 @@
+import {
+	resolveImports,
+	parseAssertionCall,
+	nearestTestCallbackKind,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-assert-in-describe';
+
+const messages = {
+	[MESSAGE_ID]: 'Assertion runs when the suite is built, not when a test runs. Move it into a test or hook.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		if (!parseAssertionCall(node, imports)) {
+			return;
+		}
+
+		if (nearestTestCallbackKind(node, imports) !== 'suite') {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow assertions directly inside a `describe` body.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-assert-in-hook.js

@@ -0,0 +1,51 @@
+import {
+	resolveImports,
+	parseAssertionCall,
+	nearestTestCallbackKind,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-assert-in-hook';
+
+const messages = {
+	[MESSAGE_ID]: 'Avoid assertions inside a hook. A hook failure is attributed to every affected test rather than reported as a focused failure. Assert inside a test instead.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		if (!parseAssertionCall(node, imports)) {
+			return;
+		}
+
+		if (nearestTestCallbackKind(node, imports) !== 'hook') {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Disallow assertions inside hooks.',
+			recommended: false,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-assert-throws-async.js

@@ -0,0 +1,114 @@
+import {resolveImports, parseAssertionCall} from './utils/node-test.js';
+import isFunction from './ast/is-function.js';
+import unwrapTypeScriptExpression from './utils/unwrap-typescript-expression.js';
+
+const MESSAGE_ID_ERROR = 'no-assert-throws-async/error';
+const MESSAGE_ID_SUGGESTION = 'no-assert-throws-async/suggestion';
+
+const messages = {
+	[MESSAGE_ID_ERROR]: '`{{method}}` does not catch an async function, which never throws synchronously. Use `{{replacement}}` instead.',
+	[MESSAGE_ID_SUGGESTION]: 'Replace with `{{replacement}}`.',
+};
+
+const SYNC_TO_ASYNC = new Map([
+	['throws', 'rejects'],
+	['doesNotThrow', 'doesNotReject'],
+]);
+
+/*
+Walk up the ancestor chain to find the nearest enclosing function node.
+Returns `undefined` if we hit the program root first.
+*/
+function findEnclosingFunction(node) {
+	let current = node.parent;
+	while (current) {
+		if (isFunction(current)) {
+			return current;
+		}
+
+		current = current.parent;
+	}
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isAssertOrTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const assertion = parseAssertionCall(node, imports);
+		if (!assertion) {
+			return;
+		}
+
+		const replacement = SYNC_TO_ASYNC.get(assertion.method);
+		if (!replacement) {
+			return;
+		}
+
+		const [firstArgument] = node.arguments;
+		if (!firstArgument) {
+			return;
+		}
+
+		const callback = unwrapTypeScriptExpression(firstArgument);
+		if (!isFunction(callback) || !callback.async) {
+			return;
+		}
+
+		const {callee} = node;
+		const data = {method: assertion.method, replacement};
+		const problem = {
+			node: callee,
+			messageId: MESSAGE_ID_ERROR,
+			data,
+		};
+
+		// Only the member forms (`assert.throws`, `t.assert.throws`) can be rewritten. A bare named
+		// import (`throws`) would reference an unimported `rejects`, so leave it reported but unfixed.
+		if (callee.type === 'MemberExpression') {
+			const isAwaited = node.parent?.type === 'AwaitExpression';
+			const enclosingFunction = findEnclosingFunction(node);
+			// Prepend `await` only where it is both valid and needed: a bare call statement inside an
+			// async function. Otherwise just switch the method and let `no-unawaited-rejects` guide the await.
+			const shouldAwait = !isAwaited
+				&& node.parent?.type === 'ExpressionStatement'
+				&& enclosingFunction?.async === true;
+
+			problem.suggest = [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					data,
+					* fix(fixer) {
+						yield fixer.replaceText(callee.property, replacement);
+						if (shouldAwait) {
+							yield fixer.insertTextBefore(node, 'await ');
+						}
+					},
+				},
+			];
+		}
+
+		return problem;
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow passing an async function to `assert.throws()`/`assert.doesNotThrow()`.',
+			recommended: 'unopinionated',
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-assert-throws-string.js

@@ -0,0 +1,65 @@
+import {resolveImports, parseAssertionCall} from './utils/node-test.js';
+import unwrapTypeScriptExpression from './utils/unwrap-typescript-expression.js';
+import {isStringExpression} from './ast/index.js';
+
+const MESSAGE_ID_ERROR = 'no-assert-throws-string/error';
+const MESSAGE_ID_SUGGESTION = 'no-assert-throws-string/suggestion';
+
+const messages = {
+	[MESSAGE_ID_ERROR]: 'The second argument to `{{method}}()` is the failure message, not an error matcher, so the thrown error is not validated.',
+	[MESSAGE_ID_SUGGESTION]: 'Match the error message with `{message: …}`.',
+};
+
+const THROWS_METHODS = new Set(['throws', 'rejects']);
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isAssertOrTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseAssertionCall(node, imports);
+		if (!parsed || !THROWS_METHODS.has(parsed.method)) {
+			return;
+		}
+
+		const errorArgument = node.arguments[1];
+		if (!errorArgument || !isStringExpression(unwrapTypeScriptExpression(errorArgument))) {
+			return;
+		}
+
+		return {
+			node: errorArgument,
+			messageId: MESSAGE_ID_ERROR,
+			data: {method: parsed.method},
+			suggest: [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					/** @param {import('eslint').Rule.RuleFixer} fixer */
+					fix: fixer => fixer.replaceText(errorArgument, `{message: ${sourceCode.getText(errorArgument)}}`),
+				},
+			],
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow a string as the error matcher of `assert.throws()`/`assert.rejects()`.',
+			recommended: 'unopinionated',
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-async-describe.js

@@ -0,0 +1,50 @@
+import {resolveImports, parseTestCall, getTestCallback} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-async-describe';
+
+const messages = {
+	[MESSAGE_ID]: '`node:test` does not await a `{{name}}` callback, so any test registered after an `await` is silently dropped. Make the callback synchronous.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (parsed?.kind !== 'suite') {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+		if (!callback?.async) {
+			return;
+		}
+
+		return {
+			node: callback,
+			messageId: MESSAGE_ID,
+			data: {name: parsed.name},
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow `async` `describe` callbacks.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;