Merge remote-tracking branch 'origin/master' into v4

Belco90 · Belco90 · commit d1f03887410b · 2020-11-01T19:15:25.000+01:00
# Conflicts:
#	README.md
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -369,6 +369,17 @@
         "platform",
         "maintenance"
       ]
+    },
+    {
+      "login": "J-Huang",
+      "name": "Jian Huang",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/4263459?v=4",
+      "profile": "https://github.com/J-Huang",
+      "contributions": [
+        "code",
+        "test",
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,
diff --git a/README.md b/README.md
@@ -24,7 +24,7 @@
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-34-orange.svg?style=flat-square)](#contributors-)
+[![All Contributors](https://img.shields.io/badge/all_contributors-35-orange.svg?style=flat-square)](#contributors-)
 
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
@@ -131,6 +131,7 @@ To enable this configuration use the `extends` property in your
 | [await-async-utils](docs/rules/await-async-utils.md)                             | Enforce async utils to be awaited properly                                               | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] |                    |
 | [await-fire-event](docs/rules/await-fire-event.md)                               | Enforce async fire event methods to be awaited                                           | ![vue-badge][]                                                    |                    |
 | [consistent-data-testid](docs/rules/consistent-data-testid.md)                   | Ensure `data-testid` values match a provided regex.                                      |                                                                   |                    |
+| [no-await-sync-events](docs/rules/no-await-sync-events.md)                       | Disallow unnecessary `await` for sync events                                             |                                                                   |                    |
 | [no-await-sync-query](docs/rules/no-await-sync-query.md)                         | Disallow unnecessary `await` for sync queries                                            | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] |                    |
 | [no-container](docs/rules/no-container.md)                                       | Disallow the use of `container` methods                                                  | ![angular-badge][] ![react-badge][] ![vue-badge][]                |                    |
 | [no-debug](docs/rules/no-debug.md)                                               | Disallow the use of `debug`                                                              | ![angular-badge][] ![react-badge][] ![vue-badge][]                |                    |
@@ -223,6 +224,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
     <td align="center"><a href="https://twitter.com/Gpx"><img src="https://avatars0.githubusercontent.com/u/767959?v=4" width="100px;" alt=""/><br /><sub><b>Giorgio Polvara</b></sub></a><br /><a href="https://github.com/testing-library/eslint-plugin-testing-library/commits?author=Gpx" title="Code">💻</a> <a href="https://github.com/testing-library/eslint-plugin-testing-library/commits?author=Gpx" title="Tests">⚠️</a> <a href="https://github.com/testing-library/eslint-plugin-testing-library/commits?author=Gpx" title="Documentation">📖</a></td>
     <td align="center"><a href="https://github.com/jdanil"><img src="https://avatars0.githubusercontent.com/u/8342105?v=4" width="100px;" alt=""/><br /><sub><b>Josh David</b></sub></a><br /><a href="https://github.com/testing-library/eslint-plugin-testing-library/commits?author=jdanil" title="Documentation">📖</a></td>
     <td align="center"><a href="https://michaeldeboey.be"><img src="https://avatars3.githubusercontent.com/u/6643991?v=4" width="100px;" alt=""/><br /><sub><b>Michaël De Boey</b></sub></a><br /><a href="https://github.com/testing-library/eslint-plugin-testing-library/commits?author=MichaelDeBoey" title="Code">💻</a> <a href="#platform-MichaelDeBoey" title="Packaging/porting to new platform">📦</a> <a href="#maintenance-MichaelDeBoey" title="Maintenance">🚧</a></td>
+    <td align="center"><a href="https://github.com/J-Huang"><img src="https://avatars0.githubusercontent.com/u/4263459?v=4" width="100px;" alt=""/><br /><sub><b>Jian Huang</b></sub></a><br /><a href="https://github.com/testing-library/eslint-plugin-testing-library/commits?author=J-Huang" title="Code">💻</a> <a href="https://github.com/testing-library/eslint-plugin-testing-library/commits?author=J-Huang" title="Tests">⚠️</a> <a href="https://github.com/testing-library/eslint-plugin-testing-library/commits?author=J-Huang" title="Documentation">📖</a></td>
   </tr>
 </table>
 
diff --git a/docs/rules/no-await-sync-events.md b/docs/rules/no-await-sync-events.md
@@ -0,0 +1,68 @@
+# Disallow unnecessary `await` for sync events (no-await-sync-events)
+
+Ensure that sync events are not awaited unnecessarily.
+
+## Rule Details
+
+Functions in the event object provided by Testing Library, including
+fireEvent and userEvent, do NOT return Promise, with an exception of
+`userEvent.type`, which delays the promise resolve only if [`delay`
+option](https://github.com/testing-library/user-event#typeelement-text-options) is specified.
+Some examples are:
+
+- `fireEvent.click`
+- `fireEvent.select`
+- `userEvent.tab`
+- `userEvent.hover`
+
+This rule aims to prevent users from waiting for those function calls.
+
+Examples of **incorrect** code for this rule:
+
+```js
+const foo = async () => {
+  // ...
+  await fireEvent.click(button);
+  // ...
+};
+
+const bar = () => {
+  // ...
+  await userEvent.tab();
+  // ...
+};
+
+const baz = () => {
+  // ...
+  await userEvent.type(textInput, 'abc');
+  // ...
+};
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const foo = () => {
+  // ...
+  fireEvent.click(button);
+  // ...
+};
+
+const bar = () => {
+  // ...
+  userEvent.tab();
+  // ...
+};
+
+const baz = () => {
+  // await userEvent.type only with delay option
+  await userEvent.type(textInput, 'abc', {delay: 1000});
+  userEvent.type(textInput, '123');
+  // ...
+};
+```
+
+## Notes
+
+There is another rule `await-fire-event`, which is only in Vue Testing
+Library. Please do not confuse with this rule.
diff --git a/lib/index.ts b/lib/index.ts
@@ -2,6 +2,7 @@ import awaitAsyncQuery from './rules/await-async-query';
 import awaitAsyncUtils from './rules/await-async-utils';
 import awaitFireEvent from './rules/await-fire-event';
 import consistentDataTestid from './rules/consistent-data-testid';
+import noAwaitSyncEvents from './rules/no-await-sync-events';
 import noAwaitSyncQuery from './rules/no-await-sync-query';
 import noContainer from './rules/no-container';
 import noDebug from './rules/no-debug';
@@ -27,6 +28,7 @@ const rules = {
   'await-async-utils': awaitAsyncUtils,
   'await-fire-event': awaitFireEvent,
   'consistent-data-testid': consistentDataTestid,
+  'no-await-sync-events': noAwaitSyncEvents,
   'no-await-sync-query': noAwaitSyncQuery,
   'no-container': noContainer,
   'no-debug': noDebug,
diff --git a/lib/rules/no-await-sync-events.ts b/lib/rules/no-await-sync-events.ts
@@ -0,0 +1,66 @@
+import { ESLintUtils, TSESTree } from '@typescript-eslint/experimental-utils';
+import { getDocsUrl, SYNC_EVENTS } from '../utils';
+import { isObjectExpression, isProperty, isIdentifier } from '../node-utils';
+export const RULE_NAME = 'no-await-sync-events';
+export type MessageIds = 'noAwaitSyncEvents';
+type Options = [];
+
+const SYNC_EVENTS_REGEXP = new RegExp(`^(${SYNC_EVENTS.join('|')})$`);
+export default ESLintUtils.RuleCreator(getDocsUrl)<Options, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow unnecessary `await` for sync events',
+      category: 'Best Practices',
+      recommended: 'error',
+    },
+    messages: {
+      noAwaitSyncEvents: '`{{ name }}` does not need `await` operator',
+    },
+    fixable: null,
+    schema: [],
+  },
+  defaultOptions: [],
+
+  create(context) {
+    // userEvent.type() is an exception, which returns a
+    // Promise. But it is only necessary to wait when delay
+    // option is specified. So this rule has a special exception
+    // for the case await userEvent.type(element, 'abc', {delay: 1234})
+    return {
+      [`AwaitExpression > CallExpression > MemberExpression > Identifier[name=${SYNC_EVENTS_REGEXP}]`](
+        node: TSESTree.Identifier
+      ) {
+        const memberExpression = node.parent as TSESTree.MemberExpression;
+        const methodNode = memberExpression.property as TSESTree.Identifier;
+        const callExpression = memberExpression.parent as TSESTree.CallExpression;
+        const withDelay =
+          callExpression.arguments.length >= 3 &&
+          isObjectExpression(callExpression.arguments[2]) &&
+          callExpression.arguments[2].properties.some(
+            (property) =>
+              isProperty(property) &&
+              isIdentifier(property.key) &&
+              property.key.name === 'delay'
+          );
+
+        if (
+          !(
+            node.name === 'userEvent' &&
+            methodNode.name === 'type' &&
+            withDelay
+          )
+        ) {
+          context.report({
+            node: methodNode,
+            messageId: 'noAwaitSyncEvents',
+            data: {
+              name: `${node.name}.${methodNode.name}`,
+            },
+          });
+        }
+      },
+    };
+  },
+});
diff --git a/lib/utils.ts b/lib/utils.ts
@@ -71,6 +71,8 @@ const ASYNC_UTILS = [
   'waitForDomChange',
 ];
 
