docs(await-async-query): update rule description and examples

Author: Belco90

README.md

@@ -127,7 +127,7 @@ To enable this configuration use the `extends` property in your
 
 | Rule                                                                             | Description                                                                              | Configurations                                                    | Fixable            |
 | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------------ |
-| [await-async-query](docs/rules/await-async-query.md)                             | Enforce async queries to have proper `await`                                             | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] |                    |
+| [await-async-query](docs/rules/await-async-query.md)                             | Enforce promise from async queries to be handled                                         | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] |                    |
 | [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.                                      |                                                                   |                    |

docs/rules/await-async-query.md

@@ -1,4 +1,4 @@
-# Enforce async queries to have proper `await` (await-async-query)
+# Enforce promise from async queries to be handled (await-async-query)
 
 Ensure that promises returned by async queries are handled properly.
 
@@ -11,65 +11,76 @@ found. Those queries variants are:
 - `findBy*`
 - `findAllBy*`
 
-This rule aims to prevent users from forgetting to await the returned
+This rule aims to prevent users from forgetting to handle the returned
 promise from those async queries to be fulfilled, which could lead to
-errors in the tests. The promises can be handled by using either `await`
-operator or `then` method.
+errors in the tests. The promise will be considered as handled when:
+
+- using `await` operator
+- chaining `then` method
+- chaining `resolves` or `rejects` from jest
+- is returned from a function (in this case, that particular function will be analyzed by this rule too)
 
 Examples of **incorrect** code for this rule:
 
 ```js
-const foo = () => {
-  // ...
-  const rows = findAllByRole('row');
-  // ...
-};
-
-const bar = () => {
-  // ...
-  findByText('submit');
-  // ...
-};
-
-const baz = () => {
-  // ...
-  screen.findAllByPlaceholderText('name');
-  // ...
-};
+// async query without handling promise
+const rows = findAllByRole('row');
+
+findByIcon('search');
+
+screen.findAllByPlaceholderText('name');
+```
+
+```js
+// promise from async query returned within wrapper function without being handled
+const findMyButton = () => findByText('my button');
+
+const someButton = findMyButton(); // promise unhandled here
 ```
 
 Examples of **correct** code for this rule:
 
 ```js
 // `await` operator is correct
-const foo = async () => {
-  // ...
-  const rows = await findAllByRole('row');
-  // ...
-};
+const rows = await findAllByRole('row');
+
+await screen.findAllByPlaceholderText('name');
+
+const promise = findByIcon('search');
+const element = await promise;
+```
 
+```js
 // `then` method is correct
-const bar = () => {
-  // ...
-  findByText('submit').then(() => {
-    // ...
-  });
-};
-
-const baz = () => {
-  // ...
-  await screen.findAllByPlaceholderText('name');
-  // ...
-};
+findByText('submit').then(() => {});
 
+const promise = findByRole('button');
+promise.then(() => {});
+```
+
+```js
 // return the promise within a function is correct too!
 const findMyButton = () => findByText('my button');
+```
+
+```js
+// promise from async query returned within wrapper function being handled
+const findMyButton = () => findByText('my button');
 
+const someButton = await findMyButton();
+```
+
+```js
 // using a resolves/rejects matcher is also correct
 expect(findByTestId('alert')).resolves.toBe('Success');
 expect(findByTestId('alert')).rejects.toBe('Error');
 ```
 
+```js
+// sync queries don't need to handle any promise
+const element = getByRole('role');
+```
+
 ## Further Reading
 
 - [Async queries variants](https://testing-library.com/docs/dom-testing-library/api-queries#findby)

lib/node-utils.ts

@@ -216,9 +216,9 @@ export function hasChainedThen(node: TSESTree.Node): boolean {
  * Determines whether an Identifier related to a promise is considered as handled.
  *
  * It will be considered as handled if:
- * - it belongs to await expression
+ * - it belongs to `await` expression
+ * - it's chained with `then` method
  * - it's returned from a function
- * - it's resolved with `then` method
  * - has `resolves` or `rejects`
  */
 export function isPromiseHandled(nodeIdentifier: TSESTree.Identifier): boolean {

lib/rules/await-async-query.ts

@@ -19,7 +19,7 @@ export default createTestingLibraryRule<Options, MessageIds>({
   meta: {
     type: 'problem',
     docs: {
-      description: 'Enforce async queries to have proper `await`',
+      description: 'Enforce promise from async queries to be handled',
       category: 'Best Practices',
       recommended: 'warn',
     },