Skip to content

Commit a09b361

Browse files
bmishbmish
authored
docs: automate docs with eslint-doc-generator (testing-library#690)
1 parent dbb5889 commit a09b361

31 files changed

+169
-172
lines changed

‎README.md

+41-42
Large diffs are not rendered by default.

‎docs/rules/await-async-query.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Enforce promises from async queries to be handled (`testing-library/await-async-query`)
22

3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
6+
37
Ensure that promises returned by async queries are handled properly.
48

59
## Rule Details

‎docs/rules/await-async-utils.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Enforce promises from async utils to be handled (`testing-library/await-async-utils`)
1+
# Enforce promises from async utils to be awaited properly (`testing-library/await-async-utils`)
2+
3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
26

37
Ensure that promises returned by async utils are handled properly.
48

‎docs/rules/await-fire-event.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Enforce promises from fire event methods to be handled (`testing-library/await-fire-event`)
1+
# Enforce promises from `fireEvent` methods to be handled (`testing-library/await-fire-event`)
2+
3+
💼 This rule is enabled in the following configs: `marko`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
26

37
Ensure that promises returned by `fireEvent` methods are handled
48
properly.

‎docs/rules/consistent-data-testid.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Enforces consistent naming for the data-testid attribute (`testing-library/consistent-data-testid`)
1+
# Ensures consistent usage of `data-testid` (`testing-library/consistent-data-testid`)
2+
3+
<!-- end auto-generated rule header -->
24

35
Ensure `data-testid` values match a provided regex. This rule is un-opinionated, and requires configuration.
46

‎docs/rules/no-await-sync-events.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Disallow unnecessary `await` for sync events (`testing-library/no-await-sync-events`)
22

3+
<!-- end auto-generated rule header -->
4+
35
Ensure that sync simulated events are not awaited unnecessarily.
46

57
## Rule Details

‎docs/rules/no-await-sync-query.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Disallow unnecessary `await` for sync queries (`testing-library/no-await-sync-query`)
22

3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
6+
37
Ensure that sync queries are not awaited unnecessarily.
48

59
## Rule Details

‎docs/rules/no-container.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Disallow the use of `container` methods (`testing-library/no-container`)
22

3+
💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
6+
37
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.
48

59
This applies to Testing Library frameworks built on top of **DOM Testing Library**

‎docs/rules/no-debugging-utils.md

+7-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Disallow the use of debugging utilities (`testing-library/no-debugging-utils`)
1+
# Disallow the use of debugging utilities like `debug` (`testing-library/no-debugging-utils`)
2+
3+
💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
26

37
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.
48

@@ -37,6 +41,8 @@ const { screen } = require('@testing-library/react');
3741
screen.debug();
3842
```
3943

44+
## Options
45+
4046
You can control which debugging utils are checked for with the `utilsToCheckFor` option:
4147

4248
```json

‎docs/rules/no-dom-import.md

+6
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Disallow importing from DOM Testing Library (`testing-library/no-dom-import`)
22

3+
💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
4+
5+
🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
6+
7+
<!-- end auto-generated rule header -->
8+
39
Ensure that there are no direct imports from `@testing-library/dom` or
410
`dom-testing-library` when using some testing library framework
511
wrapper.

‎docs/rules/no-global-regexp-flag-in-query.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Disallow the use of the global RegExp flag (/g) in queries (`testing-library/no-global-regexp-flag-in-query`)
22

3+
🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
4+
5+
<!-- end auto-generated rule header -->
6+
37
Ensure that there are no global RegExp flags used when using queries.
48

59
## Rule Details

‎docs/rules/no-manual-cleanup.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# Disallow the use of `cleanup` (`testing-library/no-manual-cleanup`)
22

3+
<!-- end auto-generated rule header -->
4+
35
`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.
46

57
## Rule Details

‎docs/rules/no-node-access.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Disallow direct Node access (`testing-library/no-node-access`)
22

3+
💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
6+
37
The Testing Library already provides methods for querying DOM elements.
48

59
## Rule Details

‎docs/rules/no-promise-in-fire-event.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Disallow the use of promises passed to a `fireEvent` method (`testing-library/no-promise-in-fire-event`)
22

3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
6+
37
Methods from `fireEvent` expect to receive a DOM element. Passing a promise will end up in an error, so it must be prevented.
48

59
Examples of **incorrect** code for this rule:

‎docs/rules/no-render-in-setup.md

+7-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Disallow the use of `render` in setup functions (`testing-library/no-render-in-setup`)
1+
# Disallow the use of `render` in testing frameworks setup functions (`testing-library/no-render-in-setup`)
2+
3+
💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
26

37
## Rule Details
48

@@ -74,6 +78,8 @@ it('Should have foo and bar', () => {
7478
});
7579
```
7680

81+
## Options
82+
7783
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"`.
7884

7985
```

‎docs/rules/no-unnecessary-act.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Disallow wrapping Testing Library utils or empty callbacks in `act` (`testing-library/no-unnecessary-act`)
22

3+
💼 This rule is enabled in the following configs: `marko`, `react`.
4+
5+
<!-- end auto-generated rule header -->
6+
37
> ⚠️ The `act` method is only available on the following Testing Library packages:
48
>
59
> - `@testing-library/react` (supported by this plugin)

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

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Empty callbacks inside `waitFor` and `waitForElementToBeRemoved` are not preferred (`testing-library/no-wait-for-empty-callback`)
1+
# Disallow empty callbacks for `waitFor` and `waitForElementToBeRemoved` (`testing-library/no-wait-for-empty-callback`)
2+
3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
26

37
## Rule Details
48

‎docs/rules/no-wait-for-multiple-assertions.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Disallow the use of multiple expect inside `waitFor` (`testing-library/no-wait-for-multiple-assertions`)
1+
# Disallow the use of multiple `expect` calls inside `waitFor` (`testing-library/no-wait-for-multiple-assertions`)
2+
3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
26

37
## Rule Details
48

‎docs/rules/no-wait-for-side-effects.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Disallow the use of side effects inside `waitFor` (`testing-library/no-wait-for-side-effects`)
1+
# Disallow the use of side effects in `waitFor` (`testing-library/no-wait-for-side-effects`)
2+
3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
26

37
## Rule Details
48

‎docs/rules/no-wait-for-snapshot.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Ensures no snapshot is generated inside a `waitFor` call (`testing-library/no-wait-for-snapshot`)
1+
# Ensures no snapshot is generated inside of a `waitFor` call (`testing-library/no-wait-for-snapshot`)
2+
3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
26

37
Ensure that no calls to `toMatchSnapshot` or `toMatchInlineSnapshot` are made from within a `waitFor` method (or any of the other async utility methods).
48

‎docs/rules/prefer-explicit-assert.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Suggest using explicit assertions rather than just `getBy*` queries (`testing-library/prefer-explicit-assert`)
1+
# Suggest using explicit assertions rather than standalone queries (`testing-library/prefer-explicit-assert`)
2+
3+
<!-- end auto-generated rule header -->
24

35
Testing Library `getBy*` queries throw an error if the element is not
46
found. Some users like this behavior to use the query itself as an

‎docs/rules/prefer-find-by.md

+7-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
1-
# Suggest using `findBy*` methods instead of the `waitFor` + `getBy` queries (`testing-library/prefer-find-by`)
1+
# Suggest using `find(All)By*` query instead of `waitFor` + `get(All)By*` to wait for elements (`testing-library/prefer-find-by`)
2+
3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
6+
7+
<!-- end auto-generated rule header -->
28

39
`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)`)
410

‎docs/rules/prefer-presence-queries.md

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Enforce specific queries when checking element is present or not (`testing-library/prefer-presence-queries`)
1+
# Ensure appropriate `get*`/`query*` queries are used with their respective matchers (`testing-library/prefer-presence-queries`)
2+
3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
26

37
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:
48

‎docs/rules/prefer-query-by-disappearance.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Suggest using `queryBy*` queries when waiting for disappearance (`testing-library/prefer-query-by-disappearance`)
22

3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
6+
37
## Rule Details
48

59
This rule enforces using `queryBy*` queries when waiting for disappearance with `waitForElementToBeRemoved`.

‎docs/rules/prefer-screen-queries.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Suggest using `screen` while querying (`testing-library/prefer-screen-queries`)
22

3+
💼 This rule is enabled in the following configs: `angular`, `dom`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
6+
37
## Rule Details
48

59
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.

‎docs/rules/prefer-user-event.md

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
1-
# Suggest using `userEvent` library instead of `fireEvent` for simulating user interaction (`testing-library/prefer-user-event`)
1+
# Suggest using `userEvent` over `fireEvent` for simulating user interactions (`testing-library/prefer-user-event`)
2+
3+
<!-- end auto-generated rule header -->
24

35
From
46
[testing-library/dom-testing-library#107](https://github.com/testing-library/dom-testing-library/issues/107):

‎docs/rules/prefer-wait-for.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Use `waitFor` instead of deprecated wait methods (`testing-library/prefer-wait-for`)
22

3+
🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
4+
5+
<!-- end auto-generated rule header -->
6+
37
`dom-testing-library` v7 released a new async util called `waitFor` which satisfies the use cases of `wait`, `waitForElement`, and `waitForDomChange` making them deprecated.
48

59
## Rule Details

‎docs/rules/render-result-naming-convention.md

+4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Enforce a valid naming for return value from `render` (`testing-library/render-result-naming-convention`)
22

3+
💼 This rule is enabled in the following configs: `angular`, `marko`, `react`, `vue`.
4+
5+
<!-- end auto-generated rule header -->
6+
37
> 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.
48
59
## Rule Details

‎package.json

+9-4
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,13 @@
3030
"postbuild": "cpy README.md ./dist && cpy package.json ./dist && cpy LICENSE ./dist",
3131
"format": "prettier --write .",
3232
"format:check": "prettier --check .",
33-
"generate:configs": "ts-node tools/generate-configs",
34-
"generate:rules-list": "ts-node tools/generate-rules-list",
35-
"lint": "eslint . --max-warnings 0 --ext .js,.ts",
36-
"lint:fix": "npm run lint -- --fix",
33+
"generate": "npm-run-all \"generate:*\"",
34+
"generate:configs": "ts-node tools/generate-configs && npm run format",
35+
"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",
36+
"lint": "npm-run-all \"lint:*\"",
37+
"lint:generate": "npm run generate && git diff --exit-code",
38+
"lint:js": "eslint . --max-warnings 0 --ext .js,.ts",
39+
"lint:js:fix": "npm run lint:js -- --fix",
3740
"prepare": "is-ci || husky install",
3841
"semantic-release": "semantic-release",
3942
"test": "jest",
@@ -59,6 +62,7 @@
5962
"eslint": "^8.28.0",
6063
"eslint-config-kentcdodds": "^20.4.0",
6164
"eslint-config-prettier": "^8.5.0",
65+
"eslint-doc-generator": "^0.24.0",
6266
"eslint-plugin-import": "^2.26.0",
6367
"eslint-plugin-jest": "^27.1.5",
6468
"eslint-plugin-jest-formatting": "^3.1.0",
@@ -71,6 +75,7 @@
7175
"is-ci": "^3.0.1",
7276
"jest": "^28.1.3",
7377
"lint-staged": "^13.0.3",
78+
"npm-run-all": "^4.1.5",
7479
"prettier": "2.7.1",
7580
"semantic-release": "^19.0.5",
7681
"ts-jest": "^28.0.8",

‎tools/generate-rules-list/index.ts

-26
This file was deleted.

0 commit comments

Comments
 (0)