v6.0.0 (#796)

testing-library · Aug 11, 2023 · b0fa89d · b0fa89d
1 parent 6b9c03e
commit b0fa89d
Show file tree

Hide file tree

Showing 49 changed files with 1,637 additions and 3,751 deletions.
diff --git a/.github/ISSUE_TEMPLATE/propose_new_rule.yml b/.github/ISSUE_TEMPLATE/propose_new_rule.yml
@@ -7,7 +7,7 @@ body:
     attributes:
       label: Name for new rule
       description: Suggest a name for the new rule that follows the [rule naming conventions](https://github.com/testing-library/eslint-plugin-testing-library/blob/main/CONTRIBUTING.md#rule-naming-conventions).
-      placeholder: prefer-wait-for
+      placeholder: prefer-find-by
     validations:
       required: true
 

diff --git a/README.md b/README.md
diff --git a/docs/migration-guides/v6.md b/docs/migration-guides/v6.md
@@ -0,0 +1,30 @@
+# Guide: migrating to v6
+
+If you are not on v5 yet, we recommend first following the [v5 migration guide](docs/migration-guides/v5.md).
+
+## Overview
+
+- `prefer-wait-for` was removed
+- `no-wait-for-empty-callback` was removed
+- `await-fire-event` is now called `await-async-events` with support for an `eventModule` option with `userEvent` and/or `fireEvent`
+- `await-async-events` is now enabled by default for `fireEvent` in Vue and Marko shared configs
+- `await-async-events` is now enabled by default for `userEvent` in all shared configs
+- `await-async-query` is now called `await-async-queries`
+- `no-await-async-query` is now called `no-await-async-queries`
+- `no-render-in-setup` is now called `no-render-in-lifecycle`
+- `no-await-sync-events` is now enabled by default in React, Angular, and DOM shared configs
+- `no-manual-cleanup` is now enabled by default in React and Vue shared configs
+- `no-global-regexp-flag-in-query` is now enabled by default in all shared configs
+- `no-node-access` is now enabled by default in DOM shared config
+- `no-debugging-utils` now reports all debugging utility methods by default
+- `no-debugging-utils` now defaults to `warn` instead of `error` in all shared configs
+
+## Steps to upgrade
+
+- Removing `testing-library/prefer-wait-for` if you were referencing it manually somewhere
+- Removing `testing-library/no-wait-for-empty-callback` if you were referencing it manually somewhere
+- Renaming `testing-library/await-fire-event` to `testing-library/await-async-events` if you were referencing it manually somewhere
+- Renaming `testing-library/await-async-query` to `testing-library/await-async-queries` if you were referencing it manually somewhere
+- Renaming `testing-library/no-await-async-query` to `testing-library/no-await-async-queries` if you were referencing it manually somewhere
+- Renaming `testing-library/no-render-in-setup` to `testing-library/no-render-in-lifecycle` if you were referencing it manually somewhere
+- Being aware of new rules enabled or changed above in shared configs which can lead to newly reported errors
diff --git a/docs/rules/await-async-events.md b/docs/rules/await-async-events.md
@@ -0,0 +1,149 @@
+# Enforce promises from async event methods are handled (`testing-library/await-async-events`)
+
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
+Ensure that promises returned by `userEvent` (v14+) async methods or `fireEvent` (only Vue and Marko) async methods are handled properly.
+
+## Rule Details
+
+This rule aims to prevent users from forgetting to handle promise returned from async event
+methods.
+
+> ⚠️ `fireEvent` methods are async only on following Testing Library packages:
+>
+> - `@testing-library/vue` (supported by this plugin)
+> - `@testing-library/svelte` (not supported yet by this plugin)
+> - `@marko/testing-library` (supported by this plugin)
+
+Examples of **incorrect** code for this rule:
+
+```js
+fireEvent.click(getByText('Click me'));
+
+fireEvent.focus(getByLabelText('username'));
+fireEvent.blur(getByLabelText('username'));
+
+// wrap a fireEvent method within a function...
+function triggerEvent() {
+	return fireEvent.click(button);
+}
+triggerEvent(); // ...but not handling promise from it is incorrect too
+```
+
+```js
+userEvent.click(getByText('Click me'));
+userEvent.tripleClick(getByText('Click me'));
+userEvent.keyboard('foo');
+
+// wrap a userEvent method within a function...
+function triggerEvent() {
+	return userEvent.click(button);
+}
+triggerEvent(); // ...but not handling promise from it is incorrect too
+```
+
+Examples of **correct** code for this rule:
+
+```js
+// `await` operator is correct
+await fireEvent.focus(getByLabelText('username'));
+await fireEvent.blur(getByLabelText('username'));
+
+// `then` method is correct
+fireEvent.click(getByText('Click me')).then(() => {
+	// ...
+});
+
+// return the promise within a function is correct too!
+const clickMeArrowFn = () => fireEvent.click(getByText('Click me'));
+
+// wrap a fireEvent method within a function...
+function triggerEvent() {
+	return fireEvent.click(button);
+}
+await triggerEvent(); // ...and handling promise from it is correct also
+
+// using `Promise.all` or `Promise.allSettled` with an array of promises is valid
+await Promise.all([
+	fireEvent.focus(getByLabelText('username')),
+	fireEvent.blur(getByLabelText('username')),
+]);
+```
+
+```js
+// `await` operator is correct
+await userEvent.click(getByText('Click me'));
+await userEvent.tripleClick(getByText('Click me'));
+
+// `then` method is correct
+userEvent.keyboard('foo').then(() => {
+	// ...
+});
+
+// return the promise within a function is correct too!
+const clickMeArrowFn = () => userEvent.click(getByText('Click me'));
+
+// wrap a userEvent method within a function...
+function triggerEvent() {
+	return userEvent.click(button);
+}
+await triggerEvent(); // ...and handling promise from it is correct also
+
+// using `Promise.all` or `Promise.allSettled` with an array of promises is valid
+await Promise.all([
+	userEvent.click(getByText('Click me'));
+	userEvent.tripleClick(getByText('Click me'));
+]);
+```
+
+## Options
+
+- `eventModule`: `string` or `string[]`. Which event module should be linted for async event methods. Defaults to `userEvent` which should be used after v14. `fireEvent` should only be used with frameworks that have async fire event methods.
+
+## Example
+
+```json
+{
+	"testing-library/await-async-events": [
+		2,
+		{
+			"eventModule": "userEvent"
+		}
+	]
+}
+```
+
+```json
+{
+	"testing-library/await-async-events": [
+		2,
+		{
+			"eventModule": "fireEvent"
+		}
+	]
+}
+```
+
+```json
+{
+	"testing-library/await-async-events": [
+		2,
+		{
+			"eventModule": ["fireEvent", "userEvent"]
+		}
+	]
+}
+```
+
+## When Not To Use It
+
+- `userEvent` is below v14, before all event methods are async
+- `fireEvent` methods are sync for most Testing Library packages. If you are not using Testing Library package with async events, you shouldn't use this rule.
+
+## Further Reading
+
+- [Vue Testing Library fireEvent](https://testing-library.com/docs/vue-testing-library/api#fireevent)
diff --git a/docs/rules/await-async-query.md → docs/rules/await-async-queries.md b/docs/rules/await-async-query.md → docs/rules/await-async-queries.md
@@ -1,4 +1,4 @@
-# Enforce promises from async queries to be handled (`testing-library/await-async-query`)
+# Enforce promises from async queries to be handled (`testing-library/await-async-queries`)
 
 💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
 

diff --git a/docs/rules/await-async-utils.md b/docs/rules/await-async-utils.md
@@ -10,11 +10,8 @@ Ensure that promises returned by async utils are handled properly.
 
 Testing library provides several utilities for dealing with asynchronous code. These are useful to wait for an element until certain criteria or situation happens. The available async utils are:
 
-- `waitFor` _(introduced since dom-testing-library v7)_
+- `waitFor`
 - `waitForElementToBeRemoved`
-- `wait` _(**deprecated** since dom-testing-library v7)_
-- `waitForElement` _(**deprecated** since dom-testing-library v7)_
-- `waitForDomChange` _(**deprecated** since dom-testing-library v7)_
 
 This rule aims to prevent users from forgetting to handle the returned
 promise from async utils, which could lead to

diff --git a/docs/rules/await-fire-event.md b/docs/rules/await-fire-event.md
diff --git a/docs/rules/no-await-sync-events.md b/docs/rules/no-await-sync-events.md
@@ -1,5 +1,7 @@
 # Disallow unnecessary `await` for sync events (`testing-library/no-await-sync-events`)
 
+💼 This rule is enabled in the following configs: `angular`, `dom`, `react`.
+
 <!-- end auto-generated rule header -->
 
 Ensure that sync simulated events are not awaited unnecessarily.
@@ -107,5 +109,4 @@ module.exports = {
 ## Notes
 
 - Since `user-event` v14 all its methods are async, so you should disable reporting them by setting the `eventModules` to just `"fire-event"` so `user-event` methods are not reported.
-- There is another rule `await-fire-event`, which is only in Vue Testing
-  Library. Please do not confuse with this rule.
+- There is another rule `await-async-events`, which is for awaiting async events for `user-event` v14 or `fire-event` only in Vue Testing Library. Please do not confuse with this rule.
diff --git a/docs/rules/no-await-sync-query.md → docs/rules/no-await-sync-queries.md b/docs/rules/no-await-sync-query.md → docs/rules/no-await-sync-queries.md
@@ -1,4 +1,4 @@
-# Disallow unnecessary `await` for sync queries (`testing-library/no-await-sync-query`)
+# Disallow unnecessary `await` for sync queries (`testing-library/no-await-sync-queries`)
 
 💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
 

diff --git a/docs/rules/no-debugging-utils.md b/docs/rules/no-debugging-utils.md
@@ -1,6 +1,6 @@
 # Disallow the use of debugging utilities like `debug` (`testing-library/no-debugging-utils`)
 
-💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
+⚠️ This rule _warns_ in the following configs: `angular`, `marko`, `react`, `vue`.
 
 <!-- end auto-generated rule header -->
 
@@ -17,7 +17,7 @@ This rule supports disallowing the following debugging utilities:
 - `logDOM`
 - `prettyFormat`
 
-By default, only `debug` and `logTestingPlaygroundURL` are disallowed.
+By default, all are disallowed.
 
 Examples of **incorrect** code for this rule:
 

diff --git a/docs/rules/no-global-regexp-flag-in-query.md b/docs/rules/no-global-regexp-flag-in-query.md
@@ -1,5 +1,7 @@
 # Disallow the use of the global RegExp flag (/g) in queries (`testing-library/no-global-regexp-flag-in-query`)
 
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
+
 🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
 <!-- end auto-generated rule header -->

diff --git a/docs/rules/no-manual-cleanup.md b/docs/rules/no-manual-cleanup.md
@@ -1,5 +1,7 @@
 # Disallow the use of `cleanup` (`testing-library/no-manual-cleanup`)
 
+💼 This rule is enabled in the following configs: `react`, `vue`.
+
 <!-- end auto-generated rule header -->
 
 `cleanup` is performed automatically if the testing framework you're using supports the `afterEach` global (like mocha, Jest, and Jasmine). In this case, it's unnecessary to do manual cleanups after each test unless you skip the auto-cleanup with environment variables such as `RTL_SKIP_AUTO_CLEANUP` for React.

diff --git a/docs/rules/no-node-access.md b/docs/rules/no-node-access.md
@@ -1,6 +1,6 @@
 # Disallow direct Node access (`testing-library/no-node-access`)
 
-💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
+💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
 
 <!-- end auto-generated rule header -->
 

diff --git a/docs/rules/no-render-in-setup.md → docs/rules/no-render-in-lifecycle.md b/docs/rules/no-render-in-setup.md → docs/rules/no-render-in-lifecycle.md
@@ -1,4 +1,4 @@
-# Disallow the use of `render` in testing frameworks setup functions (`testing-library/no-render-in-setup`)
+# Disallow the use of `render` in testing frameworks setup functions (`testing-library/no-render-in-lifecycle`)
 
 💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
 
@@ -87,5 +87,5 @@ it('Should have foo and bar', () => {
 If you would like to allow the use of `render` (or a custom render function) in _either_ `beforeAll` or `beforeEach`, this can be configured using the option `allowTestingFrameworkSetupHook`. This may be useful if you have configured your tests to [skip auto cleanup](https://testing-library.com/docs/react-testing-library/setup#skipping-auto-cleanup). `allowTestingFrameworkSetupHook` is an enum that accepts either `"beforeAll"` or `"beforeEach"`.
 
 ```
-   "testing-library/no-render-in-setup": ["error", {"allowTestingFrameworkSetupHook": "beforeAll"}],
+   "testing-library/no-render-in-lifecycle": ["error", {"allowTestingFrameworkSetupHook": "beforeAll"}],
 ```