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

package/rules/no-unawaited-promise-assertion.js

@@ -0,0 +1,366 @@
+import {findVariable} from '@eslint-community/eslint-utils';
+import {
+	resolveImports,
+	parseTestCall,
+	getTestCallback,
+	parseAssertionCall,
+	getSubtestReceiver,
+	getCalleeChain,
+	MODIFIERS,
+} from './utils/node-test.js';
+import {isFunction} from './ast/index.js';
+import {getEnclosingFunction, unwrapTypeScriptExpression, isTypeScriptExpressionWrapper} from './utils/index.js';
+
+const MESSAGE_ID = 'no-unawaited-promise-assertion';
+
+const PROMISE_METHODS = new Set(['then', 'catch', 'finally']);
+
+const messages = {
+	[MESSAGE_ID]: 'Assertion in a floating `{{method}}()` callback is not awaited by the test. Await or return the Promise chain.',
+};
+
+function unwrapChainExpression(node) {
+	node = unwrapTypeScriptExpression(node);
+	return node?.type === 'ChainExpression' ? node.expression : node;
+}
+
+function getFloatingExpression(node) {
+	let expression = node;
+	let {parent} = node;
+
+	while (parent?.type === 'ChainExpression' || isTypeScriptExpressionWrapper(parent)) {
+		expression = parent;
+		parent = parent.parent;
+	}
+
+	if (parent?.type === 'UnaryExpression' && parent.operator === 'void') {
+		const unaryExpression = parent;
+		parent = parent.parent;
+
+		if (parent?.type === 'ExpressionStatement') {
+			return {
+				expression: unaryExpression.argument,
+				canFix: false,
+			};
+		}
+
+		return undefined;
+	}
+
+	if (parent?.type !== 'ExpressionStatement') {
+		return undefined;
+	}
+
+	return {
+		expression,
+		canFix: true,
+	};
+}
+
+function getPromiseChainCalls(node) {
+	const calls = [];
+	node = unwrapChainExpression(node);
+
+	while (node?.type === 'CallExpression') {
+		const callee = unwrapChainExpression(node.callee);
+		if (
+			callee?.type !== 'MemberExpression'
+			|| callee.computed
+			|| callee.property.type !== 'Identifier'
+		) {
+			break;
+		}
+
+		if (!PROMISE_METHODS.has(callee.property.name)) {
+			if (
+				calls.length > 0
+				&& unwrapChainExpression(callee.object)?.type === 'CallExpression'
+			) {
+				return [];
+			}
+
+			return calls;
+		}
+
+		calls.push({
+			node,
+			method: callee.property.name,
+		});
+
+		node = unwrapChainExpression(callee.object);
+	}
+
+	return calls;
+}
+
+function getPromiseCallbackArguments(call) {
+	const {method} = call;
+	const argumentIndexes = method === 'then' ? [0, 1] : [0];
+
+	return argumentIndexes
+		.map(index => unwrapTypeScriptExpression(call.node.arguments[index]))
+		.filter(argument => argument && isFunction(argument));
+}
+
+function getContextParameter(callback) {
+	const parameter = callback.params[0];
+	return parameter?.type === 'Identifier' ? parameter : undefined;
+}
+
+function getContextAssertReceiver(node) {
+	const {callee} = node;
+	if (
+		callee.type === 'MemberExpression'
+		&& callee.object.type === 'MemberExpression'
+		&& !callee.object.computed
+		&& callee.object.object.type === 'Identifier'
+		&& callee.object.property.type === 'Identifier'
+		&& callee.object.property.name === 'assert'
+	) {
+		return callee.object.object;
+	}
+
+	return undefined;
+}
+
+function isTrackedContextAssertCall(node, contextParameters, sourceCode) {
+	const receiver = getContextAssertReceiver(node);
+	if (!receiver) {
+		return false;
+	}
+
+	const variable = findVariable(sourceCode.getScope(receiver), receiver);
+	return variable?.identifiers.some(identifier => contextParameters.includes(identifier)) === true;
+}
+
+function isTrackedSubtestCall(node, contextParameters, sourceCode) {
+	const receiver = getSubtestReceiver(node);
+	if (!receiver) {
+		return false;
+	}
+
+	const variable = findVariable(sourceCode.getScope(receiver), receiver);
+	return variable?.identifiers.some(identifier => contextParameters.includes(identifier)) === true;
+}
+
+function isImportBinding(identifier, sourceCode) {
+	const variable = findVariable(sourceCode.getScope(identifier), identifier);
+	return variable?.defs.some(definition => definition.type === 'ImportBinding') === true;
+}
+
+function isImportedTestCall(node, sourceCode) {
+	const root = getCalleeChain(node.callee)?.root;
+	return Boolean(root) && isImportBinding(root, sourceCode);
+}
+
+function hasOnlyTestModifiers(parsed) {
+	return parsed.modifiers.every(modifier => MODIFIERS.has(modifier.name));
+}
+
+function getImportedAssertReference(node, imports) {
+	const {callee} = node;
+
+	if (
+		callee.type === 'Identifier'
+		&& (
+			imports.assertNamed.has(callee.name)
+			|| imports.assertNamespace.has(callee.name)
+		)
+	) {
+		return callee;
+	}
+
+	if (
+		callee.type === 'MemberExpression'
+		&& callee.object.type === 'Identifier'
+		&& imports.assertNamespace.has(callee.object.name)
+	) {
+		return callee.object;
+	}
+
+	return undefined;
+}
+
+function parseScopedAssertionCall(node, imports, contextParameters, sourceCode) {
+	const parsed = parseAssertionCall(node, imports);
+	if (!parsed) {
+		return undefined;
+	}
+
+	if (getContextAssertReceiver(node)) {
+		return isTrackedContextAssertCall(node, contextParameters, sourceCode) ? parsed : undefined;
+	}
+
+	const importedAssertReference = getImportedAssertReference(node, imports);
+	return importedAssertReference && isImportBinding(importedAssertReference, sourceCode) ? parsed : undefined;
+}
+
+function findAssertion(node, state) {
+	const {
+		imports,
+		contextParameters,
+		sourceCode,
+		visitorKeys,
+	} = state;
+
+	node = unwrapTypeScriptExpression(node);
+	if (!node) {
+		return undefined;
+	}
+
+	if (isFunction(node)) {
+		return undefined;
+	}
+
+	if (
+		node.type === 'CallExpression'
+		&& parseScopedAssertionCall(node, imports, contextParameters, sourceCode)
+	) {
+		return node;
+	}
+
+	for (const key of visitorKeys[node.type] ?? []) {
+		const child = node[key];
+		for (const childNode of Array.isArray(child) ? child : [child]) {
+			const assertion = childNode?.type && findAssertion(childNode, state);
+			if (assertion) {
+				return assertion;
+			}
+		}
+	}
+
+	return undefined;
+}
+
+function getAssertionProblems(chainCalls, state) {
+	return chainCalls.flatMap(call => getPromiseCallbackArguments(call).flatMap(callback => {
+		const assertion = findAssertion(callback.body, state);
+		if (!assertion) {
+			return [];
+		}
+
+		return [{
+			node: assertion,
+			messageId: MESSAGE_ID,
+			data: {
+				method: call.method,
+			},
+		}];
+	}));
+}
+
+function getTestBoundaryCallback(node, imports, contextParameters, sourceCode) {
+	const parsed = parseTestCall(node, imports);
+	if (parsed) {
+		if (parsed.kind !== 'test' && parsed.kind !== 'hook') {
+			return undefined;
+		}
+
+		if (!hasOnlyTestModifiers(parsed)) {
+			return undefined;
+		}
+
+		if (!isImportedTestCall(node, sourceCode)) {
+			return undefined;
+		}
+
+		return getTestCallback(node);
+	}
+
+	return isTrackedSubtestCall(node, contextParameters, sourceCode) ? getTestCallback(node) : undefined;
+}
+
+function hasStaticBlockBetween(node, boundary) {
+	for (let current = node; current && current !== boundary; current = current.parent) {
+		if (current.type === 'StaticBlock') {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const {sourceCode} = context;
+	const {visitorKeys} = sourceCode;
+	const callbackStack = [];
+
+	context.on('CallExpression', node => {
+		const contextParameters = callbackStack.map(frame => frame.contextParameter).filter(Boolean);
+		const boundaryCallback = getTestBoundaryCallback(node, imports, contextParameters, sourceCode);
+
+		if (boundaryCallback) {
+			callbackStack.push({
+				node,
+				callback: boundaryCallback,
+				contextParameter: getContextParameter(boundaryCallback),
+			});
+			return;
+		}
+
+		const activeCallback = callbackStack.at(-1)?.callback;
+		if (!activeCallback || getEnclosingFunction(node) !== activeCallback) {
+			return;
+		}
+
+		const floatingExpression = getFloatingExpression(node);
+		if (!floatingExpression) {
+			return;
+		}
+
+		const chainCalls = getPromiseChainCalls(floatingExpression.expression);
+		if (chainCalls.length === 0) {
+			return;
+		}
+
+		const problems = getAssertionProblems(chainCalls, {
+			imports,
+			contextParameters,
+			sourceCode,
+			visitorKeys,
+		});
+		if (problems.length === 0) {
+			return;
+		}
+
+		if (
+			floatingExpression.canFix
+			&& activeCallback.async
+			&& !hasStaticBlockBetween(floatingExpression.expression, activeCallback)
+		) {
+			problems[0].fix = fixer => fixer.insertTextBefore(floatingExpression.expression, 'await ');
+		}
+
+		return problems;
+	});
+
+	context.onExit('CallExpression', node => {
+		if (callbackStack.at(-1)?.node === node) {
+			callbackStack.pop();
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow assertions inside unawaited Promise callbacks.',
+			recommended: 'unopinionated',
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-unawaited-rejects.js

@@ -0,0 +1,87 @@
+import {
+	resolveImports,
+	parseAssertionCall,
+	createContextTracker,
+	isAssertionCallWithSupportedContext,
+} 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;
+	}
+
+	const tracker = createContextTracker(imports, {trackHooks: true});
+
+	context.on('CallExpression', node => {
+		tracker.update(node);
+
+		const parsed = parseAssertionCall(node, imports);
+		if (!parsed || !isAssertionCallWithSupportedContext(node, tracker)) {
+			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},
+		};
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @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,60 @@
+import {
+	resolveImports,
+	parseAssertionCall,
+	createContextTracker,
+	isAssertionCallWithSupportedContext,
+} 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;
+	}
+
+	const tracker = createContextTracker(imports, {trackHooks: true});
+
+	context.on('CallExpression', node => {
+		tracker.update(node);
+
+		const parsed = parseAssertionCall(node, imports);
+		if (!parsed || !USELESS_METHODS.has(parsed.method) || !isAssertionCallWithSupportedContext(node, tracker)) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {method: parsed.method},
+		};
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @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;