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

package/rules/no-conditional-assertion.js

@@ -0,0 +1,108 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestCallback,
+	getSubtestReceiver,
+	parseAssertionCall,
+	createContextTracker,
+	isAssertionCallWithSupportedContext,
+} 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 = [];
+	const tracker = createContextTracker(imports, {trackHooks: true});
+
+	context.on('CallExpression', node => {
+		tracker.update(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) || !isAssertionCallWithSupportedContext(node, tracker)) {
+			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 => {
+		tracker.leave(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) {
+			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, suites, and hooks.',
+			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((a, b) => a.localeCompare(b)).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-constant-assertion.js

@@ -0,0 +1,218 @@
+import {findVariable, getStaticValue} from '@eslint-community/eslint-utils';
+import {
+	MODIFIERS,
+	resolveImports,
+	parseAssertionCall,
+	parseTestCall,
+	getSubtestReceiver,
+	getTestCallback,
+} from './utils/node-test.js';
+import {isRegexLiteral} from './ast/index.js';
+import unwrapTypeScriptExpression from './utils/unwrap-typescript-expression.js';
+
+const MESSAGE_ID = 'no-constant-assertion';
+
+const messages = {
+	[MESSAGE_ID]: 'This assertion has a constant outcome, so it does not test code behavior.',
+};
+
+const COMPARISON_METHODS = new Set([
+	'equal',
+	'notEqual',
+	'strictEqual',
+	'notStrictEqual',
+	'deepEqual',
+	'notDeepEqual',
+	'deepStrictEqual',
+	'notDeepStrictEqual',
+]);
+
+const MATCH_METHODS = new Set([
+	'match',
+	'doesNotMatch',
+]);
+
+function isStaticArgument(node, sourceCode) {
+	if (!node || node.type === 'SpreadElement') {
+		return false;
+	}
+
+	node = unwrapTypeScriptExpression(node);
+
+	return getStaticValue(node, sourceCode.getScope(node)) !== null;
+}
+
+function areStaticArguments(nodes, sourceCode) {
+	return nodes.every(node => isStaticArgument(node, sourceCode));
+}
+
+function isStaticRegexLiteral(node) {
+	if (!node || node.type === 'SpreadElement') {
+		return false;
+	}
+
+	return isRegexLiteral(unwrapTypeScriptExpression(node));
+}
+
+// `parseTestCall` already guarantees the callee root is an imported `node:test` binding, so no
+// separate binding check is needed here (and doing one on the raw callee would miss TypeScript
+// wrappers like `(test as any)(…)`).
+function isNodeTestCall(node, imports) {
+	const parsed = parseTestCall(node, imports);
+	return Boolean(parsed)
+		&& (parsed.kind === 'test' || parsed.kind === 'hook')
+		&& !(parsed.kind === 'hook' && parsed.modifiers.length > 0)
+		&& parsed.modifiers.every(modifier => MODIFIERS.has(modifier.name));
+}
+
+function getContextAssertReceiver(node) {
+	const {callee} = node;
+	if (
+		callee.type !== 'MemberExpression'
+		|| callee.computed
+		|| callee.object.type !== 'MemberExpression'
+		|| callee.object.computed
+		|| callee.object.object.type !== 'Identifier'
+		|| callee.object.property.type !== 'Identifier'
+		|| callee.object.property.name !== 'assert'
+	) {
+		return undefined;
+	}
+
+	return callee.object.object;
+}
+
+function isInsideNode(node, ancestor) {
+	let current = node;
+	while (current) {
+		if (current === ancestor) {
+			return true;
+		}
+
+		current = current.parent;
+	}
+
+	return false;
+}
+
+function getContextParameterVariable(callback, sourceCode) {
+	const parameter = callback.params[0];
+	if (parameter?.type !== 'Identifier') {
+		return undefined;
+	}
+
+	return sourceCode
+		.getDeclaredVariables(callback)
+		.find(variable => variable.identifiers.includes(parameter));
+}
+
+function isSubtestCall(node, activeContexts, sourceCode) {
+	const receiver = getSubtestReceiver(node);
+	if (!receiver) {
+		return false;
+	}
+
+	const receiverVariable = findVariable(sourceCode.getScope(receiver), receiver);
+	return activeContexts.some(({variable}) => receiverVariable === variable);
+}
+
+function getTestContextCallback(node, imports, activeContexts, sourceCode) {
+	if (isNodeTestCall(node, imports) || isSubtestCall(node, activeContexts, sourceCode)) {
+		return getTestCallback(node);
+	}
+}
+
+function isUntrackedContextAssertCall(node, activeContexts, sourceCode) {
+	const receiver = getContextAssertReceiver(node);
+	if (!receiver) {
+		return false;
+	}
+
+	const receiverVariable = findVariable(sourceCode.getScope(receiver), receiver);
+	return activeContexts.every(({callback, variable}) =>
+		!isInsideNode(receiver, callback)
+		|| receiverVariable !== variable);
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isAssertOrTestFile) {
+		return;
+	}
+
+	const {sourceCode} = context;
+	const activeContexts = [];
+	const trackedTestCalls = new Set();
+
+	context.on('CallExpression', node => {
+		const callback = getTestContextCallback(node, imports, activeContexts, sourceCode);
+		if (callback) {
+			const variable = getContextParameterVariable(callback, sourceCode);
+			if (variable) {
+				activeContexts.push({callback, variable});
+				trackedTestCalls.add(node);
+			}
+		}
+
+		const assertion = parseAssertionCall(node, imports);
+		if (!assertion) {
+			return;
+		}
+
+		if (getContextAssertReceiver(node) && isUntrackedContextAssertCall(node, activeContexts, sourceCode)) {
+			return;
+		}
+
+		if (node.arguments.some(argument => argument.type === 'SpreadElement')) {
+			return;
+		}
+
+		const {method} = assertion;
+		const [firstArgument, secondArgument] = node.arguments;
+		let isConstant = false;
+
+		if (method === 'ok' || method === 'ifError') {
+			isConstant = isStaticArgument(firstArgument, sourceCode);
+		} else if (COMPARISON_METHODS.has(method)) {
+			isConstant = areStaticArguments([firstArgument, secondArgument], sourceCode);
+		} else if (MATCH_METHODS.has(method)) {
+			isConstant = isStaticArgument(firstArgument, sourceCode) && isStaticRegexLiteral(secondArgument);
+		}
+
+		if (!isConstant) {
+			return;
+		}
+
+		return {
+			node,
+			messageId: MESSAGE_ID,
+		};
+	});
+
+	context.onExit('CallExpression', node => {
+		if (!trackedTestCalls.has(node)) {
+			return;
+		}
+
+		trackedTestCalls.delete(node);
+		activeContexts.pop();
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'problem',
+		docs: {
+			description: 'Disallow assertions with constant outcomes.',
+			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;