@cjser/eslint-node-test 0.2.0-cjser.2

package/rules/prefer-assert-match.js

@@ -0,0 +1,253 @@
+import {
+	resolveImports,
+	parseAssertionCall,
+	createContextTracker,
+	isAssertionCallWithSupportedContext,
+} from './utils/node-test.js';
+import {isRegexLiteral, isBooleanLiteral} from './ast/index.js';
+import {isParenthesized} from './utils/index.js';
+import unwrapTypeScriptExpression from './utils/unwrap-typescript-expression.js';
+
+const MESSAGE_ID = 'prefer-assert-match/error';
+
+const messages = {
+	[MESSAGE_ID]: 'Prefer `assert.{{method}}()` over asserting `{{pattern}}` results.',
+};
+
+/*
+Determine whether a node is a RegExp (regex literal or `new RegExp()` / `RegExp()` call).
+We deliberately keep this simple: only regex literals and direct constructor calls.
+We do not follow variable references to avoid false positives.
+*/
+function isRegExp(node) {
+	if (!node) {
+		return false;
+	}
+
+	if (isRegexLiteral(node)) {
+		return true;
+	}
+
+	// `new RegExp(...)` or `RegExp(...)`
+	return (node.type === 'NewExpression' || node.type === 'CallExpression')
+		&& node.callee.type === 'Identifier'
+		&& node.callee.name === 'RegExp';
+}
+
+/*
+Parse a `re.test(str)` or `str.match(re)` call.
+Returns `{regex, string, methodName}` or `undefined`.
+
+`String#search` is intentionally not handled: it returns the match index (`-1` for no match),
+so `assert.ok(str.search(re))` is truthy for *no* match and falsy for a match at index `0` —
+the opposite polarity of `re.test()` / `str.match()`, so it cannot be rewritten to `assert.match`.
+*/
+function parseRegexCall(node) {
+	if (
+		node.type !== 'CallExpression'
+		|| node.callee.type !== 'MemberExpression'
+		|| node.callee.computed
+		|| node.callee.property.type !== 'Identifier'
+	) {
+		return;
+	}
+
+	const {name} = node.callee.property;
+	const {object} = node.callee;
+
+	if (name === 'test' && isRegExp(object)) {
+		// `re.test(str)` — first arg is the string
+		const stringNode = node.arguments[0];
+		if (!stringNode || stringNode.type === 'SpreadElement') {
+			return;
+		}
+
+		return {regex: object, string: stringNode, methodName: 'test'};
+	}
+
+	if (name === 'match' && node.arguments.length > 0) {
+		// `str.match(re)` — first arg should be the regex
+		const regexArgument = node.arguments[0];
+		if (!regexArgument || regexArgument.type === 'SpreadElement') {
+			return;
+		}
+
+		if (!isRegExp(regexArgument)) {
+			return;
+		}
+
+		return {regex: regexArgument, string: object, methodName: name};
+	}
+}
+
+/*
+Build a fixer that replaces `assert.ok(re.test(str))` → `assert.match(str, re)`.
+Handles the callee method rename and the argument rewrite.
+*/
+function buildFix({node, method, regexNode, stringNode, extraArgsToRemove, sourceCode}) {
+	return function * fix(fixer) {
+		const assertCallee = node.callee;
+
+		if (
+			assertCallee.type === 'MemberExpression'
+			&& !assertCallee.computed
+			&& assertCallee.property.type === 'Identifier'
+		) {
+			yield fixer.replaceText(assertCallee.property, method);
+		} else {
+			// Named import: the callee is an Identifier — we can't rename it without
+			// knowing the local name. Just bail on the fix.
+			return;
+		}
+
+		const regexText = sourceCode.getText(regexNode);
+		const stringText = sourceCode.getText(stringNode);
+		yield fixer.replaceText(node.arguments[0], `${stringText}, ${regexText}`);
+
+		// Remove any extra arguments (e.g. the boolean literal in strictEqual).
+		for (const argument of extraArgsToRemove) {
+			const tokenBefore = sourceCode.getTokenBefore(argument, {includeComments: false});
+			yield fixer.removeRange([sourceCode.getRange(tokenBefore)[0], sourceCode.getRange(argument)[1]]);
+		}
+	};
+}
+
+/*
+Whether the call can be safely rewritten: a member-expression callee (a named import can't be
+renamed without knowing the local name), no comments inside the call that the argument
+rewrite/removal could drop, and no parenthesized arguments. The rewrite replaces the first
+argument's inner node and removes the boolean argument up to its own inner node, so surrounding
+parentheses on either would be left behind as stray tokens.
+*/
+function canAutofix(node, context) {
+	return node.callee.type === 'MemberExpression'
+		&& context.sourceCode.getCommentsInside(node).length === 0
+		&& node.arguments.every(argument => !isParenthesized(argument, context));
+}
+
+/** Build the problem object for a detected regex-result assertion. */
+function makeProblem({node, assertMethod, regexCall, extraArgsToRemove, context}) {
+	const fix = canAutofix(node, context)
+		? buildFix({
+			node, method: assertMethod, regexNode: regexCall.regex, stringNode: regexCall.string, extraArgsToRemove, sourceCode: context.sourceCode,
+		})
+		: undefined;
+
+	return {
+		node,
+		messageId: MESSAGE_ID,
+		data: {method: assertMethod, pattern: `${regexCall.methodName}()`},
+		fix,
+	};
+}
+
+/*
+Handle the equality forms `assert.strictEqual`/`equal`/`notStrictEqual`/`notEqual`, where one
+argument is `re.test(str)` and the other a boolean literal, in either order.
+*/
+function getEqualityProblem(node, method, context) {
+	if (node.arguments.length < 2) {
+		return;
+	}
+
+	const [firstArgument, secondArgument] = node.arguments;
+	const unwrappedFirst = unwrapTypeScriptExpression(firstArgument);
+	const unwrappedSecond = unwrapTypeScriptExpression(secondArgument);
+
+	let regexCall = parseRegexCall(unwrappedFirst);
+	let booleanLiteral = unwrappedSecond;
+	if (!(regexCall && isBooleanLiteral(booleanLiteral))) {
+		regexCall = parseRegexCall(unwrappedSecond);
+		booleanLiteral = unwrappedFirst;
+		if (!(regexCall && isBooleanLiteral(booleanLiteral))) {
+			return;
+		}
+	}
+
+	const isNegated = method === 'notStrictEqual' || method === 'notEqual';
+	// `strictEqual(re.test(str), true)` asserts a match; negating the method or comparing to
+	// `false` each flip the meaning.
+	const isMatches = (booleanLiteral.value === true) !== isNegated;
+	const assertMethod = isMatches ? 'match' : 'doesNotMatch';
+
+	// `buildFix` collapses the two arguments into `str, re` regardless of their original order.
+	return makeProblem({
+		node, assertMethod, regexCall, extraArgsToRemove: [secondArgument], context,
+	});
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+
+	if (!imports.isAssertOrTestFile) {
+		return;
+	}
+
+	const tracker = createContextTracker(imports, {trackHooks: true});
+
+	context.on('CallExpression', node => {
+		tracker.update(node);
+
+		const parsed = parseAssertionCall(node, imports);
+		if (!parsed || !isAssertionCallWithSupportedContext(node, tracker)) {
+			return;
+		}
+
+		const {method} = parsed;
+
+		// `assert.ok(re.test(str))` / `assert.ok(str.match(re))`
+		// `assert.ok(!re.test(str))` / `assert.ok(!str.match(re))`
+		if (method === 'ok') {
+			const firstArgument = node.arguments[0];
+			if (!firstArgument) {
+				return;
+			}
+
+			let target = unwrapTypeScriptExpression(firstArgument);
+			let assertMethod = 'match';
+
+			// Negated: `assert.ok(!re.test(str))` asserts no match.
+			if (target.type === 'UnaryExpression' && target.operator === '!') {
+				target = unwrapTypeScriptExpression(target.argument);
+				assertMethod = 'doesNotMatch';
+			}
+
+			const regexCall = parseRegexCall(target);
+			if (!regexCall) {
+				return;
+			}
+
+			return makeProblem({
+				node, assertMethod, regexCall, extraArgsToRemove: [], context,
+			});
+		}
+
+		// `assert.strictEqual`/`equal`/`notStrictEqual`/`notEqual(re.test(str), true/false)`
+		if (['strictEqual', 'equal', 'notStrictEqual', 'notEqual'].includes(method)) {
+			return getEqualityProblem(node, method, context);
+		}
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer `assert.match()`/`assert.doesNotMatch()` over asserting `RegExp#test()` / `String#match()` results.',
+			recommended: 'unopinionated',
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-assert-throws.js

@@ -0,0 +1,97 @@
+import {resolveImports, parseAssertionCall} from './utils/node-test.js';
+import containsSuspensionPoint from './utils/contains-suspension-point.js';
+import isFunction from './ast/is-function.js';
+
+const MESSAGE_ID_SYNC = 'prefer-assert-throws/sync';
+const MESSAGE_ID_ASYNC = 'prefer-assert-throws/async';
+
+const messages = {
+	[MESSAGE_ID_SYNC]: 'Prefer `assert.throws()` over try/catch with an assertion.',
+	[MESSAGE_ID_ASYNC]: 'Prefer `assert.rejects()` over try/catch with an assertion.',
+};
+
+/*
+Return true if the catch block contains at least one assertion call anywhere inside it. `assert.fail()`
+is excluded: a bare `fail()` in a catch asserts that the try body should *not* throw, which is the
+opposite of the `assert.throws()` pattern this rule suggests.
+*/
+function catchHasAssertion(catchClause, imports, visitorKeys) {
+	function walk(node) {
+		// Do not descend into nested functions — an assertion defined there is not executed by the
+		// catch itself, so it does not make this try/catch the `assert.throws()` pattern.
+		if (isFunction(node)) {
+			return false;
+		}
+
+		const assertion = node.type === 'CallExpression' ? parseAssertionCall(node, imports) : undefined;
+		if (assertion && assertion.method !== 'fail') {
+			return true;
+		}
+
+		for (const key of visitorKeys[node.type] ?? []) {
+			const child = node[key];
+			for (const childNode of Array.isArray(child) ? child : [child]) {
+				if (childNode?.type && walk(childNode)) {
+					return true;
+				}
+			}
+		}
+
+		return false;
+	}
+
+	return walk(catchClause.body);
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+
+	if (!imports.isAssertOrTestFile) {
+		return;
+	}
+
+	const {visitorKeys} = context.sourceCode;
+
+	context.on('TryStatement', node => {
+		// Must have a catch clause — otherwise there is no assertion to move.
+		if (!node.handler) {
+			return;
+		}
+
+		// The try body must have at least one statement (the throwing code).
+		if (node.block.body.length === 0) {
+			return;
+		}
+
+		// The catch clause must contain an assertion.
+		if (!catchHasAssertion(node.handler, imports, visitorKeys)) {
+			return;
+		}
+
+		// A suspension point (`await`, `for await`) in the try body makes it async.
+		const isAsync = node.block.body.some(statement => containsSuspensionPoint(statement, visitorKeys));
+
+		return {
+			node,
+			messageId: isAsync ? MESSAGE_ID_ASYNC : MESSAGE_ID_SYNC,
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer `assert.throws()`/`assert.rejects()` over try/catch with an assertion.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-async-await.js

@@ -0,0 +1,203 @@
+import {findVariable} from '@eslint-community/eslint-utils';
+import {resolveImports, parseTestCall, getTestCallback} from './utils/node-test.js';
+
+const MESSAGE_ID = 'prefer-async-await/error';
+
+const messages = {
+	[MESSAGE_ID]: 'Prefer async/await instead of returning a Promise.',
+};
+
+/**
+Collect all `return` statements that are directly inside `block`, descending
+into control-flow nodes but not into nested functions.
+
+@param {import('estree').BlockStatement} block
+@returns {import('estree').ReturnStatement[]}
+*/
+function findReturnStatements(block) {
+	const results = [];
+
+	function walk(node) {
+		if (!node) {
+			return;
+		}
+
+		switch (node.type) {
+			case 'ReturnStatement': {
+				results.push(node);
+				break;
+			}
+
+			case 'BlockStatement': {
+				for (const statement of node.body) {
+					walk(statement);
+				}
+
+				break;
+			}
+
+			case 'IfStatement': {
+				walk(node.consequent);
+				walk(node.alternate);
+				break;
+			}
+
+			case 'SwitchStatement': {
+				for (const switchCase of node.cases) {
+					for (const statement of switchCase.consequent) {
+						walk(statement);
+					}
+				}
+
+				break;
+			}
+
+			case 'TryStatement': {
+				walk(node.block);
+				if (node.handler) {
+					walk(node.handler.body);
+				}
+
+				walk(node.finalizer);
+				break;
+			}
+
+			case 'ForStatement':
+			case 'ForInStatement':
+			case 'ForOfStatement':
+			case 'WhileStatement':
+			case 'DoWhileStatement':
+			case 'LabeledStatement':
+			case 'WithStatement': {
+				walk(node.body);
+				break;
+			}
+
+			// Do not descend into nested functions
+			default: {
+				break;
+			}
+		}
+	}
+
+	walk(block);
+
+	return results;
+}
+
+/**
+Check whether a node contains a `.then(...)` call anywhere in its `.then`/`.catch`/`.finally`
+member chain.
+
+@param {import('estree').Node | null | undefined} node
+@returns {boolean}
+*/
+function containsThen(node) {
+	while (node) {
+		if (node.type === 'ChainExpression') {
+			node = node.expression;
+			continue;
+		}
+
+		if (
+			node.type !== 'CallExpression'
+			|| node.callee.type !== 'MemberExpression'
+		) {
+			return false;
+		}
+
+		const {callee} = node;
+		if (
+			callee.property.type === 'Identifier'
+			&& callee.property.name === 'then'
+		) {
+			return true;
+		}
+
+		node = callee.object;
+	}
+
+	return false;
+}
+
+/** @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);
+		if (!parsed) {
+			return;
+		}
+
+		// `describe`/`suite` callbacks run synchronously and are never awaited, so returning a
+		// Promise from them is meaningless and converting to async/await would not help.
+		if (parsed.kind === 'suite') {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+		// Only flag non-async functions with a block body (arrow shorthand already returns)
+		if (!callback || callback.async || callback.body.type !== 'BlockStatement') {
+			return;
+		}
+
+		const returnStatements = findReturnStatements(callback.body);
+		if (returnStatements.length === 0) {
+			return;
+		}
+
+		// Flag if any return statement returns a .then() call chain
+		for (const returnStatement of returnStatements) {
+			if (containsThen(returnStatement.argument)) {
+				return {
+					node: callback,
+					messageId: MESSAGE_ID,
+				};
+			}
+		}
+
+		// Flag if any return statement returns a variable that was assigned from a .then() call
+		for (const returnStatement of returnStatements) {
+			if (returnStatement.argument?.type !== 'Identifier') {
+				continue;
+			}
+
+			const variable = findVariable(sourceCode.getScope(returnStatement), returnStatement.argument);
+			if (!variable) {
+				continue;
+			}
+
+			const assignedFromThen = variable.defs.some(
+				definition => definition.type === 'Variable' && containsThen(definition.node.init),
+			);
+			if (assignedFromThen) {
+				return {
+					node: callback,
+					messageId: MESSAGE_ID,
+				};
+			}
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer async/await over returning a Promise.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-context-mock.js

@@ -0,0 +1,55 @@
+import {resolveImports, isGlobalMock} from './utils/node-test.js';
+
+const MESSAGE_ID = 'prefer-context-mock';
+
+const messages = {
+	[MESSAGE_ID]: 'Prefer `t.mock.{{accessor}}` over the global `mock.{{accessor}}`, which is not automatically restored between tests.',
+};
+
+// Accessors that create state which the global `mock` does not auto-restore.
+const STATEFUL_ACCESSORS = new Set(['fn', 'method', 'getter', 'setter', 'property', 'module', 'timers']);
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		let member = node.callee;
+		while (member.type === 'MemberExpression') {
+			if (isGlobalMock(member.object, imports) && !member.computed && member.property.type === 'Identifier') {
+				const accessor = member.property.name;
+				if (STATEFUL_ACCESSORS.has(accessor)) {
+					return {
+						node,
+						messageId: MESSAGE_ID,
+						data: {accessor},
+					};
+				}
+
+				return;
+			}
+
+			member = member.object;
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Prefer the test context `t.mock` over the global `mock`.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-diagnostic.js

@@ -0,0 +1,94 @@
+import {resolveImports, createContextTracker} from './utils/node-test.js';
+
+const MESSAGE_ID_ERROR = 'prefer-diagnostic/error';
+const MESSAGE_ID_SUGGESTION = 'prefer-diagnostic/suggestion';
+
+const messages = {
+	[MESSAGE_ID_ERROR]: 'Prefer `{{context}}.diagnostic()` over `console.{{method}}()` inside a test, so the message is attached to the test as a TAP diagnostic.',
+	[MESSAGE_ID_SUGGESTION]: 'Replace with `{{context}}.diagnostic()`.',
+};
+
+const CONSOLE_METHODS = new Set(['log', 'info', 'debug']);
+
+/** @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 => {
+		tracker.update(node);
+
+		const {callee} = node;
+		if (
+			callee.type !== 'MemberExpression'
+			|| callee.computed
+			|| callee.object.type !== 'Identifier'
+			|| callee.object.name !== 'console'
+			|| callee.property.type !== 'Identifier'
+			|| !CONSOLE_METHODS.has(callee.property.name)
+		) {
+			return;
+		}
+
+		const contextName = tracker.current();
+		if (!contextName) {
+			return;
+		}
+
+		// The context parameter is only in scope inside the test callback. Skip console calls in the
+		// title/options arguments (visited before the callback), where the context does not exist.
+		const callback = tracker.currentCallback();
+		const [callStart, callEnd] = context.sourceCode.getRange(callback);
+		const [consoleStart] = context.sourceCode.getRange(node);
+		if (consoleStart < callStart || consoleStart >= callEnd) {
+			return;
+		}
+
+		const method = callee.property.name;
+		const data = {context: contextName, method};
+		const problem = {
+			node: callee,
+			messageId: MESSAGE_ID_ERROR,
+			data,
+		};
+
+		// `diagnostic()` takes a single message, so only suggest a rewrite for a single argument.
+		if (node.arguments.length === 1) {
+			problem.suggest = [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					data,
+					fix: fixer => fixer.replaceText(callee, `${contextName}.diagnostic`),
+				},
+			];
+		}
+
+		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 `diagnostic()` over `console` inside tests.',
+			recommended: false,
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;