feat: add rule require-awaited-expect-poll (#817)

* feat: add rule `require-awaited-expect-poll`

Closes #496

* cleanup

* cleanup

* chore: fix linter

---------

Co-authored-by: Verite Mugabo <mugaboverite@gmail.com>

Author: StyleShit

README.md

@@ -252,6 +252,7 @@ export default defineConfig({
 | [prefer-to-have-length](docs/rules/prefer-to-have-length.md)                                                             | enforce using toHaveLength()                                                                    |     | 🌐  |     | 🔧  |     |     |     |
 | [prefer-todo](docs/rules/prefer-todo.md)                                                                                 | enforce using `test.todo`                                                                       |     | 🌐  |     | 🔧  |     |     |     |
 | [prefer-vi-mocked](docs/rules/prefer-vi-mocked.md)                                                                       | require `vi.mocked()` over `fn as Mock`                                                         |     | 🌐  |     | 🔧  |     | 💭  |     |
+| [require-awaited-expect-poll](docs/rules/require-awaited-expect-poll.md)                                                 | ensure that every `expect.poll` call is awaited                                                 |     |     |     |     |     |     |     |
 | [require-hook](docs/rules/require-hook.md)                                                                               | require setup and teardown to be within a hook                                                  |     | 🌐  |     |     |     |     |     |
 | [require-local-test-context-for-concurrent-snapshots](docs/rules/require-local-test-context-for-concurrent-snapshots.md) | require local Test Context for concurrent snapshot tests                                        | ✅  | 🌐  |     |     |     |     |     |
 | [require-mock-type-parameters](docs/rules/require-mock-type-parameters.md)                                               | enforce using type parameters with vitest mock functions                                        |     | 🌐  |     | 🔧  |     |     |     |

docs/rules/require-awaited-expect-poll.md

@@ -0,0 +1,39 @@
+# Ensure that every `expect.poll` call is awaited (`vitest/require-awaited-expect-poll`)
+
+<!-- end auto-generated rule header -->
+
+### Rule Details
+
+This rule ensures that promises returned by `expect.poll` & `expect.element` calls are handled properly.
+
+Examples of **incorrect** code for this rule:
+
+```js
+test('element exists', () => {
+  asyncInjectElement()
+
+  expect.poll(() => document.querySelector('.element')).toBeInTheDocument()
+})
+```
+
+Examples of **correct** code for this rule:
+
+```js
+test('element exists', async () => {
+  asyncInjectElement()
+
+  await expect
+    .poll(() => document.querySelector('.element'))
+    .toBeInTheDocument()
+})
+```
+
+```js
+test('element exists', () => {
+  asyncInjectElement()
+
+  return expect
+    .poll(() => document.querySelector('.element'))
+    .toBeInTheDocument()
+})
+```

src/rules/index.ts

@@ -64,6 +64,7 @@ import preferToContain from './prefer-to-contain'
 import preferToHaveLength from './prefer-to-have-length'
 import preferTodo from './prefer-todo'
 import preferViMocked from './prefer-vi-mocked'
+import requireAwaitedExpectPoll from './require-awaited-expect-poll'
 import requireHook from './require-hook'
 import requireLocalTestContextForConcurrentSnapshots from './require-local-test-context-for-concurrent-snapshots'
 import requireMockTypeParameters from './require-mock-type-parameters'
@@ -141,6 +142,7 @@ export const rules = {
   'prefer-to-have-length': preferToHaveLength,
   'prefer-todo': preferTodo,
   'prefer-vi-mocked': preferViMocked,
+  'require-awaited-expect-poll': requireAwaitedExpectPoll,
   'require-hook': requireHook,
   'require-local-test-context-for-concurrent-snapshots':
     requireLocalTestContextForConcurrentSnapshots,

src/rules/require-awaited-expect-poll.ts

@@ -0,0 +1,104 @@
+import { AST_NODE_TYPES, TSESTree } from '@typescript-eslint/utils'
+import { AccessorNode, createEslintRule, getAccessorValue } from '../utils'
+import {
+  KnownMemberExpressionProperty,
+  parseVitestFnCall,
+} from '../utils/parse-vitest-fn-call'
+
+export const RULE_NAME = 'require-awaited-expect-poll'
+export type MESSAGE_ID = 'notAwaited'
+export type Options = []
+
+export default createEslintRule<Options, MESSAGE_ID>({
+  name: RULE_NAME,
+  meta: {
+    docs: {
+      requiresTypeChecking: false,
+      recommended: false,
+      description: 'ensure that every `expect.poll` call is awaited',
+    },
+    messages: {
+      notAwaited: '`{{ method }}` calls should be awaited',
+    },
+    type: 'problem',
+    schema: [],
+  },
+  defaultOptions: [],
+  create(context) {
+    const reported = new Set<TSESTree.Node>()
+
+    return {
+      CallExpression(node) {
+        const vitestFnCall = parseVitestFnCall(node, context)
+
+        if (
+          vitestFnCall?.type !== 'expect' ||
+          !vitestFnCall.members.length ||
+          !memberRequiresAwait(vitestFnCall.members[0])
+        ) {
+          return
+        }
+
+        const nodeToReport = vitestFnCall.members[0].parent
+
+        if (reported.has(nodeToReport)) {
+          return
+        }
+
+        const topMostNode = skipSequenceExpressions(
+          skipMatchersAndModifiers(vitestFnCall.head.node),
+        )
+
+        const isHandled =
+          topMostNode.parent?.type === AST_NODE_TYPES.AwaitExpression ||
+          topMostNode.parent?.type === AST_NODE_TYPES.ReturnStatement
+
+        if (isHandled) {
+          return
+        }
+
+        context.report({
+          node: nodeToReport,
+          messageId: 'notAwaited',
+          data: {
+            method: `expect.${getAccessorValue(vitestFnCall.members[0])}`,
+          },
+        })
+
+        reported.add(nodeToReport)
+      },
+    }
+  },
+})
+
+const awaitedMembers = ['poll', 'element']
+
+function memberRequiresAwait(member: KnownMemberExpressionProperty): boolean {
+  return awaitedMembers.includes(getAccessorValue(member))
+}
+
+function skipMatchersAndModifiers(node: AccessorNode): TSESTree.Node {
+  let currentNode: TSESTree.Node = node
+
+  while (
+    currentNode.parent.type === AST_NODE_TYPES.MemberExpression ||
+    currentNode.parent.type === AST_NODE_TYPES.CallExpression
+  ) {
+    currentNode = currentNode.parent
+  }
+
+  return currentNode
+}
+
+function skipSequenceExpressions(node: TSESTree.Node): TSESTree.Node {
+  let currentNode: TSESTree.Node = node
+
+  while (
+    currentNode.parent?.type === AST_NODE_TYPES.SequenceExpression &&
+    currentNode.parent.expressions.at(-1) === currentNode
+  ) {
+    currentNode = currentNode.parent
+  }
+
+  return currentNode
+}

src/utils/parse-vitest-fn-call.ts

@@ -45,7 +45,7 @@ export interface KnownMemberExpression<Name extends string = string>
   property: AccessorNode<Name>
 }
 
-type KnownMemberExpressionProperty<Specifies extends string = string> =
+export type KnownMemberExpressionProperty<Specifies extends string = string> =
   AccessorNode<Specifies> & { parent: KnownMemberExpression<Specifies> }
 
 interface ModifiersAndMatcher {