eslint-node-test 0.0.1

package/rules/no-mock-timers-destructured-import.js

@@ -0,0 +1,150 @@
+import {resolveImports} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-mock-timers-destructured-import';
+
+const messages = {
+	[MESSAGE_ID]: '`{{name}}` is imported directly, so `mock.timers` cannot intercept it. Call the global `{{name}}` instead.',
+};
+
+const TIMER_MODULES = new Set(['node:timers', 'timers']);
+
+// Imported timer function -> the `mock.timers` API name that mocks it.
+const FUNCTION_TO_API = new Map([
+	['setTimeout', 'setTimeout'],
+	['clearTimeout', 'setTimeout'],
+	['setInterval', 'setInterval'],
+	['clearInterval', 'setInterval'],
+	['setImmediate', 'setImmediate'],
+	['clearImmediate', 'setImmediate'],
+]);
+
+/*
+The enabled timer APIs, or `null` when `enable()` was called without an `apis` list (all APIs).
+*/
+function getEnabledApis(callExpression) {
+	const [argument] = callExpression.arguments;
+	if (argument?.type !== 'ObjectExpression') {
+		return null;
+	}
+
+	const apisProperty = argument.properties.find(property =>
+		property.type === 'Property'
+		&& !property.computed
+		&& (
+			(property.key.type === 'Identifier' && property.key.name === 'apis')
+			|| (property.key.type === 'Literal' && property.key.value === 'apis')
+		));
+
+	if (apisProperty?.value.type !== 'ArrayExpression') {
+		return null;
+	}
+
+	return apisProperty.value.elements
+		.filter(element => element?.type === 'Literal' && typeof element.value === 'string')
+		.map(element => element.value);
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// Named timer-function imports from `node:timers`.
+	const timerImports = [];
+	for (const node of sourceCode.ast.body) {
+		if (node.type !== 'ImportDeclaration' || !TIMER_MODULES.has(node.source.value)) {
+			continue;
+		}
+
+		for (const specifier of node.specifiers) {
+			if (
+				specifier.type === 'ImportSpecifier'
+				&& specifier.imported.type === 'Identifier'
+				&& FUNCTION_TO_API.has(specifier.imported.name)
+			) {
+				timerImports.push(specifier);
+			}
+		}
+	}
+
+	if (timerImports.length === 0) {
+		return;
+	}
+
+	const {mockLocals} = imports;
+
+	// `mock.timers` (global) or `t.mock.timers` (context).
+	const isMockTimers = node =>
+		node.type === 'MemberExpression'
+		&& !node.computed
+		&& node.property.type === 'Identifier'
+		&& node.property.name === 'timers'
+		&& (
+			// `mock.timers` (global, named/renamed import).
+			(node.object.type === 'Identifier' && mockLocals.has(node.object.name))
+			// `t.mock.timers` (context) or `namespace.mock.timers`.
+			|| (
+				node.object.type === 'MemberExpression'
+				&& !node.object.computed
+				&& node.object.property.type === 'Identifier'
+				&& node.object.property.name === 'mock'
+			)
+		);
+
+	const enabledApis = new Set();
+	let allEnabled = false;
+
+	context.on('CallExpression', node => {
+		const {callee} = node;
+		if (
+			callee.type === 'MemberExpression'
+			&& !callee.computed
+			&& callee.property.type === 'Identifier'
+			&& callee.property.name === 'enable'
+			&& isMockTimers(callee.object)
+		) {
+			const apis = getEnabledApis(node);
+			if (apis === null) {
+				allEnabled = true;
+			} else {
+				for (const api of apis) {
+					enabledApis.add(api);
+				}
+			}
+		}
+	});
+
+	context.onExit('Program', () => {
+		if (!allEnabled && enabledApis.size === 0) {
+			return;
+		}
+
+		return timerImports
+			.filter(specifier => allEnabled || enabledApis.has(FUNCTION_TO_API.get(specifier.imported.name)))
+			.map(specifier => ({
+				node: specifier,
+				messageId: MESSAGE_ID,
+				data: {name: specifier.imported.name},
+			}));
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow destructured timer imports when using `mock.timers`.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-nested-tests.js

@@ -0,0 +1,71 @@
+import {resolveImports, parseTestCall, getTestCallback} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-nested-tests/error';
+
+const messages = {
+	[MESSAGE_ID]: 'Do not define a test or suite inside a test body. Use `t.test()` for subtests instead.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// Stack of callback function nodes of the `test`/`it` calls we are currently inside.
+	// Suites (`describe`/`suite`) legitimately contain tests and nested suites, so they
+	// do not open a scope here — only a test/it body does.
+	const testCallbackStack = [];
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		// A test or suite defined inside a test body should be a subtest (`t.test()`).
+		if ((parsed.kind === 'test' || parsed.kind === 'suite') && testCallbackStack.length > 0) {
+			return {
+				node,
+				messageId: MESSAGE_ID,
+			};
+		}
+
+		if (parsed.kind === 'test') {
+			const callback = getTestCallback(node);
+			if (callback) {
+				testCallbackStack.push(callback);
+			}
+		}
+	});
+
+	context.onExit('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed || parsed.kind !== 'test') {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+		if (callback && testCallbackStack.at(-1) === callback) {
+			testCallbackStack.pop();
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow tests and suites nested inside a test body.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-only-test.js

@@ -0,0 +1,11 @@
+import createTestModifierRule from './shared/test-modifier-rule.js';
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = createTestModifierRule({
+	modifier: 'only',
+	description: 'Disallow the `.only` test modifier.',
+	errorMessage: 'Do not use the `.only` test modifier as it prevents the other tests from running.',
+	recommended: 'unopinionated',
+});
+
+export default config;

package/rules/no-skip-test.js

@@ -0,0 +1,11 @@
+import createTestModifierRule from './shared/test-modifier-rule.js';
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = createTestModifierRule({
+	modifier: 'skip',
+	description: 'Disallow the `.skip` test modifier.',
+	errorMessage: 'Do not skip tests.',
+	recommended: true,
+});
+
+export default config;

package/rules/no-skip-without-reason.js

@@ -0,0 +1,88 @@
+import {
+	resolveImports,
+	parseTestCall,
+	createContextTracker,
+	getTestOptions,
+	findOptionsProperty,
+} from './utils/node-test.js';
+
+const MESSAGE_ID_OPTION = 'no-skip-without-reason/option';
+const MESSAGE_ID_CALL = 'no-skip-without-reason/call';
+
+const messages = {
+	[MESSAGE_ID_OPTION]: 'Give `{{modifier}}` a reason string instead of `true` explaining why.',
+	[MESSAGE_ID_CALL]: 'Pass a reason message to `{{context}}.{{modifier}}()`.',
+};
+
+const REASON_MODIFIERS = ['skip', 'todo'];
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const tracker = createContextTracker(imports);
+
+	context.on('CallExpression', node => {
+		const problems = [];
+
+		// Options form: `{skip: true}` / `{todo: true}` on a test/suite/hook.
+		if (parseTestCall(node, imports)) {
+			const options = getTestOptions(node);
+			for (const modifier of REASON_MODIFIERS) {
+				const property = findOptionsProperty(options, modifier);
+				if (property?.value.type === 'Literal' && property.value.value === true) {
+					problems.push({
+						node: property,
+						messageId: MESSAGE_ID_OPTION,
+						data: {modifier},
+					});
+				}
+			}
+		}
+
+		// Context method form: `t.skip()` / `t.todo()` with no reason message.
+		const {callee} = node;
+		if (
+			node.arguments.length === 0
+			&& callee.type === 'MemberExpression'
+			&& !callee.computed
+			&& callee.property.type === 'Identifier'
+			&& REASON_MODIFIERS.includes(callee.property.name)
+			&& callee.object.type === 'Identifier'
+			&& tracker.isContextName(callee.object.name)
+		) {
+			problems.push({
+				node,
+				messageId: MESSAGE_ID_CALL,
+				data: {context: callee.object.name, modifier: callee.property.name},
+			});
+		}
+
+		tracker.update(node);
+		return problems;
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Require a reason when skipping or marking a test as todo.',
+			recommended: false,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-skip-without-return.js

@@ -0,0 +1,127 @@
+import {resolveImports, createContextTracker} from './utils/node-test.js';
+import isFunction from './ast/is-function.js';
+
+const MESSAGE_ID_ERROR = 'no-skip-without-return/error';
+const MESSAGE_ID_SUGGESTION = 'no-skip-without-return/suggestion';
+
+const messages = {
+	[MESSAGE_ID_ERROR]: '`{{name}}.{{method}}()` does not stop the test; code after it still runs. Return afterwards.',
+	[MESSAGE_ID_SUGGESTION]: 'Add `return` after `{{name}}.{{method}}()`.',
+};
+
+const SKIP_METHODS = new Set(['skip', 'todo']);
+
+/*
+Whether reachable code follows the skip statement before the enclosing test function ends.
+Walks outward: a following sibling statement means code runs after the skip, unless the skip
+is directly followed by a `return`/`throw`. Only block and program bodies are inspected; a skip
+inside a `switch` case is best-effort and not flagged, since detecting it correctly would require
+modeling break/return/fall-through control flow.
+*/
+function hasCodeAfter(skipStatement) {
+	let node = skipStatement;
+	while (node) {
+		const {parent} = node;
+		if (!parent) {
+			return false;
+		}
+
+		if (parent.type === 'BlockStatement' || parent.type === 'Program') {
+			const next = parent.body[parent.body.indexOf(node) + 1];
+			if (next) {
+				// A `return`/`throw` immediately after the skip itself is the correct pattern.
+				if (node === skipStatement && (next.type === 'ReturnStatement' || next.type === 'ThrowStatement')) {
+					return false;
+				}
+
+				return true;
+			}
+		}
+
+		if (isFunction(parent)) {
+			return false;
+		}
+
+		node = parent;
+	}
+
+	return false;
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const tracker = createContextTracker(imports);
+
+	context.on('CallExpression', node => {
+		let problem;
+
+		const {callee, parent} = node;
+		if (
+			parent.type === 'ExpressionStatement'
+			&& callee.type === 'MemberExpression'
+			&& !callee.computed
+			&& callee.property.type === 'Identifier'
+			&& SKIP_METHODS.has(callee.property.name)
+			&& callee.object.type === 'Identifier'
+			&& tracker.isContextName(callee.object.name)
+			&& hasCodeAfter(parent)
+		) {
+			const {name} = callee.object;
+			const method = callee.property.name;
+			problem = {
+				node,
+				messageId: MESSAGE_ID_ERROR,
+				data: {name, method},
+			};
+
+			// Only suggest inserting `return` when the skip is in a block; in a braceless
+			// `if (x) t.skip()` the inserted `return` would escape the condition.
+			if (parent.parent.type === 'BlockStatement') {
+				problem.suggest = [
+					{
+						messageId: MESSAGE_ID_SUGGESTION,
+						data: {name, method},
+						fix(fixer) {
+							// Insert `return;` on its own line, matching the skip statement's indentation.
+							const [start] = sourceCode.getRange(parent);
+							const lineStart = sourceCode.text.lastIndexOf('\n', start - 1) + 1;
+							const [indentation] = /^\s*/.exec(sourceCode.text.slice(lineStart, start));
+							return fixer.insertTextAfter(parent, `\n${indentation}return;`);
+						},
+					},
+				];
+			}
+		}
+
+		tracker.update(node);
+		return problem;
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow `t.skip()`/`t.todo()` without returning afterwards.',
+			recommended: true,
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-standalone-assert.js

@@ -0,0 +1,51 @@
+import {resolveImports, parseAssertionCall} from './utils/node-test.js';
+import isFunction from './ast/is-function.js';
+
+const MESSAGE_ID = 'no-standalone-assert';
+
+const messages = {
+	[MESSAGE_ID]: 'Assertion runs when the module is loaded, not as part of a test. Move it into a test or hook.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile || !imports.hasAssert) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		if (!parseAssertionCall(node, imports)) {
+			return;
+		}
+
+		// Any enclosing function (test/hook callback or a helper) means it is not standalone.
+		for (let current = node.parent; current; current = current.parent) {
+			if (isFunction(current)) {
+				return;
+			}
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow assertions outside of a test.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-test-inside-hook.js

@@ -0,0 +1,68 @@
+import {resolveImports, parseTestCall, getTestCallback} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-test-inside-hook';
+
+const messages = {
+	[MESSAGE_ID]: 'Do not define a test or suite inside a hook. Define it at the top level or inside a `describe`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// Stack of hook callback function nodes we are currently inside.
+	const hookCallbackStack = [];
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		if ((parsed.kind === 'test' || parsed.kind === 'suite') && hookCallbackStack.length > 0) {
+			return {
+				node,
+				messageId: MESSAGE_ID,
+			};
+		}
+
+		if (parsed.kind === 'hook') {
+			const callback = getTestCallback(node);
+			if (callback) {
+				hookCallbackStack.push(callback);
+			}
+		}
+	});
+
+	context.onExit('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (parsed?.kind !== 'hook') {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+		if (callback && hookCallbackStack.at(-1) === callback) {
+			hookCallbackStack.pop();
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow defining tests and suites inside a hook.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-test-return-statement.js

@@ -0,0 +1,114 @@
+import {resolveImports, parseTestCall, getTestCallback} from './utils/node-test.js';
+import isFunction from './ast/is-function.js';
+import isPromiseType from './utils/is-promise-type.js';
+
+const MESSAGE_ID = 'no-test-return-statement';
+
+const messages = {
+	[MESSAGE_ID]: 'Do not return a value from a test. Return a Promise to signal async completion, or return nothing.',
+};
+
+// "Nothing" types and types we cannot pin down — all fine to return.
+const ALLOWED_TYPE_STRINGS = new Set(['void', 'undefined', 'null', 'any', 'never', 'unknown']);
+
+/*
+Whether the type is safe to return from a test: a returned Promise (awaited by `node:test`),
+a "nothing" type, or a type we cannot resolve. Anything else is a concrete value.
+*/
+function isAllowedReturnType(type, checker) {
+	// `isPromiseType` returns `undefined` when indeterminate; only a definite `false` is a value.
+	if (isPromiseType(type, checker) !== false) {
+		return true;
+	}
+
+	if (type.isUnion()) {
+		return type.types.every(member => isAllowedReturnType(member, checker));
+	}
+
+	return ALLOWED_TYPE_STRINGS.has(checker.typeToString(type));
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// This rule relies on type information to tell a Promise from a plain value. Without it
+	// (plain JavaScript, or TypeScript linted without a program), do nothing.
+	const {parserServices} = context.sourceCode;
+	if (!parserServices?.program) {
+		return;
+	}
+
+	const checker = parserServices.program.getTypeChecker();
+	const testCallbacks = new Set();
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (parsed?.kind !== 'test') {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+		if (callback) {
+			testCallbacks.add(callback);
+		}
+	});
+
+	context.on('ReturnStatement', node => {
+		if (!node.argument) {
+			return;
+		}
+
+		// The return must belong to the test callback itself, not a nested helper function.
+		let enclosing = node.parent;
+		while (enclosing && !isFunction(enclosing)) {
+			enclosing = enclosing.parent;
+		}
+
+		if (!enclosing || !testCallbacks.has(enclosing)) {
+			return;
+		}
+
+		// An `async` function always wraps its return value in a Promise, which `node:test`
+		// awaits, so returning a plain value there is fine.
+		if (enclosing.async) {
+			return;
+		}
+
+		let type;
+		try {
+			type = parserServices.getTypeAtLocation(node.argument);
+		} catch {
+			return;
+		}
+
+		if (isAllowedReturnType(type, checker)) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Disallow returning a non-Promise value from a test.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-todo-test.js

@@ -0,0 +1,11 @@
+import createTestModifierRule from './shared/test-modifier-rule.js';
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = createTestModifierRule({
+	modifier: 'todo',
+	description: 'Disallow the `.todo` test modifier.',
+	errorMessage: 'Do not commit `.todo` tests.',
+	recommended: false,
+});
+
+export default config;