Skip to content

Commit b9faa0f

Browse files
bmishbmish
authored
docs: use eslint-doc-generator for rule documentation (jest-community#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

Diff for: ‎.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',

Diff for: ‎README.md

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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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.

Diff for: ‎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.

Diff for: ‎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

Diff for: ‎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.

Diff for: ‎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

Diff for: ‎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.

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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

Diff for: ‎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)