eslint-node-test 0.0.1

package/rules/no-unawaited-rejects.js

@@ -0,0 +1,74 @@
+import {resolveImports, parseAssertionCall} from './utils/node-test.js';
+import {getEnclosingFunction} from './utils/index.js';
+
+const MESSAGE_ID = 'no-unawaited-rejects/error';
+
+const messages = {
+	[MESSAGE_ID]: '`assert.{{method}}()` must be awaited or returned.',
+};
+
+const REJECTS_METHODS = new Set(['rejects', 'doesNotReject']);
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+
+	if (!imports.isAssertOrTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseAssertionCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		if (!REJECTS_METHODS.has(parsed.method)) {
+			return;
+		}
+
+		// The call must be an ExpressionStatement (i.e. bare call, not awaited/returned/assigned).
+		const {parent} = node;
+		if (!parent || parent.type !== 'ExpressionStatement') {
+			return;
+		}
+
+		const enclosingFunction = getEnclosingFunction(node);
+		const isInAsyncFunction = enclosingFunction?.async === true;
+
+		if (isInAsyncFunction) {
+			// Can autofix with `await`.
+			return {
+				node,
+				messageId: MESSAGE_ID,
+				data: {method: parsed.method},
+				fix: fixer => fixer.insertTextBefore(node, 'await '),
+			};
+		}
+
+		// Not in an async function — report without a fix (await would be a syntax error here).
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {method: parsed.method},
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Require `assert.rejects()`/`assert.doesNotReject()` to be awaited or returned.',
+			recommended: 'unopinionated',
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-unawaited-subtest.js

@@ -0,0 +1,66 @@
+import {resolveImports, createContextTracker, getSubtestReceiver} from './utils/node-test.js';
+import {getEnclosingFunction} from './utils/index.js';
+
+const MESSAGE_ID = 'no-unawaited-subtest';
+
+const messages = {
+	[MESSAGE_ID]: 'Subtest `{{name}}.test()` must be awaited or returned, otherwise it is cancelled when the parent test finishes.',
+};
+
+/** @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 => {
+		// Whether this is a floating subtest must be decided against the current stack,
+		// before this call pushes its own context.
+		const subtest = tracker.isSubtestCall(node);
+
+		let problem;
+		if (subtest && node.parent.type === 'ExpressionStatement') {
+			const {name} = getSubtestReceiver(node);
+			const enclosingFunction = getEnclosingFunction(node);
+
+			problem = {
+				node,
+				messageId: MESSAGE_ID,
+				data: {name},
+			};
+
+			// `await` is only valid (and a behavior-preserving fix) inside an async function.
+			if (enclosingFunction?.async) {
+				problem.fix = fixer => fixer.insertTextBefore(node, 'await ');
+			}
+		}
+
+		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 with the test context to be awaited or returned.',
+			recommended: true,
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-unknown-test-options.js

@@ -0,0 +1,77 @@
+import {resolveImports, parseTestCall, getTestOptions} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-unknown-test-options';
+
+const messages = {
+	[MESSAGE_ID]: '`{{name}}` is not a recognized {{kind}} option.',
+};
+
+/*
+The option keys `node:test` recognizes. An unknown key is silently ignored, so a typo like
+`{skp: true}` quietly runs the test as normal. This list tracks the runner and may need
+updating as `node:test` gains options.
+*/
+const TEST_OPTIONS = new Set(['concurrency', 'expectFailure', 'only', 'plan', 'signal', 'skip', 'tags', 'timeout', 'todo']);
+const HOOK_OPTIONS = new Set(['signal', 'timeout']);
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', function * (node) {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		const options = getTestOptions(node);
+		if (!options) {
+			return;
+		}
+
+		const known = parsed.kind === 'hook' ? HOOK_OPTIONS : TEST_OPTIONS;
+
+		for (const property of options.properties) {
+			if (property.type !== 'Property' || property.computed) {
+				continue;
+			}
+
+			let name;
+			if (property.key.type === 'Identifier') {
+				name = property.key.name;
+			} else if (property.key.type === 'Literal' && typeof property.key.value === 'string') {
+				name = property.key.value;
+			} else {
+				continue;
+			}
+
+			if (!known.has(name)) {
+				yield {
+					node: property.key,
+					messageId: MESSAGE_ID,
+					data: {name, kind: parsed.kind},
+				};
+			}
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow unknown options in test and hook option objects.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-useless-assertion.js

@@ -0,0 +1,47 @@
+import {resolveImports, parseAssertionCall} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-useless-assertion';
+
+const messages = {
+	[MESSAGE_ID]: '`{{method}}()` is not useful. It catches an error only to rethrow it, so call the code directly instead.',
+};
+
+const USELESS_METHODS = new Set(['doesNotThrow', 'doesNotReject']);
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isAssertOrTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseAssertionCall(node, imports);
+		if (!parsed || !USELESS_METHODS.has(parsed.method)) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {method: parsed.method},
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Disallow `assert.doesNotThrow()` and `assert.doesNotReject()`.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/prefer-assert-match.js

@@ -0,0 +1,245 @@
+import {resolveImports, parseAssertionCall} 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(...)`
+	if (
+		(node.type === 'NewExpression' || node.type === 'CallExpression')
+		&& node.callee.type === 'Identifier'
+		&& node.callee.name === 'RegExp'
+	) {
+		return true;
+	}
+
+	return false;
+}
+
+/*
+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 a non-parenthesized first argument (the rewrite replaces the inner
+node, so surrounding parentheses would be left wrapping the `str, re` pair as a comma expression).
+*/
+function canAutofix(node, context) {
+	return node.callee.type === 'MemberExpression'
+		&& context.sourceCode.getCommentsInside(node).length === 0
+		&& !isParenthesized(node.arguments[0], 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 negated = method === 'notStrictEqual' || method === 'notEqual';
+	// `strictEqual(re.test(str), true)` asserts a match; negating the method or comparing to
+	// `false` each flip the meaning.
+	const matches = (booleanLiteral.value === true) !== negated;
+	const assertMethod = matches ? '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;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseAssertionCall(node, imports);
+		if (!parsed) {
+			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 (method === 'strictEqual' || method === 'equal' || method === 'notStrictEqual' || method === 'notEqual') {
+			return getEqualityProblem(node, method, context);
+		}
+	});
+};
+
+/** @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,90 @@
+import {resolveImports, parseAssertionCall} from './utils/node-test.js';
+import containsSuspensionPoint from './utils/contains-suspension-point.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) {
+		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;