+const SYNC_EVENTS = ['fireEvent', 'userEvent'];
+
 const TESTING_FRAMEWORK_SETUP_HOOKS = ['beforeEach', 'beforeAll'];
 
 const PROPERTIES_RETURNING_NODES = [
@@ -122,6 +124,7 @@ export {
   ASYNC_QUERIES_COMBINATIONS,
   ALL_QUERIES_COMBINATIONS,
   ASYNC_UTILS,
+  SYNC_EVENTS,
   TESTING_FRAMEWORK_SETUP_HOOKS,
   LIBRARY_MODULES,
   PROPERTIES_RETURNING_NODES,
diff --git a/tests/lib/rules/no-await-sync-events.test.ts b/tests/lib/rules/no-await-sync-events.test.ts
@@ -0,0 +1,169 @@
+import { createRuleTester } from '../test-utils';
+import rule, { RULE_NAME } from '../../../lib/rules/no-await-sync-events';
+import { SYNC_EVENTS } from '../../../lib/utils';
+
+const ruleTester = createRuleTester();
+
+const fireEventFunctions = [
+  'copy',
+  'cut',
+  'paste',
+  'compositionEnd',
+  'compositionStart',
+  'compositionUpdate',
+  'keyDown',
+  'keyPress',
+  'keyUp',
+  'focus',
+  'blur',
+  'focusIn',
+  'focusOut',
+  'change',
+  'input',
+  'invalid',
+  'submit',
+  'reset',
+  'click',
+  'contextMenu',
+  'dblClick',
+  'drag',
+  'dragEnd',
+  'dragEnter',
+  'dragExit',
+  'dragLeave',
+  'dragOver',
+  'dragStart',
+  'drop',
+  'mouseDown',
+  'mouseEnter',
+  'mouseLeave',
+  'mouseMove',
+  'mouseOut',
+  'mouseOver',
+  'mouseUp',
+  'popState',
+  'select',
+  'touchCancel',
+  'touchEnd',
+  'touchMove',
+  'touchStart',
+  'scroll',
+  'wheel',
+  'abort',
+  'canPlay',
+  'canPlayThrough',
+  'durationChange',
+  'emptied',
+  'encrypted',
+  'ended',
+  'loadedData',
+  'loadedMetadata',
+  'loadStart',
+  'pause',
+  'play',
+  'playing',
+  'progress',
+  'rateChange',
+  'seeked',
+  'seeking',
+  'stalled',
+  'suspend',
+  'timeUpdate',
+  'volumeChange',
+  'waiting',
+  'load',
+  'error',
+  'animationStart',
+  'animationEnd',
+  'animationIteration',
+  'transitionEnd',
+  'doubleClick',
+  'pointerOver',
+  'pointerEnter',
+  'pointerDown',
+  'pointerMove',
+  'pointerUp',
+  'pointerCancel',
+  'pointerOut',
+  'pointerLeave',
+  'gotPointerCapture',
+  'lostPointerCapture',
+];
+const userEventFunctions = [
+  'clear',
+  'click',
+  'dblClick',
+  'selectOptions',
+  'deselectOptions',
+  'upload',
+  // 'type',
+  'tab',
+  'paste',
+  'hover',
+  'unhover',
+];
+let eventFunctions: string[] = [];
+SYNC_EVENTS.forEach((event) => {
+  switch (event) {
+    case 'fireEvent':
+      eventFunctions = eventFunctions.concat(
+        fireEventFunctions.map((f: string): string => `${event}.${f}`)
+      );
+      break;
+    case 'userEvent':
+      eventFunctions = eventFunctions.concat(
+        userEventFunctions.map((f: string): string => `${event}.${f}`)
+      );
+      break;
+    default:
+      eventFunctions.push(`${event}.anyFunc`);
+  }
+});
+
+ruleTester.run(RULE_NAME, rule, {
+  valid: [
+    // sync events without await are valid
+    // userEvent.type() is an exception
+    ...eventFunctions.map((func) => ({
+      code: `() => {
+        ${func}('foo')
+      }
+      `,
+    })),
+    {
+      code: `() => {
+        userEvent.type('foo')
+      }
+      `,
+    },
+    {
+      code: `() => {
+        await userEvent.type('foo', 'bar', {delay: 1234})
+      }
+      `,
+    },
+  ],
+
+  invalid: [
+    // sync events with await operator are not valid
+    ...eventFunctions.map((func) => ({
+      code: `
+        import { fireEvent } from '@testing-library/framework';
+        import userEvent from '@testing-library/user-event';
+        test('should report sync event awaited', async() => {
+          await ${func}('foo');
+        });
+      `,
+      errors: [{ line: 5, messageId: 'noAwaitSyncEvents' }],
+    })),
+    {
+      code: `
+        import userEvent from '@testing-library/user-event';
+        test('should report sync event awaited', async() => {
+          await userEvent.type('foo', 'bar', {hello: 1234});
+        });
+      `,
+      errors: [{ line: 4, messageId: 'noAwaitSyncEvents' }],
+    },
+  ],
+});
