From 7ba1408c94e7aa9dc1b5b4a2b6a5fddf493c1bcd Mon Sep 17 00:00:00 2001 From: Bryan Mishkin <698306+bmish@users.noreply.github.com> Date: Sat, 19 Nov 2022 18:03:03 -0500 Subject: [PATCH] docs: automate docs with eslint-doc-generator --- README.md | 83 +++++++++--------- docs/rules/await-async-query.md | 4 + docs/rules/await-async-utils.md | 6 +- docs/rules/await-fire-event.md | 6 +- docs/rules/consistent-data-testid.md | 4 +- docs/rules/no-await-sync-events.md | 2 + docs/rules/no-await-sync-query.md | 4 + docs/rules/no-container.md | 4 + docs/rules/no-debugging-utils.md | 8 +- docs/rules/no-dom-import.md | 6 ++ docs/rules/no-global-regexp-flag-in-query.md | 4 + docs/rules/no-manual-cleanup.md | 2 + docs/rules/no-node-access.md | 4 + docs/rules/no-promise-in-fire-event.md | 4 + docs/rules/no-render-in-setup.md | 8 +- docs/rules/no-unnecessary-act.md | 4 + docs/rules/no-wait-for-empty-callback.md | 6 +- docs/rules/no-wait-for-multiple-assertions.md | 6 +- docs/rules/no-wait-for-side-effects.md | 6 +- docs/rules/no-wait-for-snapshot.md | 6 +- docs/rules/prefer-explicit-assert.md | 4 +- docs/rules/prefer-find-by.md | 8 +- docs/rules/prefer-presence-queries.md | 6 +- docs/rules/prefer-query-by-disappearance.md | 4 + docs/rules/prefer-screen-queries.md | 4 + docs/rules/prefer-user-event.md | 4 +- docs/rules/prefer-wait-for.md | 4 + docs/rules/render-result-naming-convention.md | 4 + package.json | 13 ++- tools/generate-rules-list/index.ts | 26 ------ tools/generate-rules-list/utils.ts | 87 ------------------- 31 files changed, 169 insertions(+), 172 deletions(-) delete mode 100644 tools/generate-rules-list/index.ts delete mode 100644 tools/generate-rules-list/utils.ts diff --git a/README.md b/README.md index 8b267815..3644847c 100644 --- a/README.md +++ b/README.md @@ -198,43 +198,42 @@ To enable this configuration use the `extends` property in your > Remember that all rules from this plugin are prefixed by `"testing-library/"` - - -**Key**: 🔧 = fixable - -**Configurations**: ![dom-badge][] = dom, ![angular-badge][] = angular, ![react-badge][] = react, ![vue-badge][] = vue, ![marko-badge][] = marko - -| Name | Description | 🔧 | Included in configurations | -| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | --- | ---------------------------------------------------------------------------------- | -| [`await-async-query`](./docs/rules/await-async-query.md) | Enforce promises from async queries to be handled | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`await-async-utils`](./docs/rules/await-async-utils.md) | Enforce promises from async utils to be awaited properly | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`await-fire-event`](./docs/rules/await-fire-event.md) | Enforce promises from `fireEvent` methods to be handled | | ![vue-badge][] ![marko-badge][] | -| [`consistent-data-testid`](./docs/rules/consistent-data-testid.md) | Ensures consistent usage of `data-testid` | | | -| [`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][] ![marko-badge][] | -| [`no-container`](./docs/rules/no-container.md) | Disallow the use of `container` methods | | ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`no-debugging-utils`](./docs/rules/no-debugging-utils.md) | Disallow the use of debugging utilities like `debug` | | ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`no-dom-import`](./docs/rules/no-dom-import.md) | Disallow importing from DOM Testing Library | 🔧 | ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`no-global-regexp-flag-in-query`](./docs/rules/no-global-regexp-flag-in-query.md) | Disallow the use of the global RegExp flag (/g) in queries | 🔧 | | -| [`no-manual-cleanup`](./docs/rules/no-manual-cleanup.md) | Disallow the use of `cleanup` | | | -| [`no-node-access`](./docs/rules/no-node-access.md) | Disallow direct Node access | | ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`no-promise-in-fire-event`](./docs/rules/no-promise-in-fire-event.md) | Disallow the use of promises passed to a `fireEvent` method | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`no-render-in-setup`](./docs/rules/no-render-in-setup.md) | Disallow the use of `render` in testing frameworks setup functions | | ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`no-unnecessary-act`](./docs/rules/no-unnecessary-act.md) | Disallow wrapping Testing Library utils or empty callbacks in `act` | | ![react-badge][] ![marko-badge][] | -| [`no-wait-for-empty-callback`](./docs/rules/no-wait-for-empty-callback.md) | Disallow empty callbacks for `waitFor` and `waitForElementToBeRemoved` | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`no-wait-for-multiple-assertions`](./docs/rules/no-wait-for-multiple-assertions.md) | Disallow the use of multiple `expect` calls inside `waitFor` | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`no-wait-for-side-effects`](./docs/rules/no-wait-for-side-effects.md) | Disallow the use of side effects in `waitFor` | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`no-wait-for-snapshot`](./docs/rules/no-wait-for-snapshot.md) | Ensures no snapshot is generated inside of a `waitFor` call | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`prefer-explicit-assert`](./docs/rules/prefer-explicit-assert.md) | Suggest using explicit assertions rather than standalone queries | | | -| [`prefer-find-by`](./docs/rules/prefer-find-by.md) | Suggest using `find(All)By*` query instead of `waitFor` + `get(All)By*` to wait for elements | 🔧 | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`prefer-presence-queries`](./docs/rules/prefer-presence-queries.md) | Ensure appropriate `get*`/`query*` queries are used with their respective matchers | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`prefer-query-by-disappearance`](./docs/rules/prefer-query-by-disappearance.md) | Suggest using `queryBy*` queries when waiting for disappearance | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`prefer-screen-queries`](./docs/rules/prefer-screen-queries.md) | Suggest using `screen` while querying | | ![dom-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | -| [`prefer-user-event`](./docs/rules/prefer-user-event.md) | Suggest using `userEvent` over `fireEvent` for simulating user interactions | | | -| [`prefer-wait-for`](./docs/rules/prefer-wait-for.md) | Use `waitFor` instead of deprecated wait methods | 🔧 | | -| [`render-result-naming-convention`](./docs/rules/render-result-naming-convention.md) | Enforce a valid naming for return value from `render` | | ![angular-badge][] ![react-badge][] ![vue-badge][] ![marko-badge][] | - - + + +💼 Configurations enabled in.\ +🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix). + +| Name                            | Description | 💼 | 🔧 | +| :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- | :-- | +| [await-async-query](../docs/rules/await-async-query.md) | Enforce promises from async queries to be handled | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [await-async-utils](../docs/rules/await-async-utils.md) | Enforce promises from async utils to be awaited properly | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [await-fire-event](../docs/rules/await-fire-event.md) | Enforce promises from `fireEvent` methods to be handled | ![badge-marko][] ![badge-vue][] | | +| [consistent-data-testid](../docs/rules/consistent-data-testid.md) | Ensures consistent usage of `data-testid` | | | +| [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 | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [no-container](../docs/rules/no-container.md) | Disallow the use of `container` methods | ![badge-angular][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [no-debugging-utils](../docs/rules/no-debugging-utils.md) | Disallow the use of debugging utilities like `debug` | ![badge-angular][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [no-dom-import](../docs/rules/no-dom-import.md) | Disallow importing from DOM Testing Library | ![badge-angular][] ![badge-marko][] ![badge-react][] ![badge-vue][] | 🔧 | +| [no-global-regexp-flag-in-query](../docs/rules/no-global-regexp-flag-in-query.md) | Disallow the use of the global RegExp flag (/g) in queries | | 🔧 | +| [no-manual-cleanup](../docs/rules/no-manual-cleanup.md) | Disallow the use of `cleanup` | | | +| [no-node-access](../docs/rules/no-node-access.md) | Disallow direct Node access | ![badge-angular][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [no-promise-in-fire-event](../docs/rules/no-promise-in-fire-event.md) | Disallow the use of promises passed to a `fireEvent` method | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [no-render-in-setup](../docs/rules/no-render-in-setup.md) | Disallow the use of `render` in testing frameworks setup functions | ![badge-angular][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [no-unnecessary-act](../docs/rules/no-unnecessary-act.md) | Disallow wrapping Testing Library utils or empty callbacks in `act` | ![badge-marko][] ![badge-react][] | | +| [no-wait-for-empty-callback](../docs/rules/no-wait-for-empty-callback.md) | Disallow empty callbacks for `waitFor` and `waitForElementToBeRemoved` | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [no-wait-for-multiple-assertions](../docs/rules/no-wait-for-multiple-assertions.md) | Disallow the use of multiple `expect` calls inside `waitFor` | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [no-wait-for-side-effects](../docs/rules/no-wait-for-side-effects.md) | Disallow the use of side effects in `waitFor` | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [no-wait-for-snapshot](../docs/rules/no-wait-for-snapshot.md) | Ensures no snapshot is generated inside of a `waitFor` call | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [prefer-explicit-assert](../docs/rules/prefer-explicit-assert.md) | Suggest using explicit assertions rather than standalone queries | | | +| [prefer-find-by](../docs/rules/prefer-find-by.md) | Suggest using `find(All)By*` query instead of `waitFor` + `get(All)By*` to wait for elements | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | 🔧 | +| [prefer-presence-queries](../docs/rules/prefer-presence-queries.md) | Ensure appropriate `get*`/`query*` queries are used with their respective matchers | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [prefer-query-by-disappearance](../docs/rules/prefer-query-by-disappearance.md) | Suggest using `queryBy*` queries when waiting for disappearance | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [prefer-screen-queries](../docs/rules/prefer-screen-queries.md) | Suggest using `screen` while querying | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | +| [prefer-user-event](../docs/rules/prefer-user-event.md) | Suggest using `userEvent` over `fireEvent` for simulating user interactions | | | +| [prefer-wait-for](../docs/rules/prefer-wait-for.md) | Use `waitFor` instead of deprecated wait methods | | 🔧 | +| [render-result-naming-convention](../docs/rules/render-result-naming-convention.md) | Enforce a valid naming for return value from `render` | ![badge-angular][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | + + ## Aggressive Reporting @@ -443,8 +442,8 @@ This project follows the [all-contributors](https://github.com/all-contributors/ [gh-stars-url]: https://github.com/testing-library/eslint-plugin-testing-library/stargazers [tweet-badge]: https://img.shields.io/twitter/url?style=social&url=https%3A%2F%2Fgithub.com%2Ftesting-library%2Feslint-plugin-testing-library [tweet-url]: https://twitter.com/intent/tweet?url=https%3a%2f%2fgithub.com%2ftesting-library%2feslint-plugin-testing-library&text=check%20out%20eslint-plugin-testing-library%20by%20@belcodev -[dom-badge]: https://img.shields.io/badge/%F0%9F%90%99-DOM-black?style=flat-square -[angular-badge]: https://img.shields.io/badge/-Angular-black?style=flat-square&logo=angular&logoColor=white&labelColor=DD0031&color=black -[react-badge]: https://img.shields.io/badge/-React-black?style=flat-square&logo=react&logoColor=white&labelColor=61DAFB&color=black -[vue-badge]: https://img.shields.io/badge/-Vue-black?style=flat-square&logo=vue.js&logoColor=white&labelColor=4FC08D&color=black -[marko-badge]: https://img.shields.io/badge/-Marko-black?style=flat-square&logo=marko&logoColor=white&labelColor=2596BE&color=black +[badge-dom]: https://img.shields.io/badge/%F0%9F%90%99-DOM-black?style=flat-square +[badge-angular]: https://img.shields.io/badge/-Angular-black?style=flat-square&logo=angular&logoColor=white&labelColor=DD0031&color=black +[badge-react]: https://img.shields.io/badge/-React-black?style=flat-square&logo=react&logoColor=white&labelColor=61DAFB&color=black +[badge-vue]: https://img.shields.io/badge/-Vue-black?style=flat-square&logo=vue.js&logoColor=white&labelColor=4FC08D&color=black +[badge-marko]: https://img.shields.io/badge/-Marko-black?style=flat-square&logo=marko&logoColor=white&labelColor=2596BE&color=black diff --git a/docs/rules/await-async-query.md b/docs/rules/await-async-query.md index 608b9477..6852fc24 100644 --- a/docs/rules/await-async-query.md +++ b/docs/rules/await-async-query.md @@ -1,5 +1,9 @@ # Enforce promises from async queries to be handled (`testing-library/await-async-query`) +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + + Ensure that promises returned by async queries are handled properly. ## Rule Details diff --git a/docs/rules/await-async-utils.md b/docs/rules/await-async-utils.md index f27f92df..86119f64 100644 --- a/docs/rules/await-async-utils.md +++ b/docs/rules/await-async-utils.md @@ -1,4 +1,8 @@ -# Enforce promises from async utils to be handled (`testing-library/await-async-utils`) +# Enforce promises from async utils to be awaited properly (`testing-library/await-async-utils`) + +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + Ensure that promises returned by async utils are handled properly. diff --git a/docs/rules/await-fire-event.md b/docs/rules/await-fire-event.md index 2a3fa4b0..5c1002ef 100644 --- a/docs/rules/await-fire-event.md +++ b/docs/rules/await-fire-event.md @@ -1,4 +1,8 @@ -# Enforce promises from fire event methods to be handled (`testing-library/await-fire-event`) +# Enforce promises from `fireEvent` methods to be handled (`testing-library/await-fire-event`) + +💼 This rule is enabled in the following configs: `marko`, `vue`. + + Ensure that promises returned by `fireEvent` methods are handled properly. diff --git a/docs/rules/consistent-data-testid.md b/docs/rules/consistent-data-testid.md index f74ce83b..0cfc3406 100644 --- a/docs/rules/consistent-data-testid.md +++ b/docs/rules/consistent-data-testid.md @@ -1,4 +1,6 @@ -# Enforces consistent naming for the data-testid attribute (`testing-library/consistent-data-testid`) +# Ensures consistent usage of `data-testid` (`testing-library/consistent-data-testid`) + + Ensure `data-testid` values match a provided regex. This rule is un-opinionated, and requires configuration. diff --git a/docs/rules/no-await-sync-events.md b/docs/rules/no-await-sync-events.md index ae891577..a8e900b6 100644 --- 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`) + + Ensure that sync simulated events are not awaited unnecessarily. ## Rule Details diff --git a/docs/rules/no-await-sync-query.md b/docs/rules/no-await-sync-query.md index c86baf47..79046767 100644 --- a/docs/rules/no-await-sync-query.md +++ b/docs/rules/no-await-sync-query.md @@ -1,5 +1,9 @@ # Disallow unnecessary `await` for sync queries (`testing-library/no-await-sync-query`) +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + + Ensure that sync queries are not awaited unnecessarily. ## Rule Details diff --git a/docs/rules/no-container.md b/docs/rules/no-container.md index c764c641..aab7c8ac 100644 --- a/docs/rules/no-container.md +++ b/docs/rules/no-container.md @@ -1,5 +1,9 @@ # Disallow the use of `container` methods (`testing-library/no-container`) +💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`. + + + By using `container` methods like `.querySelector` you may lose a lot of the confidence that the user can really interact with your UI. Also, the test becomes harder to read, and it will break more frequently. This applies to Testing Library frameworks built on top of **DOM Testing Library** diff --git a/docs/rules/no-debugging-utils.md b/docs/rules/no-debugging-utils.md index 7628e04a..288ee508 100644 --- a/docs/rules/no-debugging-utils.md +++ b/docs/rules/no-debugging-utils.md @@ -1,4 +1,8 @@ -# Disallow the use of debugging utilities (`testing-library/no-debugging-utils`) +# 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`. + + Just like `console.log` statements pollutes the browser's output, debug statements also pollutes the tests if one of your teammates forgot to remove it. `debug` statements should be used when you actually want to debug your tests but should not be pushed to the codebase. @@ -37,6 +41,8 @@ const { screen } = require('@testing-library/react'); screen.debug(); ``` +## Options + You can control which debugging utils are checked for with the `utilsToCheckFor` option: ```json diff --git a/docs/rules/no-dom-import.md b/docs/rules/no-dom-import.md index c61cd405..93ae97d0 100644 --- a/docs/rules/no-dom-import.md +++ b/docs/rules/no-dom-import.md @@ -1,5 +1,11 @@ # Disallow importing from DOM Testing Library (`testing-library/no-dom-import`) +💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`. + +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + Ensure that there are no direct imports from `@testing-library/dom` or `dom-testing-library` when using some testing library framework wrapper. diff --git a/docs/rules/no-global-regexp-flag-in-query.md b/docs/rules/no-global-regexp-flag-in-query.md index 61ebed20..41469460 100644 --- a/docs/rules/no-global-regexp-flag-in-query.md +++ b/docs/rules/no-global-regexp-flag-in-query.md @@ -1,5 +1,9 @@ # Disallow the use of the global RegExp flag (/g) in queries (`testing-library/no-global-regexp-flag-in-query`) +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + Ensure that there are no global RegExp flags used when using queries. ## Rule Details diff --git a/docs/rules/no-manual-cleanup.md b/docs/rules/no-manual-cleanup.md index 4b63f88f..ebd8d427 100644 --- 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`) + + `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. ## Rule Details diff --git a/docs/rules/no-node-access.md b/docs/rules/no-node-access.md index d5688657..4f90c681 100644 --- a/docs/rules/no-node-access.md +++ b/docs/rules/no-node-access.md @@ -1,5 +1,9 @@ # Disallow direct Node access (`testing-library/no-node-access`) +💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`. + + + The Testing Library already provides methods for querying DOM elements. ## Rule Details diff --git a/docs/rules/no-promise-in-fire-event.md b/docs/rules/no-promise-in-fire-event.md index 3bd5dd5f..37e3b597 100644 --- a/docs/rules/no-promise-in-fire-event.md +++ b/docs/rules/no-promise-in-fire-event.md @@ -1,5 +1,9 @@ # Disallow the use of promises passed to a `fireEvent` method (`testing-library/no-promise-in-fire-event`) +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + + Methods from `fireEvent` expect to receive a DOM element. Passing a promise will end up in an error, so it must be prevented. Examples of **incorrect** code for this rule: diff --git a/docs/rules/no-render-in-setup.md b/docs/rules/no-render-in-setup.md index cd27e366..d5a60e0b 100644 --- a/docs/rules/no-render-in-setup.md +++ b/docs/rules/no-render-in-setup.md @@ -1,4 +1,8 @@ -# Disallow the use of `render` in setup functions (`testing-library/no-render-in-setup`) +# Disallow the use of `render` in testing frameworks setup functions (`testing-library/no-render-in-setup`) + +💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`. + + ## Rule Details @@ -74,6 +78,8 @@ it('Should have foo and bar', () => { }); ``` +## Options + 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"`. ``` diff --git a/docs/rules/no-unnecessary-act.md b/docs/rules/no-unnecessary-act.md index 019f5661..3b0d2bcb 100644 --- a/docs/rules/no-unnecessary-act.md +++ b/docs/rules/no-unnecessary-act.md @@ -1,5 +1,9 @@ # Disallow wrapping Testing Library utils or empty callbacks in `act` (`testing-library/no-unnecessary-act`) +💼 This rule is enabled in the following configs: `marko`, `react`. + + + > ⚠️ The `act` method is only available on the following Testing Library packages: > > - `@testing-library/react` (supported by this plugin) diff --git a/docs/rules/no-wait-for-empty-callback.md b/docs/rules/no-wait-for-empty-callback.md index 2bcf48d5..b92fc3a2 100644 --- a/docs/rules/no-wait-for-empty-callback.md +++ b/docs/rules/no-wait-for-empty-callback.md @@ -1,4 +1,8 @@ -# Empty callbacks inside `waitFor` and `waitForElementToBeRemoved` are not preferred (`testing-library/no-wait-for-empty-callback`) +# Disallow empty callbacks for `waitFor` and `waitForElementToBeRemoved` (`testing-library/no-wait-for-empty-callback`) + +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + ## Rule Details diff --git a/docs/rules/no-wait-for-multiple-assertions.md b/docs/rules/no-wait-for-multiple-assertions.md index 82a33204..ee418cf9 100644 --- a/docs/rules/no-wait-for-multiple-assertions.md +++ b/docs/rules/no-wait-for-multiple-assertions.md @@ -1,4 +1,8 @@ -# Disallow the use of multiple expect inside `waitFor` (`testing-library/no-wait-for-multiple-assertions`) +# Disallow the use of multiple `expect` calls inside `waitFor` (`testing-library/no-wait-for-multiple-assertions`) + +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + ## Rule Details diff --git a/docs/rules/no-wait-for-side-effects.md b/docs/rules/no-wait-for-side-effects.md index 741a91a3..475b06de 100644 --- a/docs/rules/no-wait-for-side-effects.md +++ b/docs/rules/no-wait-for-side-effects.md @@ -1,4 +1,8 @@ -# Disallow the use of side effects inside `waitFor` (`testing-library/no-wait-for-side-effects`) +# Disallow the use of side effects in `waitFor` (`testing-library/no-wait-for-side-effects`) + +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + ## Rule Details diff --git a/docs/rules/no-wait-for-snapshot.md b/docs/rules/no-wait-for-snapshot.md index 1af66404..470d07bc 100644 --- a/docs/rules/no-wait-for-snapshot.md +++ b/docs/rules/no-wait-for-snapshot.md @@ -1,4 +1,8 @@ -# Ensures no snapshot is generated inside a `waitFor` call (`testing-library/no-wait-for-snapshot`) +# Ensures no snapshot is generated inside of a `waitFor` call (`testing-library/no-wait-for-snapshot`) + +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + Ensure that no calls to `toMatchSnapshot` or `toMatchInlineSnapshot` are made from within a `waitFor` method (or any of the other async utility methods). diff --git a/docs/rules/prefer-explicit-assert.md b/docs/rules/prefer-explicit-assert.md index 1937dc30..a5c6fc93 100644 --- a/docs/rules/prefer-explicit-assert.md +++ b/docs/rules/prefer-explicit-assert.md @@ -1,4 +1,6 @@ -# Suggest using explicit assertions rather than just `getBy*` queries (`testing-library/prefer-explicit-assert`) +# Suggest using explicit assertions rather than standalone queries (`testing-library/prefer-explicit-assert`) + + Testing Library `getBy*` queries throw an error if the element is not found. Some users like this behavior to use the query itself as an diff --git a/docs/rules/prefer-find-by.md b/docs/rules/prefer-find-by.md index fd152ee6..257af7a2 100644 --- a/docs/rules/prefer-find-by.md +++ b/docs/rules/prefer-find-by.md @@ -1,4 +1,10 @@ -# Suggest using `findBy*` methods instead of the `waitFor` + `getBy` queries (`testing-library/prefer-find-by`) +# Suggest using `find(All)By*` query instead of `waitFor` + `get(All)By*` to wait for elements (`testing-library/prefer-find-by`) + +💼 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). + + `findBy*` queries are a simple combination of `getBy*` queries and `waitFor`. The `findBy*` queries accept the `waitFor` options as the last argument. (i.e. `screen.findByText('text', queryOptions, waitForOptions)`) diff --git a/docs/rules/prefer-presence-queries.md b/docs/rules/prefer-presence-queries.md index 93e81f0d..ecd100a2 100644 --- a/docs/rules/prefer-presence-queries.md +++ b/docs/rules/prefer-presence-queries.md @@ -1,4 +1,8 @@ -# Enforce specific queries when checking element is present or not (`testing-library/prefer-presence-queries`) +# Ensure appropriate `get*`/`query*` queries are used with their respective matchers (`testing-library/prefer-presence-queries`) + +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + The (DOM) Testing Library allows to query DOM elements using different types of queries such as `get*` and `query*`. Using `get*` throws an error in case the element is not found, while `query*` returns null instead of throwing (or empty array for `queryAllBy*` ones). These differences are useful in some situations: diff --git a/docs/rules/prefer-query-by-disappearance.md b/docs/rules/prefer-query-by-disappearance.md index a0eabef2..dcf35a20 100644 --- a/docs/rules/prefer-query-by-disappearance.md +++ b/docs/rules/prefer-query-by-disappearance.md @@ -1,5 +1,9 @@ # Suggest using `queryBy*` queries when waiting for disappearance (`testing-library/prefer-query-by-disappearance`) +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + + ## Rule Details This rule enforces using `queryBy*` queries when waiting for disappearance with `waitForElementToBeRemoved`. diff --git a/docs/rules/prefer-screen-queries.md b/docs/rules/prefer-screen-queries.md index fa8efe52..4e562f5d 100644 --- a/docs/rules/prefer-screen-queries.md +++ b/docs/rules/prefer-screen-queries.md @@ -1,5 +1,9 @@ # Suggest using `screen` while querying (`testing-library/prefer-screen-queries`) +💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`. + + + ## Rule Details DOM Testing Library (and other Testing Library frameworks built on top of it) exports a `screen` object which has every query (and a `debug` method). This works better with autocomplete and makes each test a little simpler to write and maintain. diff --git a/docs/rules/prefer-user-event.md b/docs/rules/prefer-user-event.md index 8508b5b6..0daecd0b 100644 --- a/docs/rules/prefer-user-event.md +++ b/docs/rules/prefer-user-event.md @@ -1,4 +1,6 @@ -# Suggest using `userEvent` library instead of `fireEvent` for simulating user interaction (`testing-library/prefer-user-event`) +# Suggest using `userEvent` over `fireEvent` for simulating user interactions (`testing-library/prefer-user-event`) + + From [testing-library/dom-testing-library#107](https://github.com/testing-library/dom-testing-library/issues/107): diff --git a/docs/rules/prefer-wait-for.md b/docs/rules/prefer-wait-for.md index 449548fd..a3b59bc6 100644 --- a/docs/rules/prefer-wait-for.md +++ b/docs/rules/prefer-wait-for.md @@ -1,5 +1,9 @@ # Use `waitFor` instead of deprecated wait methods (`testing-library/prefer-wait-for`) +🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + + `dom-testing-library` v7 released a new async util called `waitFor` which satisfies the use cases of `wait`, `waitForElement`, and `waitForDomChange` making them deprecated. ## Rule Details diff --git a/docs/rules/render-result-naming-convention.md b/docs/rules/render-result-naming-convention.md index f9e2e4fe..5d76ab2c 100644 --- a/docs/rules/render-result-naming-convention.md +++ b/docs/rules/render-result-naming-convention.md @@ -1,5 +1,9 @@ # Enforce a valid naming for return value from `render` (`testing-library/render-result-naming-convention`) +💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`. + + + > The name `wrapper` is old cruft from `enzyme` and we don't need that here. The return value from `render` is not "wrapping" anything. It's simply a collection of utilities that you should actually not often need anyway. ## Rule Details diff --git a/package.json b/package.json index 883ae092..c5570a4a 100644 --- a/package.json +++ b/package.json @@ -30,10 +30,13 @@ "postbuild": "cpy README.md ./dist && cpy package.json ./dist && cpy LICENSE ./dist", "format": "prettier --write .", "format:check": "prettier --check .", - "generate:configs": "ts-node tools/generate-configs", - "generate:rules-list": "ts-node tools/generate-rules-list", - "lint": "eslint . --max-warnings 0 --ext .js,.ts", - "lint:fix": "npm run lint -- --fix", + "generate": "npm-run-all \"generate:*\"", + "generate:configs": "ts-node tools/generate-configs && npm run format", + "generate:rules-list": "npm run build && eslint-doc-generator --path-rule-list \"../README.md\" --path-rule-doc \"../docs/rules/{name}.md\" dist/ && npm run format", + "lint": "npm-run-all \"lint:*\"", + "lint:generate": "npm run generate && git diff --exit-code", + "lint:js": "eslint . --max-warnings 0 --ext .js,.ts", + "lint:js:fix": "npm run lint:js -- --fix", "prepare": "is-ci || husky install", "semantic-release": "semantic-release", "test": "jest", @@ -59,6 +62,7 @@ "eslint": "^8.28.0", "eslint-config-kentcdodds": "^20.4.0", "eslint-config-prettier": "^8.5.0", + "eslint-doc-generator": "^0.24.0", "eslint-plugin-import": "^2.26.0", "eslint-plugin-jest": "^27.1.5", "eslint-plugin-jest-formatting": "^3.1.0", @@ -71,6 +75,7 @@ "is-ci": "^3.0.1", "jest": "^28.1.3", "lint-staged": "^13.0.3", + "npm-run-all": "^4.1.5", "prettier": "2.7.1", "semantic-release": "^19.0.5", "ts-jest": "^28.0.8", diff --git a/tools/generate-rules-list/index.ts b/tools/generate-rules-list/index.ts deleted file mode 100644 index ef1c04b0..00000000 --- a/tools/generate-rules-list/index.ts +++ /dev/null @@ -1,26 +0,0 @@ -import rules from '../../lib/rules'; -import type { TestingLibraryRuleMetaDocs } from '../../lib/utils'; - -import { configBadges, emojiKey, RulesList, writeRulesList } from './utils'; - -export const createRuleLink = (ruleName: string): string => - `[\`${ruleName}\`](./docs/rules/${ruleName}.md)`; - -export const generateConfigBadges = ( - recommendedConfig: TestingLibraryRuleMetaDocs['recommendedConfig'] -): string => - Object.entries(recommendedConfig) - .filter(([_, config]) => Boolean(config)) - .map(([framework]) => configBadges[framework]) - .join(' '); - -const rulesList: RulesList = Object.entries(rules) - .sort(([ruleNameA], [ruleNameB]) => ruleNameA.localeCompare(ruleNameB)) - .map(([name, rule]) => [ - createRuleLink(name), - rule.meta.docs.description, - Boolean(rule.meta.fixable) ? emojiKey.fixable : '', - generateConfigBadges(rule.meta.docs.recommendedConfig), - ]); - -writeRulesList(rulesList); diff --git a/tools/generate-rules-list/utils.ts b/tools/generate-rules-list/utils.ts deleted file mode 100644 index b7237e56..00000000 --- a/tools/generate-rules-list/utils.ts +++ /dev/null @@ -1,87 +0,0 @@ -import { readFileSync, writeFileSync } from 'fs'; -import { resolve } from 'path'; - -import { format, resolveConfig } from 'prettier'; - -import { - SUPPORTED_TESTING_FRAMEWORKS, - SupportedTestingFramework, -} from '../../lib/utils'; - -const prettierConfig = resolveConfig.sync(__dirname); -const readmePath = resolve(__dirname, `../../README.md`); - -export type RulesList = string[][]; - -export const configBadges = SUPPORTED_TESTING_FRAMEWORKS.reduce( - (badges, framework) => ({ - ...badges, - [framework]: `![${framework}-badge][]`, - }), - {} -) as Record; -export const emojiKey = { - fixable: '🔧', -} as const; -const staticElements = { - listHeaderRow: [ - 'Name', - 'Description', - emojiKey.fixable, - 'Included in configurations', - ], - listSpacerRow: Array(4).fill('-'), - rulesListKey: [ - `**Key**: ${emojiKey.fixable} = fixable`, - '', - [ - `**Configurations**:`, - Object.entries(configBadges) - .map(([template, badge]) => `${badge} = ${template}`) - .join(', '), - ].join(' '), - ].join('\n'), -}; - -const generateRulesListTable = (rulesList: RulesList) => - [staticElements.listHeaderRow, staticElements.listSpacerRow, ...rulesList] - .map((column) => `|${column.join('|')}|`) - .join('\n'); - -const generateRulesListMarkdown = (rulesList: RulesList) => - [ - '', - staticElements.rulesListKey, - '', - generateRulesListTable(rulesList), - '', - ].join('\n'); - -const listBeginMarker = ''; -const listEndMarker = ''; -const overWriteRulesList = (rulesList: RulesList, readme: string) => { - const listStartIndex = readme.indexOf(listBeginMarker); - const listEndIndex = readme.indexOf(listEndMarker); - - if ([listStartIndex, listEndIndex].includes(-1)) { - throw new Error(`cannot find start or end rules-list`); - } - - return [ - readme.substring(0, listStartIndex - 1), - listBeginMarker, - '', - generateRulesListMarkdown(rulesList), - readme.substring(listEndIndex), - ].join('\n'); -}; - -export const writeRulesList = (rulesList: RulesList): void => { - const readme = readFileSync(readmePath, 'utf8'); - const newReadme = format(overWriteRulesList(rulesList, readme), { - parser: 'markdown', - ...prettierConfig, - }); - - writeFileSync(readmePath, newReadme); -};