Skip to content

Commit b9faa0f

Browse files
bmishbmish
authored
docs: use eslint-doc-generator for rule documentation (#1263)
1 parent ae6cfb7 commit b9faa0f

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

63 files changed

+282
-786
lines changed

‎.eslintrc.js

+4
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@ module.exports = {
3232
'@typescript-eslint/ban-types': 'error',
3333
'@typescript-eslint/no-unused-vars': 'error',
3434
'eslint-comments/no-unused-disable': 'error',
35+
'eslint-plugin/require-meta-docs-description': [
36+
'error',
37+
{ pattern: '^(Enforce|Require|Disallow|Suggest|Prefer)' },
38+
],
3539
'eslint-plugin/test-case-property-ordering': 'error',
3640
'no-else-return': 'error',
3741
'no-negated-condition': 'error',

‎README.md

+81-80
Large diffs are not rendered by default.

‎docs/rules/consistent-test-it.md

+4-11
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,9 @@
1-
# Have control over `test` and `it` usages (`consistent-test-it`)
1+
# Enforce `test` and `it` usage conventions (`consistent-test-it`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
3+
🔧 This rule is automatically fixable by the
4+
[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
65

7-
🔧 This rule is automatically fixable using the `--fix`
8-
[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
9-
on the command line.
10-
11-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
127

138
Jest allows you to choose how you want to define your tests, using the `it` or
149
the `test` keywords, with multiple permutations for each:
@@ -81,8 +76,6 @@ describe('foo', function () {
8176
});
8277
```
8378

84-
### Default configuration
85-
8679
The default configuration forces all top-level tests to use `test` and all tests
8780
nested within `describe` to use `it`.
8881

‎docs/rules/expect-expect.md

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
# Enforce assertion to be made in a test body (`expect-expect`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
3+
⚠️ This rule _warns_ in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
87

98
Ensure that there is at least one `expect` call made in a test.
109

‎docs/rules/max-expects.md

+1-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# Enforces a maximum number assertion calls in a test body (`max-expects`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
6-
7-
<!-- end rule header -->
3+
<!-- end auto-generated rule header -->
84

95
As more assertions are made, there is a possible tendency for the test to be
106
more likely to mix multiple objectives. To avoid this, this rule reports when

‎docs/rules/max-nested-describe.md

+1-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# Enforces a maximum depth to nested describe calls (`max-nested-describe`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
6-
7-
<!-- end rule header -->
3+
<!-- end auto-generated rule header -->
84

95
While it's useful to be able to group your tests together within the same file
106
using `describe()`, having too many levels of nesting throughout your tests make

‎docs/rules/no-alias-methods.md

+8-10
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
# Disallow alias methods (`no-alias-methods`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼⚠️ This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
5+
This rule _warns_ in the 🎨 `style`
6+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
67

7-
🔧 This rule is automatically fixable using the `--fix`
8-
[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
9-
on the command line.
8+
🔧 This rule is automatically fixable by the
9+
[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
1010

11-
<!-- end rule header -->
11+
<!-- end auto-generated rule header -->
1212

1313
> These aliases are going to be removed in the next major version of Jest - see
14-
> https://github.com/facebook/jest/issues/13164 for more
14+
> <https://github.com/facebook/jest/issues/13164> for more
1515
1616
Several Jest methods have alias names, such as `toThrow` having the alias of
1717
`toThrowError`. This rule ensures that only the canonical name as used in the
@@ -24,8 +24,6 @@ method names used.
2424
This rule triggers a warning if the alias name, rather than the canonical name,
2525
of a method is used.
2626

27-
### Default configuration
28-
2927
The following patterns are considered warnings:
3028

3129
```js

‎docs/rules/no-commented-out-tests.md

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
# Disallow commented out tests (`no-commented-out-tests`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
3+
⚠️ This rule _warns_ in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
87

98
This rule raises a warning about commented out tests. It's similar to
109
no-disabled-tests rule.

‎docs/rules/no-conditional-expect.md

+4-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
1-
# Prevent calling `expect` conditionally (`no-conditional-expect`)
1+
# Disallow calling `expect` conditionally (`no-conditional-expect`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
87

98
This rule prevents the use of `expect` in conditional blocks, such as `if`s &
109
`catch`s.

‎docs/rules/no-conditional-in-test.md

+1-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# Disallow conditional logic in tests (`no-conditional-in-test`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
6-
7-
<!-- end rule header -->
3+
<!-- end auto-generated rule header -->
84

95
Conditional logic in tests is usually an indication that a test is attempting to
106
cover too much, and not testing the logic it intends to. Each branch of code

‎docs/rules/no-deprecated-functions.md

+5-7
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
# Disallow use of deprecated functions (`no-deprecated-functions`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
🔧 This rule is automatically fixable using the `--fix`
8-
[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
9-
on the command line.
6+
🔧 This rule is automatically fixable by the
7+
[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
108

11-
<!-- end rule header -->
9+
<!-- end auto-generated rule header -->
1210

1311
Over the years Jest has accrued some debt in the form of functions that have
1412
either been renamed for clarity, or replaced with more powerful APIs.

‎docs/rules/no-disabled-tests.md

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
# Disallow disabled tests (`no-disabled-tests`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
3+
⚠️ This rule _warns_ in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
87

98
Jest has a feature that allows you to temporarily mark tests as disabled. This
109
feature is often helpful while debugging or to create placeholders for future

‎docs/rules/no-done-callback.md

+6-8
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
1-
# Avoid using a callback in asynchronous tests and hooks (`no-done-callback`)
1+
# Disallow using a callback in asynchronous tests and hooks (`no-done-callback`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
💡 This rule provides
8-
[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
9-
that can be applied manually.
6+
💡 This rule is manually fixable by
7+
[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
108

11-
<!-- end rule header -->
9+
<!-- end auto-generated rule header -->
1210

1311
When calling asynchronous code in hooks and tests, `jest` needs to know when the
1412
asynchronous work is complete to progress the current run.

‎docs/rules/no-duplicate-hooks.md

+1-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
6-
7-
<!-- end rule header -->
3+
<!-- end auto-generated rule header -->
84

95
A `describe` block should not contain duplicate hooks.
106

‎docs/rules/no-export.md

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
# Disallow using `exports` in files containing tests (`no-export`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
87

98
Prevents using `exports` if a file has one or more tests in it.
109

‎docs/rules/no-focused-tests.md

+5-7
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
# Disallow focused tests (`no-focused-tests`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
💡 This rule provides
8-
[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
9-
that can be applied manually.
6+
💡 This rule is manually fixable by
7+
[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
108

11-
<!-- end rule header -->
9+
<!-- end auto-generated rule header -->
1210

1311
<!-- prettier-ignore -->
1412
Jest has a feature that allows you to focus tests by appending `.only` or

‎docs/rules/no-hooks.md

+1-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# Disallow setup and teardown hooks (`no-hooks`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
6-
7-
<!-- end rule header -->
3+
<!-- end auto-generated rule header -->
84

95
Jest provides global functions for setup and teardown tasks, which are called
106
before/after each test case and each test suite. The use of these hooks promotes

‎docs/rules/no-identical-title.md

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
# Disallow identical titles (`no-identical-title`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
87

98
Having identical titles for two different tests or test suites may create
109
confusion. For example, when a test with the same title as another test in the

‎docs/rules/no-if.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
# Disallow conditional logic (`no-if`)
22

33
❌ This rule is deprecated. It was replaced by
4-
[no-conditional-in-test](no-conditional-in-test.md).
4+
[`no-conditional-in-test`](no-conditional-in-test.md).
55

6-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
77

88
Conditional logic in tests is usually an indication that a test is attempting to
99
cover too much, and not testing the logic it intends to. Each branch of code

‎docs/rules/no-interpolation-in-snapshots.md

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
# Disallow string interpolation inside snapshots (`no-interpolation-in-snapshots`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
87

98
Prevents the use of string interpolations in snapshots.
109

‎docs/rules/no-jasmine-globals.md

+6-8
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,12 @@
11
# Disallow Jasmine globals (`no-jasmine-globals`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
🔧 This rule is automatically fixable using the `--fix`
8-
[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
9-
on the command line.
6+
🔧 This rule is automatically fixable by the
7+
[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
108

11-
<!-- end rule header -->
9+
<!-- end auto-generated rule header -->
1210

1311
`jest` uses `jasmine` as a test runner. A side effect of this is that both a
1412
`jasmine` object, and some jasmine-specific globals, are exposed to the test
@@ -22,7 +20,7 @@ API.
2220
This rule reports on any usage of Jasmine globals, which is not ported to Jest,
2321
and suggests alternatives from Jest's own API.
2422

25-
### Default configuration
23+
## Examples
2624

2725
The following patterns are considered warnings:
2826

‎docs/rules/no-large-snapshots.md

+2-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
1-
# disallow large snapshots (`no-large-snapshots`)
1+
# Disallow large snapshots (`no-large-snapshots`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
6-
7-
<!-- end rule header -->
3+
<!-- end auto-generated rule header -->
84

95
When using Jest's snapshot capability one should be mindful of the size of
106
created snapshots. As a general best practice snapshots should be limited in

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

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
# Disallow manually importing from `__mocks__` (`no-mocks-import`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
87

98
When using `jest.mock`, your tests (just like the code being tested) should
109
import from `./x`, not `./__mocks__/x`. Not following this rule can lead to

‎docs/rules/no-restricted-jest-methods.md

+1-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# Disallow specific `jest.` methods (`no-restricted-jest-methods`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
6-
7-
<!-- end rule header -->
3+
<!-- end auto-generated rule header -->
84

95
You may wish to restrict the use of specific `jest` methods.
106

‎docs/rules/no-restricted-matchers.md

+1-5
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,6 @@
11
# Disallow specific matchers & modifiers (`no-restricted-matchers`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`.
6-
7-
<!-- end rule header -->
3+
<!-- end auto-generated rule header -->
84

95
You may want to ban specific matchers & modifiers from being used.
106

‎docs/rules/no-standalone-expect.md

+3-4
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
# Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
22

3-
💼 This rule is enabled in the following
4-
[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
5-
`all`, `recommended`.
3+
💼 This rule is enabled in the ✅ `recommended`
4+
[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
65

7-
<!-- end rule header -->
6+
<!-- end auto-generated rule header -->
87

98
Prevents `expect` statements outside of a `test` or `it` block. An `expect`
109
within a helper function (but outside of a `test` or `it` block) will not

0 commit comments

Comments
 (0)