feat: plugin v3 (#97)

feat(await-async-utils): reflect waitFor changes (#89)
feat: new rule no-wait-for-empty-callback (#94)
feat: new rule prefer-wait-for (#88)
feat: new rule prefer-screen-queries (#99)
BREAKING CHANGE: drop support for node v8. Min version allowed is node v10.12 (#96)
BREAKING CHANGE: rule `no-get-by-for-checking-element-not-present` removed in favor of new rule `prefer-presence-queries` (#98)

Closes #85
Closes #86
Closes #90
Closes #92
Closes #95

Co-authored-by: timdeschryver <[email protected]>

Author: Belco90

.travis.yml

@@ -1,15 +1,17 @@
 language: node_js
 
-node_js:
-  - 8
-  - 10
+env:
+  - FORCE_COLOR=true
 
-branches:
-  only: master
+node_js:
+  - 10.12
+  - 12
+  - node
 
 jobs:
   include:
     - stage: release
+      if: branch = master AND type != pull_request
       node_js: lts/*
       deploy:
         provider: script

README.md

@@ -23,7 +23,9 @@
 [![Tweet][tweet-badge]][tweet-url]
 
 <!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+
 [![All Contributors](https://img.shields.io/badge/all_contributors-13-orange.svg?style=flat-square)](#contributors-)
+
 <!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 ## Installation
@@ -132,18 +134,21 @@ To enable this configuration use the `extends` property in your
 
 ## Supported Rules
 
-| Rule                                                                                                | Description                                                                 | Configurations                                                            | Fixable            |
-| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------ |
-| [await-async-query](docs/rules/await-async-query.md)                                                | Enforce async queries to have proper `await`                                | ![recommended-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] |                    |
-| [await-async-utils](docs/rules/await-async-utils.md)                                                | Enforce async utils to be awaited properly                                  | ![recommended-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.                         |                                                                           |                    |
-| [no-await-sync-query](docs/rules/no-await-sync-query.md)                                            | Disallow unnecessary `await` for sync queries                               | ![recommended-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] |                    |
-| [no-debug](docs/rules/no-debug.md)                                                                  | Disallow the use of `debug`                                                 | ![angular-badge][] ![react-badge][] ![vue-badge][]                        |                    |
-| [no-dom-import](docs/rules/no-dom-import.md)                                                        | Disallow importing from DOM Testing Library                                 | ![angular-badge][] ![react-badge][] ![vue-badge][]                        | ![fixable-badge][] |
-| [no-get-by-for-checking-element-not-present](docs/rules/no-get-by-for-checking-element-not-present.md) | Disallow the use of `getBy*` queries when checking elements are not present |                                                                           |                    |
-| [no-manual-cleanup](docs/rules/no-manual-cleanup.md)                                                | Disallow the use of `cleanup`                                               |                                                                           |                    |
-| [prefer-explicit-assert](docs/rules/prefer-explicit-assert.md)                                      | Suggest using explicit assertions rather than just `getBy*` queries         |                                                                           |                    |
+| Rule                                                                   | Description                                                            | Configurations                                                            | Fixable            |
+| ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------ |
+| [await-async-query](docs/rules/await-async-query.md)                   | Enforce async queries to have proper `await`                           | ![recommended-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] |                    |
+| [await-async-utils](docs/rules/await-async-utils.md)                   | Enforce async utils to be awaited properly                             | ![recommended-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.                    |                                                                           |                    |
+| [no-await-sync-query](docs/rules/no-await-sync-query.md)               | Disallow unnecessary `await` for sync queries                          | ![recommended-badge][] ![angular-badge][] ![react-badge][] ![vue-badge][] |                    |
+| [no-debug](docs/rules/no-debug.md)                                     | Disallow the use of `debug`                                            | ![angular-badge][] ![react-badge][] ![vue-badge][]                        |                    |
+| [no-dom-import](docs/rules/no-dom-import.md)                           | Disallow importing from DOM Testing Library                            | ![angular-badge][] ![react-badge][] ![vue-badge][]                        | ![fixable-badge][] |
+| [no-manual-cleanup](docs/rules/no-manual-cleanup.md)                   | Disallow the use of `cleanup`                                          |                                                                           |                    |
+| [no-wait-for-empty-callback](docs/rules/no-wait-for-empty-callback.md) | Disallow empty callbacks for `waitFor` and `waitForElementToBeRemoved` |                                                                           |                    |
+| [prefer-explicit-assert](docs/rules/prefer-explicit-assert.md)         | Suggest using explicit assertions rather than just `getBy*` queries    |                                                                           |                    |
+| [prefer-presence-queries](docs/rules/prefer-presence-queries.md)       | Enforce specific queries when checking element is present or not       |                                                                           |                    |
+| [prefer-screen-queries](docs/rules/prefer-screen-queries.md)           | Suggest using screen while using queries                               |                                                                           |                    |
+| [prefer-wait-for](docs/rules/prefer-wait-for.md)                       | Use `waitFor` instead of deprecated wait methods                       |                                                                           | ![fixable-badge][] |
 
 [build-badge]: https://img.shields.io/travis/testing-library/eslint-plugin-testing-library?style=flat-square
 [build-url]: https://travis-ci.org/testing-library/eslint-plugin-testing-library
@@ -194,6 +199,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
+
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!

docs/rules/await-async-utils.md

@@ -6,10 +6,11 @@ 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:
 
-- `wait`
-- `waitForElement`
-- `waitForDomChange`
+- `waitFor` _(introduced in dom-testing-library v7)_
 - `waitForElementToBeRemoved`
+- `wait` _(**deprecated** in dom-testing-library v7)_
+- `waitForElement` _(**deprecated** in dom-testing-library v7)_
+- `waitForDomChange` _(**deprecated** in dom-testing-library v7)_
 
 This rule aims to prevent users from forgetting to handle the returned promise from those async utils, which could lead to unexpected errors in the tests execution. The promises can be handled by using either `await` operator or `then` method.
 
@@ -18,22 +19,19 @@ Examples of **incorrect** code for this rule:
 ```js
 test('something incorrectly', async () => {
   // ...
-  wait(() => getByLabelText('email'));
+  waitFor(() => {});
 
-  const [usernameElement, passwordElement] = waitForElement(
+  const [usernameElement, passwordElement] = waitFor(
     () => [
       getByLabelText(container, 'username'),
       getByLabelText(container, 'password'),
     ],
     { container }
   );
 
-  waitForDomChange(() => {
-    return { container };
-  });
+  waitFor(() => {}, { timeout: 100 });
 
   waitForElementToBeRemoved(() => document.querySelector('div.getOuttaHere'));
-  // ...
 });
 ```
 
@@ -43,9 +41,9 @@ Examples of **correct** code for this rule:
 test('something correctly', async () => {
   // ...
   // `await` operator is correct
-  await wait(() => getByLabelText('email'));
+  await waitFor(() => getByLabelText('email'));
 
-  const [usernameElement, passwordElement] = await waitForElement(
+  const [usernameElement, passwordElement] = await waitFor(
     () => [
       getByLabelText(container, 'username'),
       getByLabelText(container, 'password'),
@@ -54,16 +52,13 @@ test('something correctly', async () => {
   );
 
   // `then` chained method is correct
-  waitForDomChange(() => {
-    return { container };
-  })
+  waitFor(() => {}, { timeout: 100 })
     .then(() => console.log('DOM changed!'))
     .catch(err => console.log(`Error you need to deal with: ${err}`));
 
   // return the promise within a function is correct too!
   const makeCustomWait = () =>
     waitForElementToBeRemoved(() => document.querySelector('div.getOuttaHere'));
-  // ...
 });
 ```
 

docs/rules/no-get-by-for-checking-element-not-present.md

@@ -0,0 +1,40 @@
+# Empty callbacks inside `waitFor` and `waitForElementToBeRemoved` are not preferred (no-wait-for-empty-callback)
+
+## Rule Details
+
+This rule aims to ensure the correct usage of `waitFor` and `waitForElementToBeRemoved`, in the way that they're intended to be used.
+If an empty callback is passed, these methods will just wait next tick of the event loop before proceeding, and that's not consistent with the philosophy of the library.
+**Instead, insert an assertion in that callback function.**
+
+Examples of **incorrect** code for this rule:
+
+```js
+const foo = async () => {
+  await waitFor(() => {});
+  await waitFor(function() {});
+  await waitFor(noop);
+
+  await waitForElementToBeRemoved(() => {});
+  await waitForElementToBeRemoved(function() {});
+  await waitForElementToBeRemoved(noop);
+};
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const foo = async () => {
+  await waitFor(() => {
+    screen.getByText(/submit/i);
+  });
+
+  const submit = screen.getByText(/submit/i);
+  await waitForElementToBeRemoved(() => submit);
+  // or
+  await waitForElementToBeRemoved(submit);
+};
+```
+
+## Further Reading
+
+- [dom-testing-library v7 release](https://github.com/testing-library/dom-testing-library/releases/tag/v7.0.0)

docs/rules/no-wait-for-empty-callback.md

@@ -0,0 +1,67 @@
+# Enforce specific queries when checking element is present or not (prefer-presence-queries)
+
+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:
+
+- using `getBy*` queries when asserting if element is present, so if the element is not found the error thrown will offer better info than asserting with other queries which will not throw an error.
+- using `queryBy*` queries when asserting if element is not present, so the test doesn't fail immediately when the element is not found and the assertion can be executed properly.
+
+## Rule details
+
+This rule fires whenever:
+
+- `queryBy*` or `queryAllBy*` are used to assert element **is** present with `.toBeInTheDocument()`, `toBeTruthy()` or `.toBeDefined()` matchers or negated matchers from case below.
+- `getBy*` or `getAllBy*` are used to assert element **is not** present with `.toBeNull()` or `.toBeFalsy()` matchers or negated matchers from case above.
+
+Examples of **incorrect** code for this rule:
+
+```js
+test('some test', () => {
+  render(<App />);
+
+  // check element is present with `queryBy*`
+  expect(screen.queryByText('button')).toBeInTheDocument();
+  expect(screen.queryAllByText('button')[0]).toBeTruthy();
+  expect(screen.queryByText('button')).toBeNull();
+  expect(screen.queryAllByText('button')[2]).not.toBeNull();
+  expect(screen.queryByText('button')).not.toBeFalsy();
+
+  // check element is NOT present with `getBy*`
+  expect(screen.getByText('loading')).not.toBeInTheDocument();
+  expect(screen.getAllByText('loading')[1]).not.toBeTruthy();
+  expect(screen.getByText('loading')).not.toBeNull();
+  expect(screen.getAllByText('loading')[3]).toBeNull();
+  expect(screen.getByText('loading')).toBeFalsy();
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+test('some test', async () => {
+  render(<App />);
+  // check element is present with `getBy*`
+  expect(screen.getByText('button')).toBeInTheDocument();
+  expect(screen.getAllByText('button')[9]).toBeTruthy();
+  expect(screen.getByText('button')).toBeNull();
+  expect(screen.getAllByText('button')[7]).not.toBeNull();
+  expect(screen.getByText('button')).not.toBeFalsy();
+
+  // check element is NOT present with `queryBy*`
+  expect(screen.queryByText('loading')).not.toBeInTheDocument();
+  expect(screen.queryAllByText('loading')[8]).not.toBeTruthy();
+  expect(screen.queryByText('loading')).not.toBeNull();
+  expect(screen.queryAllByText('loading')[6]).toBeNull();
+  expect(screen.queryByText('loading')).toBeFalsy();
+
+  // `findBy*` queries are out of the scope for this rule
+  const button = await screen.findByText('submit');
+  expect(button).toBeInTheDocument();
+});
+```
+
+## Further Reading
+
+- [Testing Library queries cheatsheet](https://testing-library.com/docs/dom-testing-library/cheatsheet#queries)
+- [Asserting elements are not present](https://testing-library.com/docs/guide-disappearance#asserting-elements-are-not-present)
+- [jest-dom note about using `getBy` within assertions](https://testing-library.com/docs/ecosystem-jest-dom)
+- [Waiting for appearance](https://testing-library.com/docs/guide-disappearance#waiting-for-appearance)

docs/rules/prefer-presence-queries.md

@@ -0,0 +1,30 @@
+# Suggest using screen while using queries (prefer-screen-queries)
+
+## 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.
+This rule aims to force writing tests using queries directly from `screen` object rather than destructuring them from `render` result.
+
+Examples of **incorrect** code for this rule:
+
+```js
+// calling a query from the `render` method
+const { getByText } = render(<Component />);
+getByText('foo');
+
+const utils = render(<Component />);
+utils.getByText('foo');
+```
+
+Examples of **correct** code for this rule:
+
+```js
+import { screen } from '@testing-library/any-framework';
+
+render(<Component />);
+screen.getByText('foo');
+```
+
+## Further Reading
+
+- [`screen` documentation](https://testing-library.com/docs/dom-testing-library/api-queries#screen)