prefer-user-event.ts

import { TSESTree, ASTUtils } from '@typescript-eslint/utils';

import { createTestingLibraryRule } from '../create-testing-library-rule';
import {
	findClosestCallExpressionNode,
	isCallExpression,
	isMemberExpression,
} from '../node-utils';

export const RULE_NAME = 'prefer-user-event';

export type MessageIds = 'preferUserEvent';
export type Options = [{ allowedMethods: string[] }];

export const UserEventMethods = [
	'click',
	'dblClick',
	'type',
	'upload',
	'clear',
	'selectOptions',
	'deselectOptions',
	'tab',
	'hover',
	'unhover',
	'paste',
	'press',
	'scrollTo',
] as const;
type UserEventMethodsType = (typeof UserEventMethods)[number];

// maps fireEvent methods to userEvent. Those not found here, do not have an equivalent (yet)
export const MAPPING_TO_USER_EVENT: Record<string, UserEventMethodsType[]> = {
	click: ['click', 'type', 'selectOptions', 'deselectOptions'],
	change: ['upload', 'type', 'clear', 'selectOptions', 'deselectOptions'],
	changeText: ['type'],
	dblClick: ['dblClick'],
	input: ['type', 'upload', 'selectOptions', 'deselectOptions', 'paste'],
	keyDown: ['type', 'tab'],
	keyPress: ['type'],
	keyUp: ['type', 'tab'],
	mouseDown: ['click', 'dblClick', 'selectOptions', 'deselectOptions'],
	mouseEnter: ['hover', 'selectOptions', 'deselectOptions'],
	mouseLeave: ['unhover'],
	mouseMove: ['hover', 'unhover', 'selectOptions', 'deselectOptions'],
	mouseOut: ['unhover'],
	mouseOver: ['hover', 'selectOptions', 'deselectOptions'],
	mouseUp: ['click', 'dblClick', 'selectOptions', 'deselectOptions'],
	paste: ['paste'],
	pointerDown: ['click', 'dblClick', 'selectOptions', 'deselectOptions'],
	pointerEnter: ['hover', 'selectOptions', 'deselectOptions'],
	pointerLeave: ['unhover'],
	pointerMove: ['hover', 'unhover', 'selectOptions', 'deselectOptions'],
	pointerOut: ['unhover'],
	pointerOver: ['hover', 'selectOptions', 'deselectOptions'],
	pointerUp: ['click', 'dblClick', 'selectOptions', 'deselectOptions'],
	press: ['press'],
	scroll: ['scrollTo'],
};

function buildErrorMessage(fireEventMethod: string) {
	const userEventMethods = MAPPING_TO_USER_EVENT[fireEventMethod].map(
		(methodName) => `userEvent.${methodName}`
	);

	// TODO: when min node version is 13, we can reimplement this using `Intl.ListFormat`
	return userEventMethods.join(', ').replace(/, ([a-zA-Z.]+)$/, ', or $1');
}

const fireEventMappedMethods = Object.keys(MAPPING_TO_USER_EVENT);

export default createTestingLibraryRule<Options, MessageIds>({
	name: RULE_NAME,
	meta: {
		type: 'suggestion',
		docs: {
			description:
				'Suggest using `userEvent` over `fireEvent` for simulating user interactions',
			recommendedConfig: {
				dom: false,
				angular: false,
				react: false,
				vue: false,
				marko: false,
			},
		},
		messages: {
			preferUserEvent:
				'Prefer using {{userEventMethods}} over fireEvent.{{fireEventMethod}}',
		},
		schema: [
			{
				type: 'object',
				properties: {
					allowedMethods: { type: 'array' },
				},
			},
		],
	},
	defaultOptions: [{ allowedMethods: [] }],

	create(context, [options], helpers) {
		const { allowedMethods } = options;
		const createEventVariables: Record<string, string | undefined> = {};

		const isfireEventMethodAllowed = (methodName: string) =>
			!fireEventMappedMethods.includes(methodName) ||
			allowedMethods.includes(methodName);

		const getFireEventMethodName = (
			callExpressionNode: TSESTree.CallExpression,
			node: TSESTree.Identifier
		) => {
			if (
				!ASTUtils.isIdentifier(callExpressionNode.callee) &&
				!isMemberExpression(callExpressionNode.callee)
			) {
				return node.name;
			}
			const secondArgument = callExpressionNode.arguments[1];
			if (
				ASTUtils.isIdentifier(secondArgument) &&
				createEventVariables[secondArgument.name] !== undefined
			) {
				return createEventVariables[secondArgument.name];
			}
			if (
				!isCallExpression(secondArgument) ||
				!helpers.isCreateEventUtil(secondArgument)
			) {
				return node.name;
			}
			if (ASTUtils.isIdentifier(secondArgument.callee)) {
				// createEvent('click', foo)
				return (secondArgument.arguments[0] as TSESTree.Literal)
					.value as string;
			}
			// createEvent.click(foo)
			return (
				(secondArgument.callee as TSESTree.MemberExpression)
					.property as TSESTree.Identifier
			).name;
		};
		return {
			'CallExpression Identifier'(node: TSESTree.Identifier) {
				if (!helpers.isFireEventMethod(node)) {
					return;
				}
				const closestCallExpression = findClosestCallExpressionNode(node, true);

				if (!closestCallExpression) {
					return;
				}

				const fireEventMethodName = getFireEventMethodName(
					closestCallExpression,
					node
				);

				if (
					!fireEventMethodName ||
					isfireEventMethodAllowed(fireEventMethodName)
				) {
					return;
				}
				context.report({
					node: closestCallExpression.callee,
					messageId: 'preferUserEvent',
					data: {
						userEventMethods: buildErrorMessage(fireEventMethodName),
						fireEventMethod: fireEventMethodName,
					},
				});
			},

			VariableDeclarator(node: TSESTree.VariableDeclarator) {
				if (
					!isCallExpression(node.init) ||
					!helpers.isCreateEventUtil(node.init) ||
					!ASTUtils.isIdentifier(node.id)
				) {
					return;
				}
				let fireEventMethodName = '';
				if (
					isMemberExpression(node.init.callee) &&
					ASTUtils.isIdentifier(node.init.callee.property)
				) {
					fireEventMethodName = node.init.callee.property.name;
				} else if (node.init.arguments.length > 0) {
					fireEventMethodName = (node.init.arguments[0] as TSESTree.Literal)
						.value as string;
				}
				if (!isfireEventMethodAllowed(fireEventMethodName)) {
					createEventVariables[node.id.name] = fireEventMethodName;
				}
			},
		};
	},
});