eslint-node-test 0.0.1

package/rules/no-async-fn-without-await.js

@@ -0,0 +1,74 @@
+import {resolveImports, parseTestCall, getTestCallback} from './utils/node-test.js';
+import containsSuspensionPoint from './utils/contains-suspension-point.js';
+
+const MESSAGE_ID = 'no-async-fn-without-await/error';
+const MESSAGE_ID_SUGGESTION = 'no-async-fn-without-await/suggestion';
+
+const messages = {
+	[MESSAGE_ID]: 'Async test/hook function has no `await` expression.',
+	[MESSAGE_ID_SUGGESTION]: 'Remove the `async` keyword.',
+};
+
+/** @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);
+		// Suites are handled by `no-async-describe`, which forbids an async `describe` callback
+		// outright (the runner never awaits it), so skip them here to avoid a duplicate report.
+		if (!parsed || parsed.kind === 'suite') {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+		if (!callback?.async) {
+			return;
+		}
+
+		// Check if the async function body contains any suspension point at its own level.
+		// containsSuspensionPoint does not descend into nested functions.
+		if (containsSuspensionPoint(callback.body, sourceCode.visitorKeys)) {
+			return;
+		}
+
+		const asyncToken = sourceCode.getFirstToken(callback, token => token.value === 'async');
+
+		return {
+			node: asyncToken,
+			messageId: MESSAGE_ID,
+			suggest: [
+				{
+					messageId: MESSAGE_ID_SUGGESTION,
+					/** @param {import('eslint').Rule.RuleFixer} fixer */
+					fix(fixer) {
+						const nextToken = sourceCode.getTokenAfter(asyncToken);
+						return fixer.removeRange([sourceCode.getRange(asyncToken)[0], sourceCode.getRange(nextToken)[0]]);
+					},
+				},
+			],
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Disallow async test/hook functions that have no `await` expression.',
+			recommended: 'unopinionated',
+		},
+		hasSuggestions: true,
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-callback-and-promise.js

