Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/testing-library/eslint-plugin-testing-library
ESLint plugin to follow best practices and anticipate common mistakes when writing tests with Testing Library
https://github.com/testing-library/eslint-plugin-testing-library
angular best-practices development dom eslint eslint-plugin javascript markojs react reactjs testing-library vue
Last synced: about 2 months ago
JSON representation
ESLint plugin to follow best practices and anticipate common mistakes when writing tests with Testing Library
- Host: GitHub
- URL: https://github.com/testing-library/eslint-plugin-testing-library
- Owner: testing-library
- License: mit
- Created: 2019-09-01T18:12:58.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-12T12:29:56.000Z (5 months ago)
- Last Synced: 2024-04-14T06:45:24.917Z (5 months ago)
- Topics: angular, best-practices, development, dom, eslint, eslint-plugin, javascript, markojs, react, reactjs, testing-library, vue
- Language: TypeScript
- Homepage: https://npm.im/eslint-plugin-testing-library
- Size: 2.25 MB
- Stars: 952
- Watchers: 10
- Forks: 130
- Open Issues: 45
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-list - eslint-plugin-testing-library - library | 484 | (TypeScript)
- awesome-eslint - Testing Library - Linting rules for Testing Library. (Plugins / Testing Tools)
README
eslint-plugin-testing-library
ESLint plugin to follow best practices and anticipate common mistakes when writing tests with Testing Library
---
[![Package version][version-badge]][version-url]
[![eslint-remote-tester][eslint-remote-tester-badge]][eslint-remote-tester-workflow]
[![eslint-plugin-testing-library][package-health-badge]][package-health-url]
[](https://codecov.io/gh/testing-library/eslint-plugin-testing-library)
[![MIT License][license-badge]][license-url]
[](https://github.com/semantic-release/semantic-release)
[![PRs Welcome][pr-badge]][pr-url]
[![All Contributors][all-contributors-badge]](#contributors-)
## Installation
You'll first need to install [ESLint](https://eslint.org):
```shell
$ npm install --save-dev eslint
# or
$ yarn add --dev eslint
```
Next, install `eslint-plugin-testing-library`:
```shell
$ npm install --save-dev eslint-plugin-testing-library
# or
$ yarn add --dev eslint-plugin-testing-library
```
**Note:** If you installed ESLint globally (using the `-g` flag) then you must also install `eslint-plugin-testing-library` globally.
## Migrating
You can find detailed guides for migrating `eslint-plugin-testing-library` in the [migration guide docs](docs/migration-guides):
- [Migration guide for v4](docs/migration-guides/v4.md)
- [Migration guide for v5](docs/migration-guides/v5.md)
- [Migration guide for v6](docs/migration-guides/v6.md)
## Usage
Add `testing-library` to the plugins section of your `.eslintrc.js` configuration file. You can omit the `eslint-plugin-` prefix:
```js
module.exports = {
plugins: ['testing-library'],
};
```
Then configure the rules you want to use within `rules` property of your `.eslintrc`:
```js
module.exports = {
rules: {
'testing-library/await-async-queries': 'error',
'testing-library/no-await-sync-queries': 'error',
'testing-library/no-debugging-utils': 'warn',
'testing-library/no-dom-import': 'off',
},
};
```
### Run the plugin only against test files
With the default setup mentioned before, `eslint-plugin-testing-library` will be run against your whole codebase. If you want to run this plugin only against your tests files, you have the following options:
#### ESLint `overrides`
One way of restricting ESLint config by file patterns is by using [ESLint `overrides`](https://eslint.org/docs/user-guide/configuring/configuration-files#configuration-based-on-glob-patterns).
Assuming you are using the same pattern for your test files as [Jest by default](https://jestjs.io/docs/configuration#testmatch-arraystring), the following config would run `eslint-plugin-testing-library` only against your test files:
```js
// .eslintrc.js
module.exports = {
// 1) Here we have our usual config which applies to the whole project, so we don't put testing-library preset here.
extends: ['airbnb', 'plugin:prettier/recommended'],
// 2) We load other plugins than eslint-plugin-testing-library globally if we want to.
plugins: ['react-hooks'],
overrides: [
{
// 3) Now we enable eslint-plugin-testing-library rules or preset only for matching testing files!
files: ['**/__tests__/**/*.[jt]s?(x)', '**/?(*.)+(spec|test).[jt]s?(x)'],
extends: ['plugin:testing-library/react'],
},
],
};
```
#### ESLint Cascading and Hierarchy
Another approach for customizing ESLint config by paths is through [ESLint Cascading and Hierarchy](https://eslint.org/docs/user-guide/configuring/configuration-files#cascading-and-hierarchy). This is useful if all your tests are placed under the same folder, so you can place there another `.eslintrc` where you enable `eslint-plugin-testing-library` for applying it only to the files under such folder, rather than enabling it on your global `.eslintrc` which would apply to your whole project.
## Shareable configurations
This plugin exports several recommended configurations that enforce good practices for specific Testing Library packages.
You can find more info about enabled rules in the [Supported Rules section](#supported-rules), under the `Configurations` column.
Since each one of these configurations is aimed at a particular Testing Library package, they are not extendable between them, so you should use only one of them at once per `.eslintrc` file. For example, if you want to enable recommended configuration for React, you don't need to combine it somehow with DOM one:
```js
// โ Don't do this
module.exports = {
extends: ['plugin:testing-library/dom', 'plugin:testing-library/react'],
};
```
```js
// โ
Just do this instead
module.exports = {
extends: ['plugin:testing-library/react'],
};
```
### DOM Testing Library
Enforces recommended rules for DOM Testing Library.
To enable this configuration use the `extends` property in your
`.eslintrc.js` config file:
```js
module.exports = {
extends: ['plugin:testing-library/dom'],
};
```
### Angular
Enforces recommended rules for Angular Testing Library.
To enable this configuration use the `extends` property in your
`.eslintrc.js` config file:
```js
module.exports = {
extends: ['plugin:testing-library/angular'],
};
```
### React
Enforces recommended rules for React Testing Library.
To enable this configuration use the `extends` property in your
`.eslintrc.js` config file:
```js
module.exports = {
extends: ['plugin:testing-library/react'],
};
```
### Vue
Enforces recommended rules for Vue Testing Library.
To enable this configuration use the `extends` property in your
`.eslintrc.js` config file:
```js
module.exports = {
extends: ['plugin:testing-library/vue'],
};
```
### Marko
Enforces recommended rules for Marko Testing Library.
To enable this configuration use the `extends` property in your
`.eslintrc.js` config file:
```js
module.exports = {
extends: ['plugin:testing-library/marko'],
};
```
## Supported Rules
> Remember that all rules from this plugin are prefixed by `"testing-library/"`
๐ผ Configurations enabled in.\
โ ๏ธ Configurations set to warn in.\
๐ง Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).
| Nameย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย ย | Description | ๐ผ | โ ๏ธ | ๐ง |
| :------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------- | :------------------------------------------------------------------ | :-- |
| [await-async-events](docs/rules/await-async-events.md) | Enforce promises from async event methods are handled | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | ๐ง |
| [await-async-queries](docs/rules/await-async-queries.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][] | | |
| [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 | ![badge-angular][] ![badge-dom][] ![badge-react][] | | |
| [no-await-sync-queries](docs/rules/no-await-sync-queries.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 | ![badge-angular][] ![badge-dom][] ![badge-marko][] ![badge-react][] ![badge-vue][] | | ๐ง |
| [no-manual-cleanup](docs/rules/no-manual-cleanup.md) | Disallow the use of `cleanup` | ![badge-react][] ![badge-vue][] | | |
| [no-node-access](docs/rules/no-node-access.md) | Disallow direct Node access | ![badge-angular][] ![badge-dom][] ![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-lifecycle](docs/rules/no-render-in-lifecycle.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-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-implicit-assert](docs/rules/prefer-implicit-assert.md) | Suggest using implicit assertions for getBy* & findBy* queries | | | |
| [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-query-matchers](docs/rules/prefer-query-matchers.md) | Ensure the configured `get*`/`query*` query is used with the corresponding matchers | | | |
| [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 | | | |
| [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
In v4 this plugin introduced a new feature called "Aggressive Reporting", which intends to detect Testing Library utils usages even if they don't come directly from a Testing Library package (i.e. [using a custom utility file to re-export everything from Testing Library](https://testing-library.com/docs/react-testing-library/setup/#custom-render)). You can [read more about this feature here](docs/migration-guides/v4.md#aggressive-reporting).
If you are looking to restricting or switching off this feature, please refer to the [Shared Settings section](#shared-settings) to do so.
## Shared Settings
There are some configuration options available that will be shared across all the plugin rules. This is achieved using [ESLint Shared Settings](https://eslint.org/docs/user-guide/configuring/configuration-files#adding-shared-settings). These Shared Settings are meant to be used if you need to restrict or switch off the Aggressive Reporting, which is an out of the box advanced feature to lint Testing Library usages in a simpler way for most of the users. **So please before configuring any of these settings**, read more about [the advantages of `eslint-plugin-testing-library` Aggressive Reporting feature](docs/migration-guides/v4.md#aggressive-reporting), and [how it's affected by these settings](docs/migration-guides/v4.md#shared-settings).
If you are sure about configuring the settings, these are the options available:
### `testing-library/utils-module`
The name of your custom utility file from where you re-export everything from the Testing Library package, or `"off"` to switch related Aggressive Reporting mechanism off. Relates to [Aggressive Imports Reporting](docs/migration-guides/v4.md#imports).
```js
// .eslintrc.js
module.exports = {
settings: {
'testing-library/utils-module': 'my-custom-test-utility-file',
},
};
```
[You can find more details about the `utils-module` setting here](docs/migration-guides/v4.md#testing-libraryutils-module).
### `testing-library/custom-renders`
A list of function names that are valid as Testing Library custom renders, or `"off"` to switch related Aggressive Reporting mechanism off. Relates to [Aggressive Renders Reporting](docs/migration-guides/v4.md#renders).
```js
// .eslintrc.js
module.exports = {
settings: {
'testing-library/custom-renders': ['display', 'renderWithProviders'],
},
};
```
[You can find more details about the `custom-renders` setting here](docs/migration-guides/v4.md#testing-librarycustom-renders).
### `testing-library/custom-queries`
A list of query names/patterns that are valid as Testing Library custom queries, or `"off"` to switch related Aggressive Reporting mechanism off. Relates to [Aggressive Reporting - Queries](docs/migration-guides/v4.md#queries)
```js
// .eslintrc.js
module.exports = {
settings: {
'testing-library/custom-queries': ['ByIcon', 'getByComplexText'],
},
};
```
[You can find more details about the `custom-queries` setting here](docs/migration-guides/v4.md#testing-librarycustom-queries).
### Switching all Aggressive Reporting mechanisms off
Since each Shared Setting is related to one Aggressive Reporting mechanism, and they accept `"off"` to opt out of that mechanism, you can switch the entire feature off by doing:
```js
// .eslintrc.js
module.exports = {
settings: {
'testing-library/utils-module': 'off',
'testing-library/custom-renders': 'off',
'testing-library/custom-queries': 'off',
},
};
```
## Troubleshooting
### Errors reported in non-testing files
If you find ESLint errors related to `eslint-plugin-testing-library` in files other than testing, this could be caused by [Aggressive Reporting](#aggressive-reporting).
You can avoid this by:
1. [running `eslint-plugin-testing-library` only against testing files](#run-the-plugin-only-against-test-files)
2. [limiting the scope of Aggressive Reporting through Shared Settings](#shared-settings)
3. [switching Aggressive Reporting feature off](#switching-all-aggressive-reporting-mechanisms-off)
If you think the error you are getting is not related to this at all, please [fill a new issue](https://github.com/testing-library/eslint-plugin-testing-library/issues/new/choose) with as many details as possible.
### False positives in testing files
If you are getting false positive ESLint errors in your testing files, this could be caused by [Aggressive Reporting](#aggressive-reporting).
You can avoid this by:
1. [limiting the scope of Aggressive Reporting through Shared Settings](#shared-settings)
2. [switching Aggressive Reporting feature off](#switching-all-aggressive-reporting-mechanisms-off)
If you think the error you are getting is not related to this at all, please [fill a new issue](https://github.com/testing-library/eslint-plugin-testing-library/issues/new/choose) with as many details as possible.
## Other documentation
- [Semantic Versioning Policy](/docs/semantic-versioning-policy.md)
## Contributors โจ
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
Mario Beltrรกn Alarcรณn
๐ป ๐ ๐ โ ๏ธ ๐ ๐ ๐ง
Thomas Lombart
๐ป ๐ ๐ โ ๏ธ ๐
Ben Monro
๐ป ๐ โ ๏ธ
Nicola Molinari
๐ป โ ๏ธ ๐ ๐
Aarรณn Garcรญa Hervรกs
๐
Matej ล nuderl
๐ค ๐
Adriร Fontcuberta
๐ป โ ๏ธ
Jon Aldinger
๐
Thomas Knickman
๐ป ๐ โ ๏ธ
Kevin Sullivan
๐
Jakub Jastrzฤbski
๐ป ๐ โ ๏ธ
Nikolay Stoynov
๐
marudor
๐ป โ ๏ธ
Tim Deschryver
๐ป ๐ ๐ค ๐ โ ๏ธ ๐ ๐ ๐ฆ
Tobias Deekens
๐
Victor Cordova
๐ป โ ๏ธ ๐
Dmitry Lobanov
๐ป โ ๏ธ
Kent C. Dodds
๐
Gonzalo D'Elia
๐ป โ ๏ธ ๐ ๐
Jeff Rifwald
๐
Leandro Lourenci
๐ ๐ป โ ๏ธ
Miguel Erja Gonzรกlez
๐
Pavel Pustovalov
๐
Jacob Parish
๐ ๐ป โ ๏ธ
Nick McCurdy
๐ค ๐ป ๐
Stefan Cameron
๐
Mateus Felix
๐ป โ ๏ธ ๐
Renato Augusto Gama dos Santos
๐ค ๐ป ๐ โ ๏ธ
Josh Kelly
๐ป
Alessia Bellisario
๐ป โ ๏ธ ๐
Spencer Miskoviak
๐ป โ ๏ธ ๐ ๐ค
Giorgio Polvara
๐ป โ ๏ธ ๐
Josh David
๐
Michaรซl De Boey
๐ป ๐ฆ ๐ง ๐ ๐
Jian Huang
๐ป โ ๏ธ ๐
Philipp Fritsche
๐ป
Tomas Zaicevas
๐ ๐ป โ ๏ธ ๐
Gareth Jones
๐ป ๐ โ ๏ธ
HonkingGoose
๐ ๐ง
Julien Wajsberg
๐ ๐ป โ ๏ธ
Marat Dyatko
๐ ๐ป
David Tolman
๐
Ari Perkkiรถ
โ ๏ธ
Diego Castillo
๐ป
Bruno Pinto
๐ป โ ๏ธ
themagickoala
๐ป โ ๏ธ
Prashant Ashok
๐ป โ ๏ธ
Ivan Aprea
๐ป โ ๏ธ
Dmitry Semigradsky
๐ป โ ๏ธ ๐
Senja
๐ป โ ๏ธ ๐
Breno Cota
๐ป โ ๏ธ
Nick Bolles
๐ป โ ๏ธ ๐
Bryan Mishkin
๐ ๐ง
Nim G
๐
Patrick Ahmetovic
๐ค ๐ป โ ๏ธ
Josh Justice
๐ป โ ๏ธ ๐ ๐ค
Dale Karp
๐ป โ ๏ธ ๐
Nathan
๐ป โ ๏ธ
justintoman
๐ป โ ๏ธ
Anthony Devick
๐ป โ ๏ธ ๐
Richard Maisano
๐ป โ ๏ธ
Aleksei Androsov
๐ป โ ๏ธ
Nicolas Bonduel
๐
Alexey Ryabov
๐ง
Jemi Salo
๐ป โ ๏ธ
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
[version-badge]: https://img.shields.io/npm/v/eslint-plugin-testing-library
[version-url]: https://www.npmjs.com/package/eslint-plugin-testing-library
[license-badge]: https://img.shields.io/npm/l/eslint-plugin-testing-library
[license-url]: https://github.com/testing-library/eslint-plugin-testing-library/blob/main/LICENSE
[eslint-remote-tester-badge]: https://img.shields.io/github/actions/workflow/status/AriPerkkio/eslint-remote-tester/lint-eslint-plugin-testing-library.yml
[eslint-remote-tester-workflow]: https://github.com/AriPerkkio/eslint-remote-tester/actions/workflows/lint-eslint-plugin-testing-library.yml
[package-health-badge]: https://snyk.io/advisor/npm-package/eslint-plugin-testing-library/badge.svg
[package-health-url]: https://snyk.io/advisor/npm-package/eslint-plugin-testing-library
[pr-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square
[all-contributors-badge]: https://img.shields.io/github/all-contributors/testing-library/eslint-plugin-testing-library?color=orange&style=flat-square
[pr-url]: http://makeapullrequest.com
[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