eslint-node-test 0.0.1

package/rules/prefer-mock-method.js

@@ -0,0 +1,115 @@
+import {resolveImports, createContextTracker, isGlobalMock} from './utils/node-test.js';
+import {isValueNotUsable} from './utils/index.js';
+
+const MESSAGE_ID_ERROR = 'prefer-mock-method/error';
+const MESSAGE_ID_SUGGESTION = 'prefer-mock-method/suggestion';
+
+const messages = {
+	[MESSAGE_ID_ERROR]: 'Prefer `{{base}}.method()` over assigning `{{base}}.fn()` to a property, so the original method is tracked and can be restored.',
+	[MESSAGE_ID_SUGGESTION]: 'Replace with `{{base}}.method()`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const tracker = createContextTracker(imports);
+
+	// The context `<ctx>.mock`.
+	const isContextMock = node =>
+		node.type === 'MemberExpression'
+		&& !node.computed
+		&& node.property.type === 'Identifier'
+		&& node.property.name === 'mock'
+		&& node.object.type === 'Identifier'
+		&& tracker.isContextName(node.object.name);
+
+	// Keep the context-name stack in sync as we enter and leave test callbacks.
+	context.on('CallExpression', node => {
+		tracker.update(node);
+	});
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+
+	context.on('AssignmentExpression', node => {
+		if (node.operator !== '=' || node.left.type !== 'MemberExpression' || node.right.type !== 'CallExpression') {
+			return;
+		}
+
+		const {callee} = node.right;
+		if (
+			callee.type !== 'MemberExpression'
+			|| callee.computed
+			|| callee.property.type !== 'Identifier'
+			|| callee.property.name !== 'fn'
+			|| (!isGlobalMock(callee.object, imports) && !isContextMock(callee.object))
+		) {
+			return;
+		}
+
+		const base = sourceCode.getText(callee.object);
+		const problem = {
+			node,
+			messageId: MESSAGE_ID_ERROR,
+			data: {base},
+		};
+
+		const {left} = node;
+		const mockArguments = node.right.arguments;
+
+		// Resolve the property name to a `mock.method` second argument.
+		let key;
+		if (!left.computed && left.property.type === 'Identifier') {
+			key = `'${left.property.name}'`;
+		} else if (left.computed) {
+			key = sourceCode.getText(left.property);
+		}
+
+		// Only suggest a rewrite for the simple cases: a resolvable key, at most one argument (the
+		// implementation, which becomes `mock.method`'s third argument), and no inner comments to drop.
+		// `<obj>.method = mock.fn()` evaluates to the mock function, but `mock.method(…)` returns the
+		// original method, so skip the suggestion when the assignment's value is used.
+		const canRewrite = key !== undefined
+			&& mockArguments.length <= 1
+			&& isValueNotUsable(node)
+			&& sourceCode.getCommentsInside(node).length === 0;
+
+		if (canRewrite) {
+			const objectText = sourceCode.getText(left.object);
+			const implementation = mockArguments.length === 1 ? `, ${sourceCode.getText(mockArguments[0])}` : '';
+			const replacement = `${base}.method(${objectText}, ${key}${implementation})`;
+			problem.suggest = [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					data: {base},
+					fix: fixer => fixer.replaceText(node, replacement),
+				},
+			];
+		}
+
+		return problem;
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer `mock.method()` over assigning `mock.fn()` to an object property.',
+			recommended: true,
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-strict-assert.js

@@ -0,0 +1,69 @@
+import {resolveImports, parseAssertionCall} from './utils/node-test.js';
+
+const MESSAGE_ID = 'prefer-strict-assert';
+
+const messages = {
+	[MESSAGE_ID]: 'Prefer `{{replacement}}` over the legacy loose `{{method}}`.',
+};
+
+// Legacy loose (`==`) assertion methods and their strict equivalents.
+const LOOSE_TO_STRICT = new Map([
+	['equal', 'strictEqual'],
+	['notEqual', 'notStrictEqual'],
+	['deepEqual', 'deepStrictEqual'],
+	['notDeepEqual', 'notDeepStrictEqual'],
+]);
+
+/** @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);
+		// In a strict-mode assert module the legacy methods already behave strictly, so leave them.
+		if (!assertion || assertion.isStrict) {
+			return;
+		}
+
+		const replacement = LOOSE_TO_STRICT.get(assertion.method);
+		if (!replacement) {
+			return;
+		}
+
+		const problem = {
+			node,
+			messageId: MESSAGE_ID,
+			data: {method: assertion.method, replacement},
+		};
+
+		// Autofix only the member forms (`assert.equal`, `t.assert.equal`). A bare named
+		// import (`equal`) cannot be rewritten to `strictEqual` without also importing it,
+		// so leave it reported but unfixed.
+		if (assertion.methodNode && assertion.methodNode !== node.callee) {
+			problem.fix = fixer => fixer.replaceText(assertion.methodNode, replacement);
+		}
+
+		return problem;
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer strict assertion methods over their legacy loose counterparts.',
+			recommended: 'unopinionated',
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-test-context-assert.js

@@ -0,0 +1,125 @@
+import {resolveImports, createContextTracker} from './utils/node-test.js';
+
+const MESSAGE_ID_ERROR = 'prefer-test-context-assert/error';
+const MESSAGE_ID_SUGGESTION = 'prefer-test-context-assert/suggestion';
+
+const messages = {
+	[MESSAGE_ID_ERROR]: 'Prefer the test context `{{context}}.assert.{{method}}()` over the imported `node:assert`, so the runner ties the assertion to this test.',
+	[MESSAGE_ID_SUGGESTION]: 'Replace with `{{context}}.assert.{{method}}()`.',
+};
+
+// Under `node:assert/strict` these loose methods behave as their strict counterparts.
+// `t.assert.*` exposes the non-strict functions, so preserve the behavior when converting.
+const LOOSE_TO_STRICT = new Map([
+	['equal', 'strictEqual'],
+	['notEqual', 'notStrictEqual'],
+	['deepEqual', 'deepStrictEqual'],
+	['notDeepEqual', 'notDeepStrictEqual'],
+]);
+
+/**
+Classify a call as an imported `node:assert` assertion (not the `t.assert.*` form, which is
+already preferred) and resolve the method name to use on `t.assert`, accounting for strict mode.
+
+@returns {{method: string} | undefined}
+*/
+const getAssertMethod = (node, imports) => {
+	const {callee} = node;
+
+	// `strictEqual(…)` — named import.
+	if (callee.type === 'Identifier' && imports.assertNamed.has(callee.name)) {
+		const method = imports.assertNamed.get(callee.name);
+		const isStrict = imports.strictAssertLocals.has(callee.name);
+		return {method: (isStrict && LOOSE_TO_STRICT.get(method)) || method};
+	}
+
+	// `assert(…)` — the bare assert function (alias of `ok`).
+	if (callee.type === 'Identifier' && imports.assertNamespace.has(callee.name)) {
+		return {method: 'ok'};
+	}
+
+	// `assert.strictEqual(…)` — namespace member.
+	if (
+		callee.type === 'MemberExpression'
+		&& !callee.computed
+		&& callee.property.type === 'Identifier'
+		&& callee.object.type === 'Identifier'
+		&& imports.assertNamespace.has(callee.object.name)
+	) {
+		const method = callee.property.name;
+		const isStrict = imports.strictAssertLocals.has(callee.object.name);
+		return {method: (isStrict && LOOSE_TO_STRICT.get(method)) || method};
+	}
+
+	return undefined;
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	// Needs both: an imported `node:assert` to convert from, and `node:test` to provide a context.
+	if (!imports.hasAssert || !imports.isTestFile) {
+		return;
+	}
+
+	const tracker = createContextTracker(imports);
+
+	context.on('CallExpression', node => {
+		tracker.update(node);
+
+		const contextName = tracker.current();
+		if (!contextName) {
+			return;
+		}
+
+		const assertion = getAssertMethod(node, imports);
+		if (!assertion) {
+			return;
+		}
+
+		const {method} = assertion;
+		const data = {context: contextName, method};
+
+		const problem = {
+			node: node.callee,
+			messageId: MESSAGE_ID_ERROR,
+			data,
+		};
+
+		// Replacing the whole callee would drop any comments inside it.
+		if (sourceCode.getCommentsInside(node.callee).length === 0) {
+			problem.suggest = [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					data,
+					fix: fixer => fixer.replaceText(node.callee, `${contextName}.assert.${method}`),
+				},
+			];
+		}
+
+		return problem;
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer the test context `t.assert` over the imported `node:assert`.',
+			recommended: true,
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-todo.js

@@ -0,0 +1,98 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestCallback,
+	getTestOptions,
+	getTestTitle,
+} from './utils/node-test.js';
+import {removeArgument} from './fix/index.js';
+
+const MESSAGE_ID_ERROR = 'prefer-todo/error';
+const MESSAGE_ID_SUGGESTION = 'prefer-todo/suggestion';
+
+const messages = {
+	[MESSAGE_ID_ERROR]: 'Empty placeholder test. Use `.todo` to mark it as unfinished.',
+	[MESSAGE_ID_SUGGESTION]: 'Mark as `.todo`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		// Only plain tests (a placeholder suite is a different concept); an existing modifier is intentional.
+		if (parsed?.kind !== 'test' || parsed.modifiers.length > 0) {
+			return;
+		}
+
+		// A `.todo` needs a title to be meaningful.
+		if (!getTestTitle(node, context)) {
+			return;
+		}
+
+		// An options object (`test('title', {skip: true}, …)`) marks intent, so leave it alone.
+		if (getTestOptions(node)) {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+
+		// `test('title')` — only a title, no implementation.
+		const isTitleOnly = !callback && node.arguments.length === 1;
+
+		// `test('title', () => {})` — an empty implementation body.
+		const hasEmptyBody = callback?.body.type === 'BlockStatement' && callback.body.body.length === 0;
+
+		if (!isTitleOnly && !hasEmptyBody) {
+			return;
+		}
+
+		const {callee} = node;
+		// Dropping the function would drop any comments inside its body, so skip the fix then.
+		const canFix = !callback || sourceCode.getCommentsInside(callback).length === 0;
+
+		const problem = {
+			node,
+			messageId: MESSAGE_ID_ERROR,
+		};
+
+		if (canFix) {
+			problem.suggest = [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					* fix(fixer) {
+						yield fixer.insertTextAfter(callee, '.todo');
+						if (callback) {
+							yield removeArgument(fixer, callback, context);
+						}
+					},
+				},
+			];
+		}
+
+		return problem;
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer `.todo` for empty placeholder tests.',
+			recommended: true,
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/require-assertion.js

@@ -0,0 +1,92 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestCallback,
+	parseAssertionCall,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'require-assertion/error';
+
+const messages = {
+	[MESSAGE_ID]: 'Test is missing an assertion. Tests without assertions will always pass.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	/*
+	Stack of {callNode, callback, hasAssertion} for each open test call.
+	We push when we enter a test call with an inline callback, and pop (and possibly report) on exit.
+	*/
+	const testStack = [];
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+
+		// Track nested test calls as their own scope (don't let their assertions count for parent).
+		if (parsed && parsed.kind === 'test') {
+			const callback = getTestCallback(node);
+			// Only push if there's an inline function body to inspect.
+			if (callback) {
+				testStack.push({callNode: node, callback, hasAssertion: false});
+				return;
+			}
+
+			// No inline callback: skip/todo or external implementation — don't report.
+			if (testStack.length > 0) {
+				// Mark parent as having an assertion-like (external impl may assert).
+				testStack.at(-1).hasAssertion = true;
+			}
+
+			return;
+		}
+
+		// Check if this call is an assertion.
+		if (testStack.length > 0 && parseAssertionCall(node, imports)) {
+			testStack.at(-1).hasAssertion = true;
+		}
+	});
+
+	context.onExit('CallExpression', node => {
+		if (testStack.length === 0) {
+			return;
+		}
+
+		const top = testStack.at(-1);
+		if (top.callNode !== node) {
+			return;
+		}
+
+		testStack.pop();
+
+		if (!top.hasAssertion) {
+			return {
+				node,
+				messageId: MESSAGE_ID,
+			};
+		}
+
+		// Propagate to parent: a nested test call itself doesn't count as an assertion in the parent.
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require that each test contains at least one assertion.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/require-await-concurrent-subtests.js

@@ -0,0 +1,119 @@
+import {resolveImports, createContextTracker} from './utils/node-test.js';
+import isFunction from './ast/is-function.js';
+
+const MESSAGE_ID = 'require-await-concurrent-subtests';
+
+const messages = {
+	[MESSAGE_ID]: 'Subtests created in a `{{method}}()` callback are not awaited, so they are cancelled when the parent test finishes. Use `await Promise.all(items.map(item => t.test(…)))`.',
+};
+
+// Array methods commonly used to create one subtest per element.
+const ITERATION_METHODS = new Set(['map', 'forEach', 'flatMap']);
+
+/** Find the iteration call (`xs.map(cb)`) whose callback directly encloses `node`, or `undefined`. */
+function findEnclosingIterationCall(node) {
+	let current = node.parent;
+	while (current) {
+		if (isFunction(current)) {
+			const {parent} = current;
+			if (
+				parent?.type === 'CallExpression'
+				&& parent.callee.type === 'MemberExpression'
+				&& !parent.callee.computed
+				&& parent.callee.property.type === 'Identifier'
+				&& ITERATION_METHODS.has(parent.callee.property.name)
+				&& parent.arguments.includes(current)
+			) {
+				return parent;
+			}
+
+			// Any other function is a scope boundary (the test callback or a helper).
+			return undefined;
+		}
+
+		current = current.parent;
+	}
+}
+
+/** Whether the iteration call is an argument to a consumed `Promise.all(…)` / `Promise.allSettled(…)`. */
+function isAwaitedViaPromiseAll(iterationCall) {
+	const {parent} = iterationCall;
+	if (
+		parent?.type === 'CallExpression'
+		&& parent.callee.type === 'MemberExpression'
+		&& !parent.callee.computed
+		&& parent.callee.property.type === 'Identifier'
+		&& (parent.callee.property.name === 'all' || parent.callee.property.name === 'allSettled')
+		&& parent.callee.object.type === 'Identifier'
+		&& parent.callee.object.name === 'Promise'
+		&& parent.arguments.includes(iterationCall)
+	) {
+		// The `Promise.all(…)` itself must be consumed (awaited, returned, or assigned), not discarded —
+		// otherwise the parent test still finishes before the subtests settle. It is discarded when left
+		// as a floating bare statement or explicitly thrown away with `void`.
+		const {parent: grandparent} = parent;
+		const isDiscarded = grandparent?.type === 'ExpressionStatement'
+			|| (grandparent?.type === 'UnaryExpression' && grandparent.operator === 'void');
+		return !isDiscarded;
+	}
+
+	return false;
+}
+
+/** @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 isSubtest = tracker.isSubtestCall(node);
+
+		let problem;
+		// A bare-statement subtest is already covered by `no-unawaited-subtest`; this rule covers the
+		// expression-body and `return` forms inside an iteration callback that it misses.
+		if (isSubtest && node.parent?.type !== 'ExpressionStatement') {
+			const iterationCall = findEnclosingIterationCall(node);
+			if (iterationCall) {
+				const method = iterationCall.callee.property.name;
+				// `forEach` discards its callbacks' results entirely; `map`/`flatMap` are fine only when
+				// the resulting array is awaited via `Promise.all`.
+				const handled = method !== 'forEach' && isAwaitedViaPromiseAll(iterationCall);
+				if (!handled) {
+					problem = {
+						node,
+						messageId: MESSAGE_ID,
+						data: {method},
+					};
+				}
+			}
+		}
+
+		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: 'Require subtests created in a loop callback to be awaited.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;