@@ -0,0 +1,56 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestCallback,
+	getEffectiveArity,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-callback-and-promise';
+
+const messages = {
+	[MESSAGE_ID]: 'A {{kind}} cannot use both a callback parameter and a Promise; this `async` function also declares a callback.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		// Suite (`describe`/`suite`) callbacks receive a `SuiteContext`, never a `done` callback.
+		if (parsed?.kind !== 'test' && parsed?.kind !== 'hook') {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+		if (!callback?.async || getEffectiveArity(callback.params) < 2) {
+			return;
+		}
+
+		return {
+			node: callback.params[1],
+			messageId: MESSAGE_ID,
+			data: {kind: parsed.kind === 'hook' ? 'hook' : 'test'},
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow a test or hook from using both a callback and a Promise.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-commented-tests.js

@@ -0,0 +1,59 @@
+import getComments from './utils/get-comments.js';
+
+const MESSAGE_ID = 'no-commented-tests/error';
+
+const messages = {
+	[MESSAGE_ID]: 'Use `.skip()` or remove the commented-out test instead of commenting it out.',
+};
+
+// Matches lines that look like commented-out test/hook calls from node:test.
+// Anchored at start-of-line (with optional leading whitespace and block comment asterisk).
+// Matches: test(, it(, describe(, suite(, before(, after(, beforeEach(, afterEach(
+// and dotted modifier variants like test.only(, it.skip(, describe.todo(, etc.
+// Only the real node:test modifiers are allowed in the chain, so unrelated method calls like
+// `it.each(` or `test.config(` are not misidentified as commented-out tests.
+const COMMENTED_TEST_PATTERN = /^\s*\*?\s*(?:test|it|describe|suite|before|after|beforeEach|afterEach)\s*(?:\.\s*(?:only|skip|todo)\s*)*\(/v;
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	context.on('Program:exit', () => {
+		for (const comment of getComments(context)) {
+			// Skip JSDoc-style block comments (/** ... */).
+			if (comment.type === 'Block' && context.sourceCode.getText(comment).startsWith('/**')) {
+				continue;
+			}
+
+			const lines = comment.value.split('\n');
+			const commentStartLine = context.sourceCode.getLoc(comment).start.line;
+			for (const [index, line] of lines.entries()) {
+				if (COMMENTED_TEST_PATTERN.test(line)) {
+					context.report({
+						loc: {
+							line: commentStartLine + index,
+							column: 0,
+						},
+						messageId: MESSAGE_ID,
+					});
+					break;
+				}
+			}
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Disallow commented-out tests.',
+			recommended: false,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-conditional-assertion.js

@@ -0,0 +1,101 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestCallback,
+	getSubtestReceiver,
+	parseAssertionCall,
+} from './utils/node-test.js';
+import isConditionalBranch from './utils/is-conditional-branch.js';
+
+const MESSAGE_ID = 'no-conditional-assertion/error';
+
+const messages = {
+	[MESSAGE_ID]: 'Assertions should not be placed inside conditionals, as they may never execute.',
+};
+
+/*
+The callback that bounds an assertion's scope: a test/hook call, or a subtest (`t.test(…)`, a method
+call rather than an imported binding). Returns `undefined` for suites (their bodies only register
+tests, so conditional assertions there are not this rule's concern) and non-test calls.
+*/
+function getScopeBoundaryCallback(node, imports) {
+	const parsed = parseTestCall(node, imports);
+	if (parsed) {
+		return parsed.kind === 'test' || parsed.kind === 'hook' ? getTestCallback(node) : undefined;
+	}
+
+	return getSubtestReceiver(node) === undefined ? undefined : getTestCallback(node);
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// Stack of callback function nodes for the currently open test/hook/subtest scopes. An assertion
+	// is checked against the conditionals up to its nearest enclosing scope, so a subtest's body is
+	// scoped to the subtest, not to a conditional wrapping the subtest call in the outer test.
+	const testCallbackStack = [];
+
+	context.on('CallExpression', node => {
+		const boundaryCallback = getScopeBoundaryCallback(node, imports);
+		if (boundaryCallback) {
+			testCallbackStack.push(boundaryCallback);
+			return;
+		}
+
+		// Not a test/subtest call — check if it's an assertion inside a test.
+		if (testCallbackStack.length === 0) {
+			return;
+		}
+
+		if (!parseAssertionCall(node, imports)) {
+			return;
+		}
+
+		const testCallback = testCallbackStack.at(-1);
+
+		// Walk ancestors from this assertion up to (but not including) the test callback.
+		let child = node;
+		let current = node.parent;
+
+		while (current && current !== testCallback) {
+			// Loops count here: an assertion in a loop body may run zero or many times.
+			if (isConditionalBranch(current, child, {includeLoops: true})) {
+				return {
+					node,
+					messageId: MESSAGE_ID,
+				};
+			}
+
+			child = current;
+			current = current.parent;
+		}
+	});
+
+	context.onExit('CallExpression', node => {
+		const boundaryCallback = getScopeBoundaryCallback(node, imports);
+		if (boundaryCallback && testCallbackStack.at(-1) === boundaryCallback) {
+			testCallbackStack.pop();
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow assertions inside conditional code within a test.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-conditional-in-test.js

@@ -0,0 +1,66 @@
+import {resolveImports, parseTestCall, getTestCallback} from './utils/node-test.js';
+import isFunction from './ast/is-function.js';
+
+const MESSAGE_ID = 'no-conditional-in-test';
+
+const messages = {
+	[MESSAGE_ID]: 'Avoid conditional logic in a test; a test should run the same way every time.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// Callbacks of test/hook calls. Conditionals inside a `describe` body are about test
+	// registration (see `no-conditional-tests`), so suites are excluded here.
+	const testCallbacks = new Set();
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (parsed?.kind !== 'test' && parsed?.kind !== 'hook') {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+		if (callback) {
+			testCallbacks.add(callback);
+		}
+	});
+
+	const report = node => {
+		// The conditional must sit directly in the test body, not in a sibling argument like the
+		// options object (`{skip: a ? … : …}`) or inside a nested helper function.
+		let enclosing = node.parent;
+		while (enclosing && !isFunction(enclosing)) {
+			enclosing = enclosing.parent;
+		}
+
+		if (enclosing && testCallbacks.has(enclosing)) {
+			return {node, messageId: MESSAGE_ID};
+		}
+	};
+
+	context.on('IfStatement', report);
+	context.on('SwitchStatement', report);
+	context.on('ConditionalExpression', report);
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Disallow conditional logic inside tests.',
+			recommended: false,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-conditional-tests.js

@@ -0,0 +1,75 @@
+import {resolveImports, parseTestCall} from './utils/node-test.js';
+import isConditionalBranch from './utils/is-conditional-branch.js';
+import isFunction from './ast/is-function.js';
+
+const MESSAGE_ID = 'no-conditional-tests';
+
+const messages = {
+	[MESSAGE_ID]: 'Do not register a {{kind}} conditionally; it makes the suite structure non-deterministic.',
+};
+
+/*
+Whether a conditional construct guards `node`, searching up to the enclosing function. Loops are
+intentionally ignored: iterating to register tests is the idiomatic way to write table-driven tests
+in `node:test`.
+*/
+function isConditionallyRegistered(node) {
+	let current = node;
+	let {parent} = current;
+	while (parent) {
+		if (isFunction(parent)) {
+			return false;
+		}
+
+		if (isConditionalBranch(parent, current)) {
+			return true;
+		}
+
+		current = parent;
+		({parent} = current);
+	}
+
+	return false;
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (parsed?.kind !== 'test' && parsed?.kind !== 'suite') {
+			return;
+		}
+
+		if (!isConditionallyRegistered(node)) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {kind: parsed.kind},
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow conditionally registering tests and suites.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-conflicting-modifiers.js

@@ -0,0 +1,73 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestOptions,
+	findEnabledOptionsProperty,
+	MODIFIERS,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-conflicting-modifiers';
+
+const messages = {
+	[MESSAGE_ID]: 'Conflicting modifiers {{modifiers}}; `node:test` applies only one.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		const active = new Set();
+
+		// Chained form: `test.skip.only(…)`.
+		for (const modifier of parsed.modifiers) {
+			if (MODIFIERS.has(modifier.name)) {
+				active.add(modifier.name);
+			}
+		}
+
+		// Options form: `test('t', {skip: true, only: true}, …)`.
+		const options = getTestOptions(node);
+		for (const name of MODIFIERS) {
+			if (findEnabledOptionsProperty(options, name)) {
+				active.add(name);
+			}
+		}
+
+		if (active.size < 2) {
+			return;
+		}
+
+		const modifiers = [...active].toSorted().map(name => `\`${name}\``).join(', ');
+		return {
+			node,
+			messageId: MESSAGE_ID,
+			data: {modifiers},
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow conflicting `only`/`skip`/`todo` modifiers.',
+			recommended: 'unopinionated',
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-done-callback.js

@@ -0,0 +1,58 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestCallback,
+	getEffectiveArity,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-done-callback';
+
+const messages = {
+	[MESSAGE_ID]: 'Use `async`/`await` or return a Promise instead of the `{{name}}` callback parameter.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		// Suite (`describe`/`suite`) callbacks receive a `SuiteContext`, never a `done` callback.
+		if (parsed?.kind !== 'test' && parsed?.kind !== 'hook') {
+			return;
+		}
+
+		const callback = getTestCallback(node);
+		// A declared second parameter is the `done` callback `node:test` passes based on arity.
+		if (!callback || getEffectiveArity(callback.params) < 2) {
+			return;
+		}
+
+		const parameter = callback.params[1];
+		return {
+			node: parameter,
+			messageId: MESSAGE_ID,
+			data: {name: parameter.type === 'Identifier' ? parameter.name : 'done'},
+		};
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Disallow callback (`done`) parameters in tests and hooks.',
+			recommended: false,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/no-duplicate-hooks.js

@@ -0,0 +1,75 @@
+import {resolveImports, parseTestCall, getTestCallback} from './utils/node-test.js';
+
+const MESSAGE_ID = 'no-duplicate-hooks';
+
+const messages = {
+	[MESSAGE_ID]: 'Duplicate `{{name}}` hook in the same scope.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// Stack of scopes; each scope tracks the hook names already declared in it.
+	const scopeStack = [new Set()];
+	// Calls whose callback opened a scope, so we can pop on exit.
+	const pushedCalls = new Set();
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		let problem;
+		if (parsed.kind === 'hook') {
+			const scope = scopeStack.at(-1);
+			if (scope.has(parsed.name)) {
+				problem = {
+					node,
+					messageId: MESSAGE_ID,
+					data: {name: parsed.name},
+				};
+			} else {
+				scope.add(parsed.name);
+			}
+		}
+
+		if (parsed.kind === 'test' || parsed.kind === 'suite') {
+			const callback = getTestCallback(node);
+			if (callback) {
+				scopeStack.push(new Set());
+				pushedCalls.add(node);
+			}
+		}
+
+		return problem;
+	});
+
+	context.onExit('CallExpression', node => {
+		if (pushedCalls.has(node)) {
+			pushedCalls.delete(node);
+			scopeStack.pop();
+		}
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Disallow duplicate hooks within the same scope.',
+			recommended: true,
+		},
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;