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

package/rules/consistent-modifier-style.js

@@ -0,0 +1,95 @@
+import {
+	resolveImports,
+	parseTestCall,
+	getTestOptions,
+	findOptionsProperty,
+	MODIFIERS,
+} from './utils/node-test.js';
+
+const MESSAGE_ID_PREFER_CHAINED = 'consistent-modifier-style/prefer-chained';
+const MESSAGE_ID_PREFER_OPTIONS = 'consistent-modifier-style/prefer-options';
+
+const messages = {
+	[MESSAGE_ID_PREFER_CHAINED]: 'Use the chained modifier `.{{modifier}}` instead of the `{{modifier}}` option.',
+	[MESSAGE_ID_PREFER_OPTIONS]: 'Use the `{{modifier}}` option instead of the chained `.{{modifier}}`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const {style} = context.options[0];
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		// Only tests and suites have `.only`/`.skip`/`.todo`; hooks have no chained modifier form.
+		if (parsed.kind === 'hook') {
+			return;
+		}
+
+		if (style === 'chained') {
+			// Flag modifiers expressed through the options object, but only `modifier: true`. A string
+			// reason (`{skip: 'why'}`), `false`, or a dynamic value has no equivalent chained form.
+			const options = getTestOptions(node);
+			const problems = [];
+			for (const modifier of MODIFIERS) {
+				const property = findOptionsProperty(options, modifier);
+				if (property?.value.type === 'Literal' && property.value.value === true) {
+					problems.push({
+						node: property,
+						messageId: MESSAGE_ID_PREFER_CHAINED,
+						data: {modifier},
+					});
+				}
+			}
+
+			return problems;
+		}
+
+		// `style === 'options'` — flag chained modifiers. `parsed.modifiers` includes any member
+		// after the test binding, so restrict to the real modifiers (`only`/`skip`/`todo`).
+		return parsed.modifiers
+			.filter(modifier => MODIFIERS.has(modifier.name))
+			.map(modifier => ({
+				node: modifier,
+				messageId: MESSAGE_ID_PREFER_OPTIONS,
+				data: {modifier: modifier.name},
+			}));
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a consistent style for test modifiers.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					style: {
+						enum: ['chained', 'options'],
+						description: 'Whether modifiers should be chained (`test.skip()`) or passed as options (`{skip: true}`).',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{style: 'chained'}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/consistent-test-context-name.js

@@ -0,0 +1,75 @@
+import {
+	resolveImports,
+	parseTestCall,
+	createContextTracker,
+	getTestCallback,
+} from './utils/node-test.js';
+
+const MESSAGE_ID = 'consistent-test-context-name';
+
+const messages = {
+	[MESSAGE_ID]: 'Name the test context parameter `{{expected}}` instead of `{{actual}}`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const expected = context.options[0].name;
+	const tracker = createContextTracker(imports);
+
+	context.on('CallExpression', node => {
+		const isSubtest = tracker.isSubtestCall(node);
+		const isTest = parseTestCall(node, imports)?.kind === 'test';
+		tracker.update(node);
+
+		if (!isTest && !isSubtest) {
+			return;
+		}
+
+		const parameter = getTestCallback(node)?.params[0];
+		if (parameter?.type === 'Identifier' && parameter.name !== expected) {
+			return {
+				node: parameter,
+				messageId: MESSAGE_ID,
+				data: {expected, actual: parameter.name},
+			};
+		}
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.leave(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a consistent name for the test context parameter.',
+			recommended: 'unopinionated',
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					name: {
+						type: 'string',
+						description: 'The required name for the test context parameter.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{name: 't'}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/consistent-test-filename.js

@@ -0,0 +1,70 @@
+import {resolveImports} from './utils/node-test.js';
+
+const MESSAGE_ID = 'consistent-test-filename';
+
+const messages = {
+	[MESSAGE_ID]: 'Test file name `{{name}}` does not match the required pattern `{{pattern}}`.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const filename = context.physicalFilename ?? context.filename;
+	// No real file (for example, linting stdin), so there is nothing to check.
+	if (!filename || filename === '<input>' || filename === '<text>') {
+		return;
+	}
+
+	const {pattern} = context.options[0];
+
+	let patternRegExp;
+	try {
+		patternRegExp = new RegExp(pattern, 'v');
+	} catch (error) {
+		throw new Error(`Invalid \`pattern\` option for \`consistent-test-filename\`: ${error.message}`, {cause: error});
+	}
+
+	const name = filename.split(/[/\\]/).pop();
+	if (patternRegExp.test(name)) {
+		return;
+	}
+
+	context.on('Program', node => ({
+		node,
+		messageId: MESSAGE_ID,
+		data: {name, pattern},
+	}));
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a consistent test file name pattern.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					pattern: {
+						type: 'string',
+						description: 'A regular expression the test file name must match.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{pattern: String.raw`\.test\.[cm]?[jt]sx?$`}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/consistent-test-it.js

@@ -0,0 +1,84 @@
+import {resolveImports, parseTestCall, createSuiteDepthTracker} from './utils/node-test.js';
+
+const MESSAGE_ID = 'consistent-test-it';
+
+const messages = {
+	[MESSAGE_ID]: 'Prefer `{{expected}}` over `{{actual}}` {{location}}.',
+};
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	const {fn: topLevelName, withinDescribe: withinDescribeName} = context.options[0];
+
+	const tracker = createSuiteDepthTracker();
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (!parsed) {
+			return;
+		}
+
+		let problem;
+		if (parsed.kind === 'test') {
+			const isInDescribe = tracker.depth > 0;
+			const expected = isInDescribe ? withinDescribeName : topLevelName;
+			if (parsed.name !== expected) {
+				problem = {
+					node,
+					messageId: MESSAGE_ID,
+					data: {
+						expected,
+						actual: parsed.name,
+						location: isInDescribe ? 'inside a `describe`' : 'at the top level',
+					},
+				};
+			}
+		} else if (parsed.kind === 'suite') {
+			tracker.enterSuite(node);
+		}
+
+		return problem;
+	});
+
+	context.onExit('CallExpression', node => {
+		tracker.exitSuite(node);
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce consistent use of `test` or `it`.',
+			recommended: false,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					fn: {
+						enum: ['test', 'it'],
+						description: 'The name to use for top-level test cases.',
+					},
+					withinDescribe: {
+						enum: ['test', 'it'],
+						description: 'The name to use for test cases inside a `describe`.',
+					},
+				},
+				additionalProperties: false,
+			},
+		],
+		defaultOptions: [{fn: 'test', withinDescribe: 'it'}],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/fix/index.js

@@ -0,0 +1,5 @@
+export {default as removeArgument, getArgumentRemovalRange} from './remove-argument.js';
+export {
+	replaceMemberExpressionProperty,
+	removeMemberExpressionProperty,
+} from './replace-member-expression-property.js';

package/rules/fix/remove-argument.js

@@ -0,0 +1,58 @@
+import {isCommaToken} from '@eslint-community/eslint-utils';
+import {getParentheses} from '../utils/index.js';
+
+/**
+@import {TSESTree as ESTree} from '@typescript-eslint/types';
+@import * as ESLint from 'eslint';
+*/
+
+/**
+@param {ESTree.CallExpressionArgument} node
+@param {ESLint.Rule.RuleContext} context - The ESLint rule context object.
+@returns {Array<number>}
+*/
+function getArgumentRemovalRange(node, context) {
+	const callOrNewExpression = node.parent;
+	const index = callOrNewExpression.arguments.indexOf(node);
+	const parentheses = getParentheses(node, context);
+	const firstToken = parentheses[0] || node;
+	const lastToken = parentheses.at(-1) || node;
+	const {sourceCode} = context;
+
+	let [start] = sourceCode.getRange(firstToken);
+	let [, end] = sourceCode.getRange(lastToken);
+
+	if (callOrNewExpression.arguments.length === 1) {
+		// The only argument: also drop a dangling trailing comma if present (`fn(a,)`).
+		const tokenAfter = sourceCode.getTokenAfter(lastToken);
+		if (isCommaToken(tokenAfter)) {
+			[, end] = sourceCode.getRange(tokenAfter);
+		}
+	} else if (index === 0) {
+		// First of several: remove it through the following comma and the gap after it, so
+		// `fn(a, b)` becomes `fn(b)` rather than `fn( b)`.
+		const commaToken = sourceCode.getTokenAfter(lastToken);
+		const nextArgumentToken = sourceCode.getTokenAfter(commaToken);
+		[end] = sourceCode.getRange(nextArgumentToken);
+	} else {
+		// Otherwise remove the comma that precedes it.
+		const commaToken = sourceCode.getTokenBefore(firstToken);
+		[start] = sourceCode.getRange(commaToken);
+	}
+
+	return [start, end];
+}
+
+/**
+@param {ESLint.Rule.RuleFixer} fixer
+@param {ESTree.CallExpressionArgument} node
+@param {ESLint.Rule.RuleContext} context - The ESLint rule context object.
+@returns {ESLint.Rule.Fix}
+*/
+export default function removeArgument(fixer, node, context) {
+	return fixer.removeRange(getArgumentRemovalRange(node, context));
+}
+
+export {
+	getArgumentRemovalRange,
+};

package/rules/fix/replace-member-expression-property.js

@@ -0,0 +1,25 @@
+import {getParenthesizedRange} from '../utils/index.js';
+
+/**
+@import {TSESTree as ESTree} from '@typescript-eslint/types';
+@import * as ESLint from 'eslint';
+*/
+
+/**
+@param {ESTree.MemberExpression} memberExpression - The `MemberExpression` to fix.
+@param {ESLint.Rule.RuleContext} context - The ESLint rule context object.
+@param {string} text
+@returns {ESLint.Rule.ReportFixer}
+*/
+export function replaceMemberExpressionProperty(fixer, memberExpression, context, text) {
+	const [, start] = getParenthesizedRange(memberExpression.object, context);
+	const [, end] = context.sourceCode.getRange(memberExpression);
+	return fixer.replaceTextRange([start, end], text);
+}
+
+/**
+@param {ESTree.MemberExpression} memberExpression - The `MemberExpression` to fix.
+@param {ESLint.Rule.RuleContext} context - The ESLint rule context object.
+@returns {ESLint.Rule.ReportFixer}
+*/
+export const removeMemberExpressionProperty = (fixer, memberExpression, context) => replaceMemberExpressionProperty(fixer, memberExpression, context, '');

package/rules/hooks-order.js

@@ -0,0 +1,147 @@
+import {resolveImports, parseTestCall} from './utils/node-test.js';
+
+const MESSAGE_ID = 'hooks-order/error';
+
+const messages = {
+	[MESSAGE_ID]: 'Hook `{{current}}` must come before `{{invalid}}`.',
+};
+
+// Canonical order for node:test hooks.
+const HOOK_ORDER = ['before', 'beforeEach', 'afterEach', 'after'];
+const HOOK_ORDER_INDEX = Object.fromEntries(HOOK_ORDER.map((name, index) => [name, index]));
+
+/*
+Build the fix that reorders a block's hooks into canonical order in a single pass. Returns
+`undefined` (no fix) when the hooks are not a contiguous run of statements, or a comment sits
+between them — reordering would otherwise drop or misattribute code.
+*/
+function getReorderFix(block, hooks, sourceCode) {
+	const positions = hooks.map(hook => block.body.indexOf(hook.statement));
+	const min = Math.min(...positions);
+	const max = Math.max(...positions);
+
+	// Non-hook statements interleaved with the hooks.
+	if (max - min + 1 !== hooks.length) {
+		return undefined;
+	}
+
+	// A comment anywhere between consecutive hooks must not be moved.
+	for (let index = min; index < max; index += 1) {
+		if (sourceCode.getTokensBetween(block.body[index], block.body[index + 1], {includeComments: true}).length > 0) {
+			return undefined;
+		}
+	}
+
+	// A trailing comment on the last hook's line would stay put while the statement text moves,
+	// misattributing it to whichever hook ends up last. The reorder replaces statement text only.
+	const lastHook = block.body[max];
+	const [trailingComment] = sourceCode.getCommentsAfter(lastHook);
+	if (trailingComment && sourceCode.getLoc(trailingComment).start.line === sourceCode.getLoc(lastHook).end.line) {
+		return undefined;
+	}
+
+	// Stable sort preserves the original order of same-named hooks.
+	const sorted = hooks.toSorted((a, b) => HOOK_ORDER_INDEX[a.name] - HOOK_ORDER_INDEX[b.name]);
+
+	return function * (fixer) {
+		for (const [index, hook] of hooks.entries()) {
+			if (sorted[index].statement !== hook.statement) {
+				yield fixer.replaceText(hook.statement, sourceCode.getText(sorted[index].statement));
+			}
+		}
+	};
+}
+
+function getBlockProblems(block, hooks, sourceCode) {
+	const problems = [];
+	let fix;
+	let isFixComputed = false;
+
+	for (const [position, hook] of hooks.entries()) {
+		const index = HOOK_ORDER_INDEX[hook.name];
+		// A hook that appears before the current one but belongs later means the current hook
+		// is out of order and should have come first.
+		const earlierConflict = hooks.slice(0, position).find(other => HOOK_ORDER_INDEX[other.name] > index);
+		if (!earlierConflict) {
+			continue;
+		}
+
+		// Compute the single block-wide reorder fix once, lazily, and share it across the
+		// block's problems; ESLint applies it once and the re-lint finds the block sorted.
+		if (!isFixComputed) {
+			fix = getReorderFix(block, hooks, sourceCode);
+			isFixComputed = true;
+		}
+
+		problems.push({
+			node: hook.statement.expression,
+			messageId: MESSAGE_ID,
+			data: {current: hook.name, invalid: earlierConflict.name},
+			fix,
+		});
+	}
+
+	return problems;
+}
+
+/** @param {import('eslint').Rule.RuleContext} context */
+const create = context => {
+	const {sourceCode} = context;
+	const imports = resolveImports(context);
+	if (!imports.isTestFile) {
+		return;
+	}
+
+	// Group bare-statement hooks by their containing block, in source order. Hooks used as a
+	// sub-expression (`const x = before(…)`, `await before(…)`) cannot be moved safely and are
+	// skipped. The containing block (a `describe` body or the program) is the ordering scope.
+	const hooksByBlock = new Map();
+
+	context.on('CallExpression', node => {
+		const parsed = parseTestCall(node, imports);
+		if (parsed?.kind !== 'hook' || node.parent.type !== 'ExpressionStatement') {
+			return;
+		}
+
+		const block = node.parent.parent;
+		if (block?.type !== 'BlockStatement' && block?.type !== 'Program') {
+			return;
+		}
+
+		let hooks = hooksByBlock.get(block);
+		if (!hooks) {
+			hooks = [];
+			hooksByBlock.set(block, hooks);
+		}
+
+		hooks.push({name: parsed.name, statement: node.parent});
+	});
+
+	context.onExit('Program', () => {
+		const problems = [];
+
+		for (const [block, hooks] of hooksByBlock) {
+			problems.push(...getBlockProblems(block, hooks, sourceCode));
+		}
+
+		return problems;
+	});
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const config = {
+	create,
+	meta: {
+		type: 'suggestion',
+		docs: {
+			description: 'Enforce a consistent order of hook declarations.',
+			recommended: 'unopinionated',
+		},
+		fixable: 'code',
+		schema: [],
+		messages,
+		languages: ['js/js'],
+	},
+};
+
+export default config;

package/rules/index.js

@@ -0,0 +1,84 @@
+// Generated file, DO NOT edit
+
+export {default as 'assertion-arguments'} from './assertion-arguments.js';
+export {default as 'consistent-assert-style'} from './consistent-assert-style.js';
+export {default as 'consistent-assert-throws-callback-style'} from './consistent-assert-throws-callback-style.js';
+export {default as 'consistent-modifier-style'} from './consistent-modifier-style.js';
+export {default as 'consistent-test-context-name'} from './consistent-test-context-name.js';
+export {default as 'consistent-test-filename'} from './consistent-test-filename.js';
+export {default as 'consistent-test-it'} from './consistent-test-it.js';
+export {default as 'hooks-order'} from './hooks-order.js';
+export {default as 'max-assertions'} from './max-assertions.js';
+export {default as 'max-nested-describe'} from './max-nested-describe.js';
+export {default as 'no-assert-in-describe'} from './no-assert-in-describe.js';
+export {default as 'no-assert-in-hook'} from './no-assert-in-hook.js';
+export {default as 'no-assert-match-string'} from './no-assert-match-string.js';
+export {default as 'no-assert-throws-async'} from './no-assert-throws-async.js';
+export {default as 'no-assert-throws-call'} from './no-assert-throws-call.js';
+export {default as 'no-assert-throws-multiple-statements'} from './no-assert-throws-multiple-statements.js';
+export {default as 'no-assert-throws-string'} from './no-assert-throws-string.js';
+export {default as 'no-async-describe'} from './no-async-describe.js';
+export {default as 'no-async-fn-without-await'} from './no-async-fn-without-await.js';
+export {default as 'no-callback-and-promise'} from './no-callback-and-promise.js';
+export {default as 'no-commented-tests'} from './no-commented-tests.js';
+export {default as 'no-compound-assertion'} from './no-compound-assertion.js';
+export {default as 'no-conditional-assertion'} from './no-conditional-assertion.js';
+export {default as 'no-conditional-in-test'} from './no-conditional-in-test.js';
+export {default as 'no-conditional-tests'} from './no-conditional-tests.js';
+export {default as 'no-conflicting-modifiers'} from './no-conflicting-modifiers.js';
+export {default as 'no-constant-assertion'} from './no-constant-assertion.js';
+export {default as 'no-done-callback'} from './no-done-callback.js';
+export {default as 'no-duplicate-assertions'} from './no-duplicate-assertions.js';
+export {default as 'no-duplicate-hooks'} from './no-duplicate-hooks.js';
+export {default as 'no-duplicate-plan'} from './no-duplicate-plan.js';
+export {default as 'no-export'} from './no-export.js';
+export {default as 'no-identical-assertion-arguments'} from './no-identical-assertion-arguments.js';
+export {default as 'no-identical-title'} from './no-identical-title.js';
+export {default as 'no-incorrect-deep-equal'} from './no-incorrect-deep-equal.js';
+export {default as 'no-incorrect-strict-equal'} from './no-incorrect-strict-equal.js';
+export {default as 'no-loop-static-title'} from './no-loop-static-title.js';
+export {default as 'no-misused-concurrency'} from './no-misused-concurrency.js';
+export {default as 'no-mock-timers-destructured-import'} from './no-mock-timers-destructured-import.js';
+export {default as 'no-nested-tests'} from './no-nested-tests.js';
+export {default as 'no-only-test'} from './no-only-test.js';
+export {default as 'no-parent-test-context'} from './no-parent-test-context.js';
+export {default as 'no-process-env-mutation'} from './no-process-env-mutation.js';
+export {default as 'no-process-exit-in-test'} from './no-process-exit-in-test.js';
+export {default as 'no-skip-test'} from './no-skip-test.js';
+export {default as 'no-skip-without-reason'} from './no-skip-without-reason.js';
+export {default as 'no-skip-without-return'} from './no-skip-without-return.js';
+export {default as 'no-sleep-in-test'} from './no-sleep-in-test.js';
+export {default as 'no-snapshot-in-loop'} from './no-snapshot-in-loop.js';
+export {default as 'no-standalone-assert'} from './no-standalone-assert.js';
+export {default as 'no-test-inside-hook'} from './no-test-inside-hook.js';
+export {default as 'no-test-return-statement'} from './no-test-return-statement.js';
+export {default as 'no-todo-test'} from './no-todo-test.js';
+export {default as 'no-unawaited-promise-assertion'} from './no-unawaited-promise-assertion.js';
+export {default as 'no-unawaited-rejects'} from './no-unawaited-rejects.js';
+export {default as 'no-unawaited-subtest'} from './no-unawaited-subtest.js';
+export {default as 'no-unknown-test-options'} from './no-unknown-test-options.js';
+export {default as 'no-useless-assertion'} from './no-useless-assertion.js';
+export {default as 'prefer-assert-match'} from './prefer-assert-match.js';
+export {default as 'prefer-assert-throws'} from './prefer-assert-throws.js';
+export {default as 'prefer-async-await'} from './prefer-async-await.js';
+export {default as 'prefer-context-mock'} from './prefer-context-mock.js';
+export {default as 'prefer-diagnostic'} from './prefer-diagnostic.js';
+export {default as 'prefer-equality-assertion'} from './prefer-equality-assertion.js';
+export {default as 'prefer-hooks-on-top'} from './prefer-hooks-on-top.js';
+export {default as 'prefer-lowercase-title'} from './prefer-lowercase-title.js';
+export {default as 'prefer-mock-method'} from './prefer-mock-method.js';
+export {default as 'prefer-strict-assert'} from './prefer-strict-assert.js';
+export {default as 'prefer-test-context-assert'} from './prefer-test-context-assert.js';
+export {default as 'prefer-todo'} from './prefer-todo.js';
+export {default as 'require-assertion'} from './require-assertion.js';
+export {default as 'require-await-concurrent-subtests'} from './require-await-concurrent-subtests.js';
+export {default as 'require-context-assert-with-plan'} from './require-context-assert-with-plan.js';
+export {default as 'require-hook'} from './require-hook.js';
+export {default as 'require-mock-timers-advance'} from './require-mock-timers-advance.js';
+export {default as 'require-mock-timers-apis'} from './require-mock-timers-apis.js';
+export {default as 'require-throws-expectation'} from './require-throws-expectation.js';
+export {default as 'require-throws-validator-return-true'} from './require-throws-validator-return-true.js';
+export {default as 'require-top-level-describe'} from './require-top-level-describe.js';
+export {default as 'test-title-format'} from './test-title-format.js';
+export {default as 'test-title'} from './test-title.js';
+export {default as 'valid-describe-callback'} from './valid-describe-callback.js';