Skip to content

Commit f4b5958

Browse files
Belco90Belco90
authored
docs: add guide for migrating to v4 (#312)
* docs: first steps for migrating to v4 guide * docs: extract Aggressive Reporting Query info to its own section * docs: explain Aggressive Reporting motivation and mechanism * docs: describe each aggressive reporting mechanism * docs: shared settings * docs: update info related to Shareable Configs updated * docs: fix typo * docs: fix more typos * docs: replace tho by though * docs: fix wrong new lines entered * ci: remove duplicated max-warnings param
1 parent 66df731 commit f4b5958

File tree

2 files changed

+207
-1
lines changed

2 files changed

+207
-1
lines changed

‎.github/workflows/pipeline.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ jobs:
4545
run: npm run lint
4646

4747
- name: Check format
48-
run: npm run format:check -- --max-warnings 0
48+
run: npm run format:check
4949

5050
tests:
5151
name: Tests (Node v${{ matrix.node }} - ESLint v${{ matrix.eslint }})

‎docs/migrating-to-v4-guide.md

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
# Guide: migrating to v4
2+
3+
Previous versions of `eslint-plugin-testing-library` weren't checking common things consistently: Testing Library imports, renamed methods, wrappers around Testing Library methods, etc.
4+
One of the most important changes of `eslint-plugin-testing-library` v4 is the new detection mechanism implemented to be shared across all the rules, so each one of them has been rewritten to detect and report Testing Library usages consistently and correctly from a core module.
5+
6+
## Overview
7+
8+
- [Aggressive Reporting](#aggressive-reporting) opted-in to avoid silencing possible errors
9+
- 7 new rules
10+
- `no-container`
11+
- `no-node-access`
12+
- `no-promise-in-fire-event`
13+
- `no-wait-for-multiple-assertions`
14+
- `no-wait-for-side-effects`
15+
- `prefer-user-event`
16+
- `render-result-naming-convention`
17+
- Shareable Configs updated
18+
- `recommended` renamed to `dom`
19+
- list of rules enabled has changed
20+
- Some rules option removed in favor of new Shared Settings + Aggressive Reporting
21+
- More consistent and flexible core rules detection
22+
- Tons of errors and small issues fixed
23+
- Dependencies updates
24+
25+
## Breaking Changes
26+
27+
### Dependencies
28+
29+
- Min Node version required is `10.22.1`
30+
- Min ESLint version required is `7.5`
31+
32+
Make sure you have Node and ESLint installed satisfying these new required versions.
33+
34+
### New errors reported
35+
36+
Since v4 also fixes a lot of issues and detect invalid usages in a more consistent way, you might find new errors reported in your codebase. Just be aware of this when migrating to v4.
37+
38+
### `recommended` Shareable Config has been renamed
39+
40+
If you were using `recommended` Shareable Config, it has been renamed to `dom` so you'll need to update it in your ESLint config file:
41+
42+
```diff
43+
{
44+
...
45+
- "extends": ["plugin:testing-library/recommended"]
46+
+ "extends": ["plugin:testing-library/dom"]
47+
}
48+
```
49+
50+
This Shareable Config has been renamed to clarify there is no _recommended_ config by default, so it depends on which Testing Library package you are using: DOM, Angular, React, or Vue (for now).
51+
52+
### Shareable Configs updated
53+
54+
Shareable Configs have been updated with:
55+
56+
- `dom`
57+
- `no-promise-in-fire-event` enabled as "error"
58+
- `no-wait-for-empty-callback` enabled as "error"
59+
- `prefer-screen-queries` enabled as "error"
60+
- `angular`
61+
- `no-container` enabled as "error"
62+
- `no-debug` changed from "warning" to "error"
63+
- `no-node-access` enabled as "error"
64+
- `no-promise-in-fire-event` enabled as "error"
65+
- `no-wait-for-empty-callback` enabled as "error"
66+
- `prefer-screen-queries` enabled as "error"
67+
- `render-result-naming-convention` enabled as "error"
68+
- `react`
69+
- `no-container` enabled as "error"
70+
- `no-debug` changed from "warning" to "error"
71+
- `no-node-access` enabled as "error"
72+
- `no-promise-in-fire-event` enabled as "error"
73+
- `no-wait-for-empty-callback` enabled as "error"
74+
- `prefer-screen-queries` enabled as "error"
75+
- `render-result-naming-convention` enabled as "error"
76+
- `vue`
77+
- `no-container` enabled as "error"
78+
- `no-debug` changed from "warning" to "error"
79+
- `no-node-access` enabled as "error"
80+
- `no-promise-in-fire-event` enabled as "error"
81+
- `no-wait-for-empty-callback` enabled as "error"
82+
- `prefer-screen-queries` enabled as "error"
83+
- `render-result-naming-convention` enabled as "error"
84+
85+
### `customQueryNames` rules option has been removed
86+
87+
Until now, those rules reporting errors related to Testing Library queries needed an option called `customQueryNames` so you could specify which extra queries you'd like to report apart from built-in ones. This option has been removed in favor of reporting every method matching Testing Library queries pattern. The only thing you need to do is removing `customQueryNames` from your rules config if any. You can read more about it in corresponding [Aggressive Reporting - Queries](#queries) section.
88+
89+
### `renderFunctions` rules option has been removed
90+
91+
Until now, those rules reporting errors related to Testing Library `render` needed an option called `renderFunctions` so you could specify which extra functions from your codebase should be assumed as extra `render` methods apart from built-in one. This option has been removed in favor of reporting every method which contains `*render*` on its name. The only thing you need to do is removing `renderFunctions` from your rules config if any. You can read more about it in corresponding [Aggressive Reporting - Render](#renders) section, and available config in [Shared Settings](#shared-settings) section.
92+
93+
## Aggressive Reporting
94+
95+
So what is this Aggressive Reporting introduced on v4? Until v3, `eslint-plugin-testing-library` had assumed that all Testing Libraries utils would be imported from some `@testing-library/*` or `*-testing-library` package. However, this is not always true since:
96+
97+
- users can [add their own Custom Render](https://testing-library.com/docs/react-testing-library/setup/#custom-render) methods, so it can be named other than `render`.
98+
- users can [re-export Testing Library utils from a custom module](https://testing-library.com/docs/react-testing-library/setup/#configuring-jest-with-test-utils), so they won't be imported from a Testing Library package but a custom one.
99+
- users can [add their own Custom Queries](https://testing-library.com/docs/react-testing-library/setup/#add-custom-queries), so it's possible to use other queries than built-in ones.
100+
101+
These customization mechanisms make impossible for `eslint-plugin-testing-library` to figure out if some utils are related to Testing Library or not. Here you have some examples illustrating it:
102+
103+
```javascript
104+
import { render, screen } from '@testing-library/react';
105+
// ...
106+
107+
// ✅ this render has to be reported since it's named `render`
108+
// and it's imported from @testing-library/* package
109+
const wrapper = render(<Component />);
110+
111+
// ✅ this query has to be reported since it's named after a built-in query
112+
// and it's imported from @testing-library/* package
113+
const el = screen.findByRole('button');
114+
```
115+
116+
```javascript
117+
// importing from Custom Module
118+
import { renderWithRedux, findByIcon } from 'test-utils';
119+
// ...
120+
121+
// ❓ we don't know if this render has to be reported since it's NOT named `render`
122+
// and it's NOT imported from @testing-library/* package
123+
const wrapper = renderWithRedux(<Component />);
124+
125+
// ❓ we don't know if this query has to be reported since it's NOT named after a built-in query
126+
// and it's NOT imported from @testing-library/* package
127+
const el = findByIcon('profile');
128+
```
129+
130+
How can the `eslint-plugin-testing-library` be aware of this? Until v3, the plugin offered some options to indicate some of these custom things, so the plugin would check them when reporting usages. This can lead to false negatives though since the users might not be aware of the necessity of indicating such custom utils or just forget about doing so.
131+
132+
Instead, in `eslint-plugin-testing-library` v4 we have opted-in a more **aggressive reporting** mechanism which, by default, will assume any method named following the same patterns as Testing Library utils has to be reported too:
133+
134+
```javascript
135+
// importing from Custom Module
136+
import { renderWithRedux, findByIcon } from 'test-utils';
137+
// ...
138+
139+
// ✅ this render has to be reported since its name contains "*render*"
140+
// and it doesn't matter where it's imported from
141+
const wrapper = renderWithRedux(<Component />);
142+
143+
// ✅ this render has to be reported since its name starts by "findBy*"
144+
// and it doesn't matter where it's imported from
145+
const el = findByIcon('profile');
146+
```
147+
148+
There are 3 behaviors then that can be aggressively reported: imports, renders, and queries. This new Aggressive Reporting mechanism will just work fine out of the box and won't create false positives for most of the users. However, it's possible to do some tweaks to disable some of these behaviors using the new [Shared Settings](#shared-settings). We recommend you to keep reading this section to know more about these Aggressive Reporting behaviors and then check the Shared Settings if you think you'd still need it for some particular reason.
149+
150+
_You can find the motivation behind this behavior on [this issue comment](https://github.com/testing-library/eslint-plugin-testing-library/issues/222#issuecomment-679592434)._
151+
152+
### Imports
153+
154+
By default, `eslint-plugin-testing-library` v4 won't check from which module are the utils imported. This means it doesn't matter if you are importing the utils from `@testing-library/*`, `test-utils` or `whatever`.
155+
156+
There is a new Shared Setting to restrict this scope though: [`utils-module`](#utils-module). By using this setting, only utils imported from `@testing-library/*` packages, or the custom one indicated in this setting would be reported.
157+
158+
### Renders
159+
160+
By default, `eslint-plugin-testing-library` v4 will assume that all methods which names contain "render" should be reported. This means it doesn't matter if you are rendering your elements for testing using `render`, `customRender` or `renderWithRedux`.
161+
162+
There is a new Shared Setting to restrict this scope though: [`custom-renders`](#custom-renders). By using this setting, only methods strictly named `render` or as one of the indicated Custom Renders would be reported.
163+
164+
### Queries
165+
166+
`eslint-plugin-testing-library` v4 will assume that all methods named following the pattern `get(All)By*`, `query(All)By*`, or `find(All)By*` are queries to be reported. This means it doesn't matter if you are using a built-in query (`getByText`), or a custom one (`getByIcon`): if it matches this pattern, it will be assumed as a potential query to be reported.
167+
168+
There is no way to restrict this behavior for now.
169+
170+
## Shared Settings
171+
172+
ESLint has a setting feature which allows configuring data that must be shared across all its rules: [Shared Settings](https://eslint.org/docs/user-guide/configuring/configuration-files#adding-shared-settings). Since `eslint-plugin-testing-library` v4 we are using this Shared Settings to config global things for the plugin.
173+
174+
To avoid collision with settings from other ESLint plugins, all the properties for this one are prefixed with `testing-library/`.
175+
176+
⚠️ **Please be aware of using these settings will disable part of [Aggressive Reporting](#aggressive-reporting).**
177+
178+
### `utils-module`
179+
180+
Relates to [Aggressive Reporting - Imports](#imports). This setting (just a string) allows you to indicate which is the only Custom Module you'd like to be reported by `eslint-plugin-testing-library`.
181+
182+
```json
183+
// .eslintrc
184+
{
185+
"settings": {
186+
"testing-library/utils-module": "my-custom-test-utils"
187+
}
188+
}
189+
```
190+
191+
The previous setting example would force `eslint-plugin-testing-library` to only report Testing Library utils coming from `@testing-library/*` package or `my-custom-test-utils`, silencing potential errors for utils imported from somewhere else.
192+
193+
### `custom-renders`
194+
195+
Relates to [Aggressive Reporting - Renders](#renders). This setting (array of strings) allows you to indicate which are the only Custom Renders you'd like to be reported by `eslint-plugin-testing-library`.
196+
197+
```json
198+
// .eslintrc
199+
{
200+
"settings": {
201+
"testing-library/custom-renders": ["display", "renderWithProviders"]
202+
}
203+
}
204+
```
205+
206+
The previous setting example would force `eslint-plugin-testing-library` to only report Testing Library renders named `render` (built-in one is always included), `display` and `renderWithProviders`, silencing potential errors for others custom renders.

0 commit comments

Comments
 (0)