From 422bac929c9d8db3c036df5f365cc5aae4a7eef8 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Sun, 9 Oct 2022 16:09:08 -0400
Subject: [PATCH] docs: automate docs with eslint-doc-generator
---
.eslintrc.js | 4 +
README.md | 162 ++++++------
docs/rules/consistent-test-it.md | 15 +-
docs/rules/expect-expect.md | 7 +-
docs/rules/max-expects.md | 6 +-
docs/rules/max-nested-describe.md | 6 +-
docs/rules/no-alias-methods.md | 18 +-
docs/rules/no-commented-out-tests.md | 7 +-
docs/rules/no-conditional-expect.md | 9 +-
docs/rules/no-conditional-in-test.md | 6 +-
docs/rules/no-deprecated-functions.md | 12 +-
docs/rules/no-disabled-tests.md | 7 +-
docs/rules/no-done-callback.md | 14 +-
docs/rules/no-duplicate-hooks.md | 6 +-
docs/rules/no-export.md | 7 +-
docs/rules/no-focused-tests.md | 12 +-
docs/rules/no-hooks.md | 6 +-
docs/rules/no-identical-title.md | 7 +-
docs/rules/no-if.md | 4 +-
docs/rules/no-interpolation-in-snapshots.md | 7 +-
docs/rules/no-jasmine-globals.md | 14 +-
docs/rules/no-large-snapshots.md | 8 +-
docs/rules/no-mocks-import.md | 7 +-
docs/rules/no-restricted-jest-methods.md | 6 +-
docs/rules/no-restricted-matchers.md | 6 +-
docs/rules/no-standalone-expect.md | 7 +-
docs/rules/no-test-prefixes.md | 14 +-
docs/rules/no-test-return-statement.md | 6 +-
docs/rules/prefer-called-with.md | 6 +-
docs/rules/prefer-comparison-matcher.md | 11 +-
docs/rules/prefer-each.md | 6 +-
docs/rules/prefer-equality-matcher.md | 11 +-
docs/rules/prefer-expect-assertions.md | 13 +-
docs/rules/prefer-expect-resolves.md | 11 +-
docs/rules/prefer-hooks-in-order.md | 6 +-
docs/rules/prefer-hooks-on-top.md | 6 +-
docs/rules/prefer-lowercase-title.md | 11 +-
docs/rules/prefer-mock-promise-shorthand.md | 11 +-
docs/rules/prefer-snapshot-hint.md | 6 +-
docs/rules/prefer-spy-on.md | 13 +-
docs/rules/prefer-strict-equal.md | 13 +-
docs/rules/prefer-to-be.md | 12 +-
docs/rules/prefer-to-contain.md | 14 +-
docs/rules/prefer-to-have-length.md | 14 +-
docs/rules/prefer-todo.md | 13 +-
docs/rules/require-hook.md | 6 +-
docs/rules/require-to-throw-message.md | 8 +-
docs/rules/require-top-level-describe.md | 6 +-
docs/rules/unbound-method.md | 6 +-
docs/rules/valid-describe-callback.md | 7 +-
docs/rules/valid-expect-in-promise.md | 9 +-
docs/rules/valid-expect.md | 9 +-
docs/rules/valid-title.md | 12 +-
package.json | 3 +-
src/rules/consistent-test-it.ts | 2 +-
src/rules/no-conditional-expect.ts | 2 +-
src/rules/no-done-callback.ts | 2 +-
src/rules/no-large-snapshots.ts | 2 +-
src/rules/no-test-prefixes.ts | 2 +-
src/rules/valid-expect-in-promise.ts | 2 +-
tools/regenerate-docs.ts | 264 --------------------
tools/rule-notices.ts | 116 ---------
yarn.lock | 44 +++-
63 files changed, 283 insertions(+), 786 deletions(-)
delete mode 100644 tools/regenerate-docs.ts
delete mode 100644 tools/rule-notices.ts
diff --git a/.eslintrc.js b/.eslintrc.js
index 7e45a25a5..4611a2e63 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -32,6 +32,10 @@ module.exports = {
'@typescript-eslint/ban-types': 'error',
'@typescript-eslint/no-unused-vars': 'error',
'eslint-comments/no-unused-disable': 'error',
+ 'eslint-plugin/require-meta-docs-description': [
+ 'error',
+ { pattern: '^(Enforce|Require|Disallow|Suggest|Prefer)' },
+ ],
'eslint-plugin/test-case-property-ordering': 'error',
'no-else-return': 'error',
'no-negated-condition': 'error',
diff --git a/README.md b/README.md
index 6f1b6a3ad..da1a2edc5 100644
--- a/README.md
+++ b/README.md
@@ -195,70 +195,85 @@ installations requiring long-term consistency.
## Rules
-
-
-| Rule | Description | Configurations | Fixable |
-| ---------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------- | ------------ |
-| [consistent-test-it](docs/rules/consistent-test-it.md) | Have control over `test` and `it` usages | | ![fixable][] |
-| [expect-expect](docs/rules/expect-expect.md) | Enforce assertion to be made in a test body | ![recommended][] | |
-| [max-expects](docs/rules/max-expects.md) | Enforces a maximum number assertion calls in a test body | | |
-| [max-nested-describe](docs/rules/max-nested-describe.md) | Enforces a maximum depth to nested describe calls | | |
-| [no-alias-methods](docs/rules/no-alias-methods.md) | Disallow alias methods | ![recommended][] | ![fixable][] |
-| [no-commented-out-tests](docs/rules/no-commented-out-tests.md) | Disallow commented out tests | ![recommended][] | |
-| [no-conditional-expect](docs/rules/no-conditional-expect.md) | Prevent calling `expect` conditionally | ![recommended][] | |
-| [no-conditional-in-test](docs/rules/no-conditional-in-test.md) | Disallow conditional logic in tests | | |
-| [no-deprecated-functions](docs/rules/no-deprecated-functions.md) | Disallow use of deprecated functions | ![recommended][] | ![fixable][] |
-| [no-disabled-tests](docs/rules/no-disabled-tests.md) | Disallow disabled tests | ![recommended][] | |
-| [no-done-callback](docs/rules/no-done-callback.md) | Avoid using a callback in asynchronous tests and hooks | ![recommended][] | ![suggest][] |
-| [no-duplicate-hooks](docs/rules/no-duplicate-hooks.md) | Disallow duplicate setup and teardown hooks | | |
-| [no-export](docs/rules/no-export.md) | Disallow using `exports` in files containing tests | ![recommended][] | |
-| [no-focused-tests](docs/rules/no-focused-tests.md) | Disallow focused tests | ![recommended][] | ![suggest][] |
-| [no-hooks](docs/rules/no-hooks.md) | Disallow setup and teardown hooks | | |
-| [no-identical-title](docs/rules/no-identical-title.md) | Disallow identical titles | ![recommended][] | |
-| [no-if](docs/rules/no-if.md) | Disallow conditional logic | ![deprecated][] | |
-| [no-interpolation-in-snapshots](docs/rules/no-interpolation-in-snapshots.md) | Disallow string interpolation inside snapshots | ![recommended][] | |
-| [no-jasmine-globals](docs/rules/no-jasmine-globals.md) | Disallow Jasmine globals | ![recommended][] | ![fixable][] |
-| [no-large-snapshots](docs/rules/no-large-snapshots.md) | disallow large snapshots | | |
-| [no-mocks-import](docs/rules/no-mocks-import.md) | Disallow manually importing from `__mocks__` | ![recommended][] | |
-| [no-restricted-jest-methods](docs/rules/no-restricted-jest-methods.md) | Disallow specific `jest.` methods | | |
-| [no-restricted-matchers](docs/rules/no-restricted-matchers.md) | Disallow specific matchers & modifiers | | |
-| [no-standalone-expect](docs/rules/no-standalone-expect.md) | Disallow using `expect` outside of `it` or `test` blocks | ![recommended][] | |
-| [no-test-prefixes](docs/rules/no-test-prefixes.md) | Use `.only` and `.skip` over `f` and `x` | ![recommended][] | ![fixable][] |
-| [no-test-return-statement](docs/rules/no-test-return-statement.md) | Disallow explicitly returning from tests | | |
-| [prefer-called-with](docs/rules/prefer-called-with.md) | Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` | | |
-| [prefer-comparison-matcher](docs/rules/prefer-comparison-matcher.md) | Suggest using the built-in comparison matchers | | ![fixable][] |
-| [prefer-each](docs/rules/prefer-each.md) | Prefer using `.each` rather than manual loops | | |
-| [prefer-equality-matcher](docs/rules/prefer-equality-matcher.md) | Suggest using the built-in equality matchers | | ![suggest][] |
-| [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md) | Suggest using `expect.assertions()` OR `expect.hasAssertions()` | | ![suggest][] |
-| [prefer-expect-resolves](docs/rules/prefer-expect-resolves.md) | Prefer `await expect(...).resolves` over `expect(await ...)` syntax | | ![fixable][] |
-| [prefer-hooks-in-order](docs/rules/prefer-hooks-in-order.md) | Prefer having hooks in a consistent order | | |
-| [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md) | Suggest having hooks before any test cases | | |
-| [prefer-lowercase-title](docs/rules/prefer-lowercase-title.md) | Enforce lowercase test names | | ![fixable][] |
-| [prefer-mock-promise-shorthand](docs/rules/prefer-mock-promise-shorthand.md) | Prefer mock resolved/rejected shorthands for promises | | ![fixable][] |
-| [prefer-snapshot-hint](docs/rules/prefer-snapshot-hint.md) | Prefer including a hint with external snapshots | | |
-| [prefer-spy-on](docs/rules/prefer-spy-on.md) | Suggest using `jest.spyOn()` | | ![fixable][] |
-| [prefer-strict-equal](docs/rules/prefer-strict-equal.md) | Suggest using `toStrictEqual()` | | ![suggest][] |
-| [prefer-to-be](docs/rules/prefer-to-be.md) | Suggest using `toBe()` for primitive literals | ![style][] | ![fixable][] |
-| [prefer-to-contain](docs/rules/prefer-to-contain.md) | Suggest using `toContain()` | ![style][] | ![fixable][] |
-| [prefer-to-have-length](docs/rules/prefer-to-have-length.md) | Suggest using `toHaveLength()` | ![style][] | ![fixable][] |
-| [prefer-todo](docs/rules/prefer-todo.md) | Suggest using `test.todo` | | ![fixable][] |
-| [require-hook](docs/rules/require-hook.md) | Require setup and teardown code to be within a hook | | |
-| [require-to-throw-message](docs/rules/require-to-throw-message.md) | Require a message for `toThrow()` | | |
-| [require-top-level-describe](docs/rules/require-top-level-describe.md) | Require test cases and hooks to be inside a `describe` block | | |
-| [valid-describe-callback](docs/rules/valid-describe-callback.md) | Enforce valid `describe()` callback | ![recommended][] | |
-| [valid-expect](docs/rules/valid-expect.md) | Enforce valid `expect()` usage | ![recommended][] | |
-| [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md) | Ensure promises that have expectations in their chain are valid | ![recommended][] | |
-| [valid-title](docs/rules/valid-title.md) | Enforce valid titles | ![recommended][] | ![fixable][] |
-
-
-
-## TypeScript Rules
-
-In addition to the above rules, this plugin also includes a few advanced rules
-that are powered by type-checking information provided by TypeScript.
-
-In order to use these rules, you must be using `@typescript-eslint/parser` &
-adjust your eslint config as outlined
+
+
+πΌ
+[Configurations](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations)
+enabled in.\
+β
Enabled in the `recommended` [configuration](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).\
+β
β οΈ Warns in the `recommended`
+[configuration](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).\
+π¨ Enabled in the `style` [configuration](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).\
+π¨β οΈ Warns in the `style`
+[configuration](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).\
+π§ Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
+π‘ Manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).\
+β Deprecated.
+
+| NameΒ Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β | Description | πΌ | π§ | π‘ | β |
+| :--------------------------------------------------------------------------- | :------------------------------------------------------------------ | :--------------------------------------------------------- | :-- | :-- | :-- |
+| [consistent-test-it](docs/rules/consistent-test-it.md) | Enforce `test` and `it` usage conventions | | π§ | | |
+| [expect-expect](docs/rules/expect-expect.md) | Enforce assertion to be made in a test body | β
β οΈ | | | |
+| [max-expects](docs/rules/max-expects.md) | Enforces a maximum number assertion calls in a test body | | | | |
+| [max-nested-describe](docs/rules/max-nested-describe.md) | Enforces a maximum depth to nested describe calls | | | | |
+| [no-alias-methods](docs/rules/no-alias-methods.md) | Disallow alias methods | β
π¨β οΈ | π§ | | |
+| [no-commented-out-tests](docs/rules/no-commented-out-tests.md) | Disallow commented out tests | β
β οΈ | | | |
+| [no-conditional-expect](docs/rules/no-conditional-expect.md) | Disallow calling `expect` conditionally | β
| | | |
+| [no-conditional-in-test](docs/rules/no-conditional-in-test.md) | Disallow conditional logic in tests | | | | |
+| [no-deprecated-functions](docs/rules/no-deprecated-functions.md) | Disallow use of deprecated functions | β
| π§ | | |
+| [no-disabled-tests](docs/rules/no-disabled-tests.md) | Disallow disabled tests | β
β οΈ | | | |
+| [no-done-callback](docs/rules/no-done-callback.md) | Disallow using a callback in asynchronous tests and hooks | β
| | π‘ | |
+| [no-duplicate-hooks](docs/rules/no-duplicate-hooks.md) | Disallow duplicate setup and teardown hooks | | | | |
+| [no-export](docs/rules/no-export.md) | Disallow using `exports` in files containing tests | β
| | | |
+| [no-focused-tests](docs/rules/no-focused-tests.md) | Disallow focused tests | β
| | π‘ | |
+| [no-hooks](docs/rules/no-hooks.md) | Disallow setup and teardown hooks | | | | |
+| [no-identical-title](docs/rules/no-identical-title.md) | Disallow identical titles | β
| | | |
+| [no-if](docs/rules/no-if.md) | Disallow conditional logic | | | | β |
+| [no-interpolation-in-snapshots](docs/rules/no-interpolation-in-snapshots.md) | Disallow string interpolation inside snapshots | β
| | | |
+| [no-jasmine-globals](docs/rules/no-jasmine-globals.md) | Disallow Jasmine globals | β
| π§ | | |
+| [no-large-snapshots](docs/rules/no-large-snapshots.md) | Disallow large snapshots | | | | |
+| [no-mocks-import](docs/rules/no-mocks-import.md) | Disallow manually importing from `__mocks__` | β
| | | |
+| [no-restricted-jest-methods](docs/rules/no-restricted-jest-methods.md) | Disallow specific `jest.` methods | | | | |
+| [no-restricted-matchers](docs/rules/no-restricted-matchers.md) | Disallow specific matchers & modifiers | | | | |
+| [no-standalone-expect](docs/rules/no-standalone-expect.md) | Disallow using `expect` outside of `it` or `test` blocks | β
| | | |
+| [no-test-prefixes](docs/rules/no-test-prefixes.md) | Require using `.only` and `.skip` over `f` and `x` | β
| π§ | | |
+| [no-test-return-statement](docs/rules/no-test-return-statement.md) | Disallow explicitly returning from tests | | | | |
+| [prefer-called-with](docs/rules/prefer-called-with.md) | Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` | | | | |
+| [prefer-comparison-matcher](docs/rules/prefer-comparison-matcher.md) | Suggest using the built-in comparison matchers | | π§ | | |
+| [prefer-each](docs/rules/prefer-each.md) | Prefer using `.each` rather than manual loops | | | | |
+| [prefer-equality-matcher](docs/rules/prefer-equality-matcher.md) | Suggest using the built-in equality matchers | | | π‘ | |
+| [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md) | Suggest using `expect.assertions()` OR `expect.hasAssertions()` | | | π‘ | |
+| [prefer-expect-resolves](docs/rules/prefer-expect-resolves.md) | Prefer `await expect(...).resolves` over `expect(await ...)` syntax | | π§ | | |
+| [prefer-hooks-in-order](docs/rules/prefer-hooks-in-order.md) | Prefer having hooks in a consistent order | | | | |
+| [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md) | Suggest having hooks before any test cases | | | | |
+| [prefer-lowercase-title](docs/rules/prefer-lowercase-title.md) | Enforce lowercase test names | | π§ | | |
+| [prefer-mock-promise-shorthand](docs/rules/prefer-mock-promise-shorthand.md) | Prefer mock resolved/rejected shorthands for promises | | π§ | | |
+| [prefer-snapshot-hint](docs/rules/prefer-snapshot-hint.md) | Prefer including a hint with external snapshots | | | | |
+| [prefer-spy-on](docs/rules/prefer-spy-on.md) | Suggest using `jest.spyOn()` | | π§ | | |
+| [prefer-strict-equal](docs/rules/prefer-strict-equal.md) | Suggest using `toStrictEqual()` | | | π‘ | |
+| [prefer-to-be](docs/rules/prefer-to-be.md) | Suggest using `toBe()` for primitive literals | π¨ | π§ | | |
+| [prefer-to-contain](docs/rules/prefer-to-contain.md) | Suggest using `toContain()` | π¨ | π§ | | |
+| [prefer-to-have-length](docs/rules/prefer-to-have-length.md) | Suggest using `toHaveLength()` | π¨ | π§ | | |
+| [prefer-todo](docs/rules/prefer-todo.md) | Suggest using `test.todo` | | π§ | | |
+| [require-hook](docs/rules/require-hook.md) | Require setup and teardown code to be within a hook | | | | |
+| [require-to-throw-message](docs/rules/require-to-throw-message.md) | Require a message for `toThrow()` | | | | |
+| [require-top-level-describe](docs/rules/require-top-level-describe.md) | Require test cases and hooks to be inside a `describe` block | | | | |
+| [valid-describe-callback](docs/rules/valid-describe-callback.md) | Enforce valid `describe()` callback | β
| | | |
+| [valid-expect](docs/rules/valid-expect.md) | Enforce valid `expect()` usage | β
| | | |
+| [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md) | Require promises that have expectations in their chain to be valid | β
| | | |
+| [valid-title](docs/rules/valid-title.md) | Enforce valid titles | β
| π§ | | |
+
+### Requires Type Checking
+
+| NameΒ Β Β Β Β Β Β Β Β Β | Description | πΌ | π§ | π‘ | β |
+| :--------------------------------------------- | :----------------------------------------------------------- | :-- | :-- | :-- | :-- |
+| [unbound-method](docs/rules/unbound-method.md) | Enforce unbound methods are called with their expected scope | | | | |
+
+
+
+In order to use the rules powered by TypeScript type-checking, you must be using
+`@typescript-eslint/parser` & adjust your eslint config as outlined
[here](https://github.com/typescript-eslint/typescript-eslint/blob/main/docs/linting/TYPED_LINTING.md).
Note that unlike the type-checking rules in `@typescript-eslint/eslint-plugin`,
@@ -269,14 +284,6 @@ used on JavaScript and TypeScript projects.
Also note that `unbound-method` depends on `@typescript-eslint/eslint-plugin`,
as it extends the original `unbound-method` rule from that plugin.
-
-
-| Rule | Description | Configurations | Fixable |
-| ---------------------------------------------- | ------------------------------------------------------------ | -------------- | ------- |
-| [unbound-method](docs/rules/unbound-method.md) | Enforce unbound methods are called with their expected scope | | |
-
-
-
## Credit
- [eslint-plugin-mocha](https://github.com/lo1tuma/eslint-plugin-mocha)
@@ -290,25 +297,20 @@ This is a sister plugin to `eslint-plugin-jest` that provides support for the
matchers provided by
[`jest-extended`](https://github.com/jest-community/jest-extended).
-https://github.com/jest-community/eslint-plugin-jest-extended
+
### eslint-plugin-jest-formatting
This project aims to provide formatting rules (auto-fixable where possible) to
ensure consistency and readability in jest test suites.
-https://github.com/dangreenisrael/eslint-plugin-jest-formatting
+
### eslint-plugin-istanbul
A set of rules to enforce good practices for Istanbul, one of the code coverage
tools used by Jest.
-https://github.com/istanbuljs/eslint-plugin-istanbul
+
-[recommended]: https://img.shields.io/badge/-recommended-lightgrey.svg
-[suggest]: https://img.shields.io/badge/-suggest-yellow.svg
-[fixable]: https://img.shields.io/badge/-fixable-green.svg
-[style]: https://img.shields.io/badge/-style-blue.svg
-[deprecated]: https://img.shields.io/badge/-deprecated-red.svg
[`no-deprecated-functions`]: docs/rules/no-deprecated-functions.md
diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md
index 71d303181..69e8b569e 100644
--- a/docs/rules/consistent-test-it.md
+++ b/docs/rules/consistent-test-it.md
@@ -1,14 +1,9 @@
-# Have control over `test` and `it` usages (`consistent-test-it`)
+# Enforce `test` and `it` usage conventions (`consistent-test-it`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
-
-
+
Jest allows you to choose how you want to define your tests, using the `it` or
the `test` keywords, with multiple permutations for each:
@@ -81,8 +76,6 @@ describe('foo', function () {
});
```
-### Default configuration
-
The default configuration forces all top-level tests to use `test` and all tests
nested within `describe` to use `it`.
diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md
index f832faeb7..4e4e5017b 100644
--- a/docs/rules/expect-expect.md
+++ b/docs/rules/expect-expect.md
@@ -1,10 +1,9 @@
# Enforce assertion to be made in a test body (`expect-expect`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+β
β οΈ This rule _warns_ in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
Ensure that there is at least one `expect` call made in a test.
diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md
index 5034f4d4a..e11f3b4e1 100644
--- a/docs/rules/max-expects.md
+++ b/docs/rules/max-expects.md
@@ -1,10 +1,6 @@
# Enforces a maximum number assertion calls in a test body (`max-expects`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
As more assertions are made, there is a possible tendency for the test to be
more likely to mix multiple objectives. To avoid this, this rule reports when
diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md
index 6293ae1a4..964adf46c 100644
--- a/docs/rules/max-nested-describe.md
+++ b/docs/rules/max-nested-describe.md
@@ -1,10 +1,6 @@
# Enforces a maximum depth to nested describe calls (`max-nested-describe`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
While it's useful to be able to group your tests together within the same file
using `describe()`, having too many levels of nesting throughout your tests make
diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md
index fc61154c3..08186d77d 100644
--- a/docs/rules/no-alias-methods.md
+++ b/docs/rules/no-alias-methods.md
@@ -1,17 +1,17 @@
# Disallow alias methods (`no-alias-methods`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+πΌ This rule is enabled in the β
`recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
+This rule _warns_ in the π¨ `style`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-
+
> These aliases are going to be removed in the next major version of Jest - see
-> https://github.com/facebook/jest/issues/13164 for more
+> for more
Several Jest methods have alias names, such as `toThrow` having the alias of
`toThrowError`. This rule ensures that only the canonical name as used in the
@@ -24,8 +24,6 @@ method names used.
This rule triggers a warning if the alias name, rather than the canonical name,
of a method is used.
-### Default configuration
-
The following patterns are considered warnings:
```js
diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md
index 413008d76..e5ee46d83 100644
--- a/docs/rules/no-commented-out-tests.md
+++ b/docs/rules/no-commented-out-tests.md
@@ -1,10 +1,9 @@
# Disallow commented out tests (`no-commented-out-tests`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+β
β οΈ This rule _warns_ in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
This rule raises a warning about commented out tests. It's similar to
no-disabled-tests rule.
diff --git a/docs/rules/no-conditional-expect.md b/docs/rules/no-conditional-expect.md
index b15dd68ab..f4568b9ad 100644
--- a/docs/rules/no-conditional-expect.md
+++ b/docs/rules/no-conditional-expect.md
@@ -1,10 +1,9 @@
-# Prevent calling `expect` conditionally (`no-conditional-expect`)
+# Disallow calling `expect` conditionally (`no-conditional-expect`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
This rule prevents the use of `expect` in conditional blocks, such as `if`s &
`catch`s.
diff --git a/docs/rules/no-conditional-in-test.md b/docs/rules/no-conditional-in-test.md
index 7fe5e9c8f..45c153663 100644
--- a/docs/rules/no-conditional-in-test.md
+++ b/docs/rules/no-conditional-in-test.md
@@ -1,10 +1,6 @@
# Disallow conditional logic in tests (`no-conditional-in-test`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
Conditional logic in tests is usually an indication that a test is attempting to
cover too much, and not testing the logic it intends to. Each branch of code
diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md
index 4b3a23909..be09b695e 100644
--- a/docs/rules/no-deprecated-functions.md
+++ b/docs/rules/no-deprecated-functions.md
@@ -1,14 +1,12 @@
# Disallow use of deprecated functions (`no-deprecated-functions`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-
+
Over the years Jest has accrued some debt in the form of functions that have
either been renamed for clarity, or replaced with more powerful APIs.
diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md
index 56595ed55..0a614dde0 100644
--- a/docs/rules/no-disabled-tests.md
+++ b/docs/rules/no-disabled-tests.md
@@ -1,10 +1,9 @@
# Disallow disabled tests (`no-disabled-tests`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+β
β οΈ This rule _warns_ in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
Jest has a feature that allows you to temporarily mark tests as disabled. This
feature is often helpful while debugging or to create placeholders for future
diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md
index 551fb9e0d..83361fa41 100644
--- a/docs/rules/no-done-callback.md
+++ b/docs/rules/no-done-callback.md
@@ -1,14 +1,12 @@
-# Avoid using a callback in asynchronous tests and hooks (`no-done-callback`)
+# Disallow using a callback in asynchronous tests and hooks (`no-done-callback`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π‘ This rule provides
-[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
-that can be applied manually.
+π‘ This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
-
+
When calling asynchronous code in hooks and tests, `jest` needs to know when the
asynchronous work is complete to progress the current run.
diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md
index 72bca8b31..520284507 100644
--- a/docs/rules/no-duplicate-hooks.md
+++ b/docs/rules/no-duplicate-hooks.md
@@ -1,10 +1,6 @@
# Disallow duplicate setup and teardown hooks (`no-duplicate-hooks`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
A `describe` block should not contain duplicate hooks.
diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md
index df9136be5..efeb93b7d 100644
--- a/docs/rules/no-export.md
+++ b/docs/rules/no-export.md
@@ -1,10 +1,9 @@
# Disallow using `exports` in files containing tests (`no-export`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
Prevents using `exports` if a file has one or more tests in it.
diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md
index 02975a0b3..3b593e8b5 100644
--- a/docs/rules/no-focused-tests.md
+++ b/docs/rules/no-focused-tests.md
@@ -1,14 +1,12 @@
# Disallow focused tests (`no-focused-tests`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π‘ This rule provides
-[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
-that can be applied manually.
+π‘ This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
-
+
Jest has a feature that allows you to focus tests by appending `.only` or
diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md
index 75438f4cb..2011f84b8 100644
--- a/docs/rules/no-hooks.md
+++ b/docs/rules/no-hooks.md
@@ -1,10 +1,6 @@
# Disallow setup and teardown hooks (`no-hooks`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
Jest provides global functions for setup and teardown tasks, which are called
before/after each test case and each test suite. The use of these hooks promotes
diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md
index 495b0faeb..c6e073d41 100644
--- a/docs/rules/no-identical-title.md
+++ b/docs/rules/no-identical-title.md
@@ -1,10 +1,9 @@
# Disallow identical titles (`no-identical-title`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
Having identical titles for two different tests or test suites may create
confusion. For example, when a test with the same title as another test in the
diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md
index 033a9c3a2..bfbda1212 100644
--- a/docs/rules/no-if.md
+++ b/docs/rules/no-if.md
@@ -1,9 +1,9 @@
# Disallow conditional logic (`no-if`)
β This rule is deprecated. It was replaced by
-[no-conditional-in-test](no-conditional-in-test.md).
+[`no-conditional-in-test`](no-conditional-in-test.md).
-
+
Conditional logic in tests is usually an indication that a test is attempting to
cover too much, and not testing the logic it intends to. Each branch of code
diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md
index a4a394614..82d9479a2 100644
--- a/docs/rules/no-interpolation-in-snapshots.md
+++ b/docs/rules/no-interpolation-in-snapshots.md
@@ -1,10 +1,9 @@
# Disallow string interpolation inside snapshots (`no-interpolation-in-snapshots`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
Prevents the use of string interpolations in snapshots.
diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md
index fb48142bb..f3bc02267 100644
--- a/docs/rules/no-jasmine-globals.md
+++ b/docs/rules/no-jasmine-globals.md
@@ -1,14 +1,12 @@
# Disallow Jasmine globals (`no-jasmine-globals`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-
+
`jest` uses `jasmine` as a test runner. A side effect of this is that both a
`jasmine` object, and some jasmine-specific globals, are exposed to the test
@@ -22,7 +20,7 @@ API.
This rule reports on any usage of Jasmine globals, which is not ported to Jest,
and suggests alternatives from Jest's own API.
-### Default configuration
+## Examples
The following patterns are considered warnings:
diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md
index 8a4d6e27e..bfc371ba9 100644
--- a/docs/rules/no-large-snapshots.md
+++ b/docs/rules/no-large-snapshots.md
@@ -1,10 +1,6 @@
-# disallow large snapshots (`no-large-snapshots`)
+# Disallow large snapshots (`no-large-snapshots`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
When using Jest's snapshot capability one should be mindful of the size of
created snapshots. As a general best practice snapshots should be limited in
diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md
index 4c03ce549..84106ac2b 100644
--- a/docs/rules/no-mocks-import.md
+++ b/docs/rules/no-mocks-import.md
@@ -1,10 +1,9 @@
# Disallow manually importing from `__mocks__` (`no-mocks-import`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
When using `jest.mock`, your tests (just like the code being tested) should
import from `./x`, not `./__mocks__/x`. Not following this rule can lead to
diff --git a/docs/rules/no-restricted-jest-methods.md b/docs/rules/no-restricted-jest-methods.md
index 322bd6023..40b928ed2 100644
--- a/docs/rules/no-restricted-jest-methods.md
+++ b/docs/rules/no-restricted-jest-methods.md
@@ -1,10 +1,6 @@
# Disallow specific `jest.` methods (`no-restricted-jest-methods`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
You may wish to restrict the use of specific `jest` methods.
diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md
index c5efff6ad..1d33448a2 100644
--- a/docs/rules/no-restricted-matchers.md
+++ b/docs/rules/no-restricted-matchers.md
@@ -1,10 +1,6 @@
# Disallow specific matchers & modifiers (`no-restricted-matchers`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
You may want to ban specific matchers & modifiers from being used.
diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md
index 9152161b0..e80056962 100644
--- a/docs/rules/no-standalone-expect.md
+++ b/docs/rules/no-standalone-expect.md
@@ -1,10 +1,9 @@
# Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
Prevents `expect` statements outside of a `test` or `it` block. An `expect`
within a helper function (but outside of a `test` or `it` block) will not
diff --git a/docs/rules/no-test-prefixes.md b/docs/rules/no-test-prefixes.md
index 5a9eaee97..625eedb5d 100644
--- a/docs/rules/no-test-prefixes.md
+++ b/docs/rules/no-test-prefixes.md
@@ -1,14 +1,12 @@
-# Use `.only` and `.skip` over `f` and `x` (`no-test-prefixes`)
+# Require using `.only` and `.skip` over `f` and `x` (`no-test-prefixes`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-
+
Jest allows you to choose how you want to define focused and skipped tests, with
multiple permutations for each:
diff --git a/docs/rules/no-test-return-statement.md b/docs/rules/no-test-return-statement.md
index f5d6a1e53..80043901c 100644
--- a/docs/rules/no-test-return-statement.md
+++ b/docs/rules/no-test-return-statement.md
@@ -1,10 +1,6 @@
# Disallow explicitly returning from tests (`no-test-return-statement`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
Tests in Jest should be void and not return values.
diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md
index b9acf363b..b4446b830 100644
--- a/docs/rules/prefer-called-with.md
+++ b/docs/rules/prefer-called-with.md
@@ -1,10 +1,6 @@
# Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
The `toBeCalled()` matcher is used to assert that a mock function has been
called one or more times, without checking the arguments passed. The assertion
diff --git a/docs/rules/prefer-comparison-matcher.md b/docs/rules/prefer-comparison-matcher.md
index 5f27ffce4..11863dcdd 100644
--- a/docs/rules/prefer-comparison-matcher.md
+++ b/docs/rules/prefer-comparison-matcher.md
@@ -1,14 +1,9 @@
# Suggest using the built-in comparison matchers (`prefer-comparison-matcher`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
-
-
+
Jest has a number of built-in matchers for comparing numbers, which allow for
more readable tests and error messages if an expectation fails.
diff --git a/docs/rules/prefer-each.md b/docs/rules/prefer-each.md
index 381a063c4..e06d30a00 100644
--- a/docs/rules/prefer-each.md
+++ b/docs/rules/prefer-each.md
@@ -1,10 +1,6 @@
# Prefer using `.each` rather than manual loops (`prefer-each`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
Reports where you might be able to use `.each` instead of native loops.
diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md
index afcec0356..6e33e8ad5 100644
--- a/docs/rules/prefer-equality-matcher.md
+++ b/docs/rules/prefer-equality-matcher.md
@@ -1,14 +1,9 @@
# Suggest using the built-in equality matchers (`prefer-equality-matcher`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π‘ This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
-π‘ This rule provides
-[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
-that can be applied manually.
-
-
+
Jest has built-in matchers for expecting equality, which allow for more readable
tests and error messages if an expectation fails.
diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md
index dd55676eb..3fb2c4aae 100644
--- a/docs/rules/prefer-expect-assertions.md
+++ b/docs/rules/prefer-expect-assertions.md
@@ -1,14 +1,9 @@
# Suggest using `expect.assertions()` OR `expect.hasAssertions()` (`prefer-expect-assertions`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π‘ This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
-π‘ This rule provides
-[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
-that can be applied manually.
-
-
+
Ensure every test to have either `expect.assertions()` OR
`expect.hasAssertions()` as its first expression.
@@ -37,8 +32,6 @@ test('my test', () => {
});
```
-### Default configuration
-
The following patterns are considered warnings:
```js
diff --git a/docs/rules/prefer-expect-resolves.md b/docs/rules/prefer-expect-resolves.md
index 13e372099..3457876eb 100644
--- a/docs/rules/prefer-expect-resolves.md
+++ b/docs/rules/prefer-expect-resolves.md
@@ -1,14 +1,9 @@
# Prefer `await expect(...).resolves` over `expect(await ...)` syntax (`prefer-expect-resolves`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
-
-
+
When working with promises, there are two primary ways you can test the resolved
value:
diff --git a/docs/rules/prefer-hooks-in-order.md b/docs/rules/prefer-hooks-in-order.md
index d24e21957..fca3a92f8 100644
--- a/docs/rules/prefer-hooks-in-order.md
+++ b/docs/rules/prefer-hooks-in-order.md
@@ -1,10 +1,6 @@
# Prefer having hooks in a consistent order (`prefer-hooks-in-order`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
While hooks can be setup in any order, they're always called by `jest` in this
specific order:
diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md
index 74a36ed0d..a176ae45c 100644
--- a/docs/rules/prefer-hooks-on-top.md
+++ b/docs/rules/prefer-hooks-on-top.md
@@ -1,10 +1,6 @@
# Suggest having hooks before any test cases (`prefer-hooks-on-top`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
While hooks can be setup anywhere in a test file, they are always called in a
specific order, which means it can be confusing if they're intermixed with test
diff --git a/docs/rules/prefer-lowercase-title.md b/docs/rules/prefer-lowercase-title.md
index 742481a55..d0c1cf094 100644
--- a/docs/rules/prefer-lowercase-title.md
+++ b/docs/rules/prefer-lowercase-title.md
@@ -1,14 +1,9 @@
# Enforce lowercase test names (`prefer-lowercase-title`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
-
-
+
## Rule details
diff --git a/docs/rules/prefer-mock-promise-shorthand.md b/docs/rules/prefer-mock-promise-shorthand.md
index 90d3ef62d..2c69021ff 100644
--- a/docs/rules/prefer-mock-promise-shorthand.md
+++ b/docs/rules/prefer-mock-promise-shorthand.md
@@ -1,14 +1,9 @@
# Prefer mock resolved/rejected shorthands for promises (`prefer-mock-promise-shorthand`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
-
-
+
When working with mocks of functions that return promises, Jest provides some
API sugar functions to reduce the amount of boilerplate you have to write.
diff --git a/docs/rules/prefer-snapshot-hint.md b/docs/rules/prefer-snapshot-hint.md
index d6f91666d..ceb90547e 100644
--- a/docs/rules/prefer-snapshot-hint.md
+++ b/docs/rules/prefer-snapshot-hint.md
@@ -1,10 +1,6 @@
# Prefer including a hint with external snapshots (`prefer-snapshot-hint`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
When working with external snapshot matchers it's considered best practice to
provide a hint (as the last argument to the matcher) describing the expected
diff --git a/docs/rules/prefer-spy-on.md b/docs/rules/prefer-spy-on.md
index 7a3d071e3..5904a616b 100644
--- a/docs/rules/prefer-spy-on.md
+++ b/docs/rules/prefer-spy-on.md
@@ -1,14 +1,9 @@
# Suggest using `jest.spyOn()` (`prefer-spy-on`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
-
-
+
When mocking a function by overwriting a property you have to manually restore
the original implementation when cleaning up. When using `jest.spyOn()` Jest
@@ -34,8 +29,6 @@ jest.spyOn(Date, 'now').mockReturnValue(10); // Will always return 10
This rule triggers a warning if an object's property is overwritten with a jest
mock.
-### Default configuration
-
The following patterns are considered warnings:
```js
diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md
index 1e4689027..650fad2e3 100644
--- a/docs/rules/prefer-strict-equal.md
+++ b/docs/rules/prefer-strict-equal.md
@@ -1,14 +1,9 @@
# Suggest using `toStrictEqual()` (`prefer-strict-equal`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π‘ This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
-π‘ This rule provides
-[suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions)
-that can be applied manually.
-
-
+
`toStrictEqual` not only checks that two objects contain the same data but also
that they have the same structure. It is common to expect objects to not only
@@ -19,8 +14,6 @@ catch cases where two objects do not have identical keys.
This rule triggers a warning if `toEqual()` is used to assert equality.
-### Default configuration
-
The following pattern is considered warning:
```js
diff --git a/docs/rules/prefer-to-be.md b/docs/rules/prefer-to-be.md
index 60d0e8e40..d5c734c10 100644
--- a/docs/rules/prefer-to-be.md
+++ b/docs/rules/prefer-to-be.md
@@ -1,14 +1,12 @@
# Suggest using `toBe()` for primitive literals (`prefer-to-be`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `style`.
+π¨ This rule is enabled in the `style`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-
+
When asserting against primitive literals such as numbers and strings, the
equality matchers all operate the same, but read slightly differently in code.
diff --git a/docs/rules/prefer-to-contain.md b/docs/rules/prefer-to-contain.md
index d6b4600a4..3442a9bd6 100644
--- a/docs/rules/prefer-to-contain.md
+++ b/docs/rules/prefer-to-contain.md
@@ -1,14 +1,12 @@
# Suggest using `toContain()` (`prefer-to-contain`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `style`.
+π¨ This rule is enabled in the `style`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-
+
In order to have a better failure message, `toContain()` should be used upon
asserting expectations on an array containing an object.
@@ -30,8 +28,6 @@ expect(a.includes(b)).not.toBe(true);
expect(a.includes(b)).toBe(false);
```
-### Default configuration
-
The following patterns are considered warnings:
```js
diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md
index 38d965838..c040852be 100644
--- a/docs/rules/prefer-to-have-length.md
+++ b/docs/rules/prefer-to-have-length.md
@@ -1,14 +1,12 @@
# Suggest using `toHaveLength()` (`prefer-to-have-length`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `style`.
+π¨ This rule is enabled in the `style`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-
+
In order to have a better failure message, `toHaveLength()` should be used upon
asserting expectations on objects length property.
@@ -24,8 +22,6 @@ expect(files.length).toBe(1);
This rule is enabled by default.
-### Default configuration
-
The following patterns are considered warnings:
```js
diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md
index 104ca69fc..1fac05323 100644
--- a/docs/rules/prefer-todo.md
+++ b/docs/rules/prefer-todo.md
@@ -1,14 +1,9 @@
# Suggest using `test.todo` (`prefer-todo`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
-
-
+
When test cases are empty then it is better to mark them as `test.todo` as it
will be highlighted in the summary output.
@@ -21,8 +16,6 @@ This rule triggers a warning if empty test cases are used without 'test.todo'.
test('i need to write this test');
```
-### Default configuration
-
The following pattern is considered warning:
```js
diff --git a/docs/rules/require-hook.md b/docs/rules/require-hook.md
index a8e6fc6d4..ab97ad2a8 100644
--- a/docs/rules/require-hook.md
+++ b/docs/rules/require-hook.md
@@ -1,10 +1,6 @@
# Require setup and teardown code to be within a hook (`require-hook`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
Often while writing tests you have some setup work that needs to happen before
tests run, and you have some finishing work that needs to happen after tests
diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md
index afb529cc0..aa38d3e09 100644
--- a/docs/rules/require-to-throw-message.md
+++ b/docs/rules/require-to-throw-message.md
@@ -1,10 +1,6 @@
# Require a message for `toThrow()` (`require-to-throw-message`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
`toThrow()` (and its alias `toThrowError()`) is used to check if an error is
thrown by a function call, such as in `expect(() => a()).toThrow()`. However, if
@@ -16,8 +12,6 @@ message ensures that the intended error is thrown.
This rule triggers a warning if `toThrow()` or `toThrowError()` is used without
an error message.
-### Default configuration
-
The following patterns are considered warnings:
```js
diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md
index 8e99f5337..04294db49 100644
--- a/docs/rules/require-top-level-describe.md
+++ b/docs/rules/require-top-level-describe.md
@@ -1,10 +1,6 @@
# Require test cases and hooks to be inside a `describe` block (`require-top-level-describe`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
-
-
+
Jest allows you to organise your test files the way you want it. However, the
more your codebase grows, the more it becomes hard to navigate in your test
diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md
index 95998e8cc..240926c58 100644
--- a/docs/rules/unbound-method.md
+++ b/docs/rules/unbound-method.md
@@ -1,10 +1,8 @@
# Enforce unbound methods are called with their expected scope (`unbound-method`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`.
+π This rule requires type information.
-
+
## Rule details
diff --git a/docs/rules/valid-describe-callback.md b/docs/rules/valid-describe-callback.md
index 920e46c0c..861331c7b 100644
--- a/docs/rules/valid-describe-callback.md
+++ b/docs/rules/valid-describe-callback.md
@@ -1,10 +1,9 @@
# Enforce valid `describe()` callback (`valid-describe-callback`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
Using an improper `describe()` callback function can lead to unexpected test
errors.
diff --git a/docs/rules/valid-expect-in-promise.md b/docs/rules/valid-expect-in-promise.md
index d8a1cbaab..e704f5ffd 100644
--- a/docs/rules/valid-expect-in-promise.md
+++ b/docs/rules/valid-expect-in-promise.md
@@ -1,10 +1,9 @@
-# Ensure promises that have expectations in their chain are valid (`valid-expect-in-promise`)
+# Require promises that have expectations in their chain to be valid (`valid-expect-in-promise`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
Ensure promises that include expectations are returned or awaited.
diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md
index 09d41318f..535e2b97e 100644
--- a/docs/rules/valid-expect.md
+++ b/docs/rules/valid-expect.md
@@ -1,10 +1,9 @@
# Enforce valid `expect()` usage (`valid-expect`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-
+
Ensure `expect()` is called with a single argument and there is an actual
expectation made.
@@ -109,8 +108,6 @@ This is useful when you're using libraries that increase the number of arguments
supported by `expect`, such as
[`jest-expect-message`](https://www.npmjs.com/package/jest-expect-message).
-### Default configuration
-
The following patterns are considered warnings:
```js
diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md
index 87c1993f0..ecdf55df4 100644
--- a/docs/rules/valid-title.md
+++ b/docs/rules/valid-title.md
@@ -1,14 +1,12 @@
# Enforce valid titles (`valid-title`)
-πΌ This rule is enabled in the following
-[configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):
-`all`, `recommended`.
+β
This rule is enabled in the `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
-π§ This rule is automatically fixable using the `--fix`
-[option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
-on the command line.
+π§ This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
-
+
Checks that the title of Jest blocks are valid by ensuring that titles are:
diff --git a/package.json b/package.json
index 432f0b285..7d621266f 100644
--- a/package.json
+++ b/package.json
@@ -29,7 +29,7 @@
"prettier:write": "prettier --write 'docs/**/*.md' README.md '.github/**' package.json tsconfig.json src/globals.json .yarnrc.yml",
"postpublish": "pinst --enable",
"test": "jest",
- "tools:regenerate-docs": "ts-node -T tools/regenerate-docs",
+ "tools:regenerate-docs": "yarn prepack && eslint-doc-generator --ignore-config all --rule-doc-title-format desc-parens-name --rule-doc-section-include \"Rule details\" --rule-list-columns name,description,configs,fixable,hasSuggestions,deprecated --split-by meta.docs.requiresTypeChecking --url-configs \"https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations\" && yarn prettier:write",
"typecheck": "tsc -p ."
},
"commitlint": {
@@ -121,6 +121,7 @@
"dedent": "^0.7.0",
"eslint": "^6.0.0 || ^7.0.0 || ^8.0.0",
"eslint-config-prettier": "^8.3.0",
+ "eslint-doc-generator": "^0.18.1",
"eslint-plugin-eslint-comments": "^3.1.2",
"eslint-plugin-eslint-plugin": "^5.0.6",
"eslint-plugin-import": "^2.25.1",
diff --git a/src/rules/consistent-test-it.ts b/src/rules/consistent-test-it.ts
index 6f0705d16..8341a8d1d 100644
--- a/src/rules/consistent-test-it.ts
+++ b/src/rules/consistent-test-it.ts
@@ -35,7 +35,7 @@ export default createRule<
meta: {
docs: {
category: 'Best Practices',
- description: 'Have control over `test` and `it` usages',
+ description: 'Enforce `test` and `it` usage conventions',
recommended: false,
},
fixable: 'code',
diff --git a/src/rules/no-conditional-expect.ts b/src/rules/no-conditional-expect.ts
index b6489df11..cd0551878 100644
--- a/src/rules/no-conditional-expect.ts
+++ b/src/rules/no-conditional-expect.ts
@@ -18,7 +18,7 @@ export default createRule({
name: __filename,
meta: {
docs: {
- description: 'Prevent calling `expect` conditionally',
+ description: 'Disallow calling `expect` conditionally',
category: 'Best Practices',
recommended: 'error',
},
diff --git a/src/rules/no-done-callback.ts b/src/rules/no-done-callback.ts
index 9ffb70e1b..a356f2664 100644
--- a/src/rules/no-done-callback.ts
+++ b/src/rules/no-done-callback.ts
@@ -28,7 +28,7 @@ export default createRule({
meta: {
docs: {
category: 'Best Practices',
- description: 'Avoid using a callback in asynchronous tests and hooks',
+ description: 'Disallow using a callback in asynchronous tests and hooks',
recommended: 'error',
},
messages: {
diff --git a/src/rules/no-large-snapshots.ts b/src/rules/no-large-snapshots.ts
index d3d88131c..6619108c2 100644
--- a/src/rules/no-large-snapshots.ts
+++ b/src/rules/no-large-snapshots.ts
@@ -72,7 +72,7 @@ export default createRule<[RuleOptions], MessageId>({
meta: {
docs: {
category: 'Best Practices',
- description: 'disallow large snapshots',
+ description: 'Disallow large snapshots',
recommended: false,
},
messages: {
diff --git a/src/rules/no-test-prefixes.ts b/src/rules/no-test-prefixes.ts
index dcd5fbf42..771609e4e 100644
--- a/src/rules/no-test-prefixes.ts
+++ b/src/rules/no-test-prefixes.ts
@@ -6,7 +6,7 @@ export default createRule({
meta: {
docs: {
category: 'Best Practices',
- description: 'Use `.only` and `.skip` over `f` and `x`',
+ description: 'Require using `.only` and `.skip` over `f` and `x`',
recommended: 'error',
},
messages: {
diff --git a/src/rules/valid-expect-in-promise.ts b/src/rules/valid-expect-in-promise.ts
index 851ba830c..32abcbf0d 100644
--- a/src/rules/valid-expect-in-promise.ts
+++ b/src/rules/valid-expect-in-promise.ts
@@ -342,7 +342,7 @@ export default createRule({
docs: {
category: 'Best Practices',
description:
- 'Ensure promises that have expectations in their chain are valid',
+ 'Require promises that have expectations in their chain to be valid',
recommended: 'error',
},
messages: {
diff --git a/tools/regenerate-docs.ts b/tools/regenerate-docs.ts
deleted file mode 100644
index af0f4bd72..000000000
--- a/tools/regenerate-docs.ts
+++ /dev/null
@@ -1,264 +0,0 @@
-#!/usr/bin/env ts-node-transpile-only
-
-import * as fs from 'fs';
-import * as path from 'path';
-import type { JSONSchema, TSESLint } from '@typescript-eslint/utils';
-import prettier, { Options } from 'prettier';
-import { prettier as prettierRC } from '../package.json';
-import plugin from '../src/index';
-import { getRuleNoticeLines } from './rule-notices';
-
-// Marker so that rule doc header (title/notices) can be automatically updated.
-export const END_RULE_HEADER_MARKER = '';
-
-const pathTo = {
- readme: path.resolve(__dirname, '../README.md'),
- rules: path.resolve(__dirname, '../src/rules'),
- docs: path.resolve(__dirname, '../docs'),
-};
-
-const format = (str: string): string =>
- prettier.format(str, { ...(prettierRC as Options), parser: 'markdown' });
-
-type FixType = 'fixable' | 'suggest';
-
-interface RuleDetails {
- name: string;
- description: string;
- fixable: FixType | false;
- requiresTypeChecking: boolean;
- deprecated: boolean;
- schema: JSONSchema.JSONSchema4;
-}
-
-type RuleModule = TSESLint.RuleModule & {
- meta: Required, 'docs'>>;
-};
-
-const staticElements = {
- listHeaderRow: ['Rule', 'Description', 'Configurations', 'Fixable'],
- listSpacerRow: Array(5).fill('-'),
-};
-
-const getConfigurationColumnValueForRule = (rule: RuleDetails): string => {
- if (`jest/${rule.name}` in plugin.configs.recommended.rules) {
- return '![recommended][]';
- }
-
- if (`jest/${rule.name}` in plugin.configs.style.rules) {
- return '![style][]';
- }
-
- if (rule.deprecated) {
- return '![deprecated][]';
- }
-
- return '';
-};
-
-const buildRuleRow = (rule: RuleDetails): string[] => [
- `[${rule.name}](docs/rules/${rule.name}.md)`,
- rule.description,
- getConfigurationColumnValueForRule(rule),
- rule.fixable ? `![${rule.fixable}][]` : '',
-];
-
-const generateRulesListMarkdown = (details: RuleDetails[]): string =>
- [
- staticElements.listHeaderRow,
- staticElements.listSpacerRow,
- ...details
- .sort(({ name: a }, { name: b }) => a.localeCompare(b))
- .map(buildRuleRow),
- ]
- .map(column => [...column, ' '].join('|'))
- .join('\n');
-
-const updateRulesList = (
- listName: 'base' | 'type',
- details: RuleDetails[],
- markdown: string,
-): string => {
- const listBeginMarker = ``;
- const listEndMarker = ``;
-
- const listStartIndex = markdown.indexOf(listBeginMarker);
- const listEndIndex = markdown.indexOf(listEndMarker);
-
- if (listStartIndex === -1 || listEndIndex === -1) {
- throw new Error(`cannot find start or end of rules list`);
- }
-
- return [
- markdown.substring(0, listStartIndex - 1),
- listBeginMarker,
- '',
- generateRulesListMarkdown(details),
- '',
- markdown.substring(listEndIndex),
- ].join('\n');
-};
-
-/**
- * Generate a rule doc header for a particular rule.
- * @param description - rule description
- * @param name - rule name
- * @returns {string[]} - lines for new header including marker
- */
-const generateRuleHeaderLines = (
- description: string,
- name: string,
-): string[] => [
- `# ${description} (\`${name}\`)`,
- ...getRuleNoticeLines(name),
- END_RULE_HEADER_MARKER,
-];
-
-/**
- * Replace the header of a doc up to and including the specified marker.
- * Insert at beginning if header doesn't exist.
- * @param lines - lines of doc
- * @param newHeaderLines - lines of new header including marker
- * @param marker - marker to indicate end of header
- */
-const replaceOrCreateHeader = (
- lines: string[],
- newHeaderLines: string[],
- marker: string,
-) => {
- const markerLineIndex = lines.findIndex(line => line === marker);
-
- // Replace header section (or create at top if missing).
- lines.splice(0, markerLineIndex + 1, ...newHeaderLines);
-};
-
-/**
- * Ensure a rule doc contains (or doesn't contain) some particular content.
- * Upon failure, output the failure and set a failure exit code.
- * @param ruleName - which rule we are checking
- * @param contents - the rule doc's contents
- * @param content - the content we are checking for
- * @param expected - whether the content should be present or not present
- */
-const expectContent = (
- ruleName: string,
- contents: string,
- content: string,
- expected: boolean,
-) => {
- if (contents.includes(content) !== expected) {
- console.error(
- `\`${ruleName}\` rule doc should ${
- expected ? '' : 'not '
- }have included: ${content}`,
- );
- process.exitCode = 1;
- }
-};
-
-/**
- * Gather a list of named options from a rule schema.
- * @param jsonSchema - the JSON schema to check
- * @returns - list of named options we could detect from the schema
- */
-const getAllNamedOptions = (jsonSchema: JSONSchema.JSONSchema4): string[] => {
- if (!jsonSchema) {
- return [];
- }
-
- if (Array.isArray(jsonSchema)) {
- return jsonSchema.flatMap(getAllNamedOptions);
- }
-
- if (jsonSchema.items) {
- return getAllNamedOptions(jsonSchema.items);
- }
-
- if (jsonSchema.properties) {
- return Object.keys(jsonSchema.properties);
- }
-
- return [];
-};
-
-/**
- * Check if a rule schema is non-blank/empty and thus has actual options.
- * @param jsonSchema - the JSON schema to check
- * @returns - whether the schema has options
- */
-const hasOptions = (jsonSchema: JSONSchema.JSONSchema4): boolean =>
- (Array.isArray(jsonSchema) && jsonSchema.length > 0) ||
- (typeof jsonSchema === 'object' && Object.keys(jsonSchema).length > 0);
-
-// copied from https://github.com/babel/babel/blob/d8da63c929f2d28c401571e2a43166678c555bc4/packages/babel-helpers/src/helpers.js#L602-L606
-/* istanbul ignore next */
-const interopRequireDefault = (obj: any): { default: any } =>
- obj && obj.__esModule ? obj : { default: obj };
-
-const importDefault = (moduleName: string) =>
- // eslint-disable-next-line @typescript-eslint/no-require-imports
- interopRequireDefault(require(moduleName)).default;
-
-const requireJestRule = (name: string): RuleModule =>
- importDefault(path.join(pathTo.rules, name)) as RuleModule;
-
-const details: RuleDetails[] = Object.keys(plugin.rules)
- .map(name => [name, requireJestRule(name)] as const)
- .filter(
- (nameAndRule): nameAndRule is [string, Required] =>
- !!nameAndRule[1].meta,
- )
- .map(
- ([name, rule]): RuleDetails => ({
- name,
- description: rule.meta.docs.description,
- fixable: rule.meta.fixable
- ? 'fixable'
- : rule.meta.hasSuggestions
- ? 'suggest'
- : false,
- requiresTypeChecking: rule.meta.docs.requiresTypeChecking ?? false,
- deprecated: rule.meta.deprecated ?? false,
- schema: rule.meta.schema,
- }),
- );
-
-details.forEach(({ name, description, schema }) => {
- const pathToDoc = path.join(pathTo.docs, 'rules', `${name}.md`);
- const contents = fs.readFileSync(pathToDoc).toString();
- const lines = contents.split('\n');
-
- // Regenerate the header (title/notices) of each rule doc.
- const newHeaderLines = generateRuleHeaderLines(description, name);
-
- replaceOrCreateHeader(lines, newHeaderLines, END_RULE_HEADER_MARKER);
-
- fs.writeFileSync(pathToDoc, format(lines.join('\n')));
-
- // Check for potential issues with the rule doc.
-
- // "Rule details" section.
- expectContent(name, contents, '## Rule details', true);
-
- // "Options" section.
- expectContent(name, contents, '## Options', hasOptions(schema));
- for (const namedOption of getAllNamedOptions(schema)) {
- expectContent(name, contents, namedOption, true); // Each rule option is mentioned.
- }
-});
-
-const [baseRules, typeRules] = details.reduce<[RuleDetails[], RuleDetails[]]>(
- (groups, details) => {
- groups[details.requiresTypeChecking ? 1 : 0].push(details);
-
- return groups;
- },
- [[], []],
-);
-
-let readme = fs.readFileSync(pathTo.readme, 'utf8');
-
-readme = updateRulesList('base', baseRules, readme);
-readme = updateRulesList('type', typeRules, readme);
-
-fs.writeFileSync(pathTo.readme, format(readme), 'utf8');
diff --git a/tools/rule-notices.ts b/tools/rule-notices.ts
deleted file mode 100644
index d73a09605..000000000
--- a/tools/rule-notices.ts
+++ /dev/null
@@ -1,116 +0,0 @@
-import plugin from '../src';
-
-enum MESSAGE_TYPE {
- CONFIGS = 'configs',
- DEPRECATED = 'deprecated',
- FIXABLE = 'fixable',
- HAS_SUGGESTIONS = 'hasSuggestions',
-}
-
-export const MESSAGES = {
- [MESSAGE_TYPE.CONFIGS]:
- 'πΌ This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations):',
- [MESSAGE_TYPE.DEPRECATED]: 'β This rule is deprecated.',
- [MESSAGE_TYPE.FIXABLE]:
- 'π§ This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line.',
- [MESSAGE_TYPE.HAS_SUGGESTIONS]:
- 'π‘ This rule provides [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions) that can be applied manually.',
-};
-
-type Rule = typeof plugin.rules[string];
-
-/**
- * Get config names that a given rule belongs to.
- */
-function getConfigsForRule(ruleName: string) {
- const { configs } = plugin;
- const configNames: Array = [];
- let configName: keyof typeof configs;
-
- for (configName in configs) {
- const config = configs[configName];
- const value = config.rules[`jest/${ruleName}`];
- const isEnabled = [2, 'error'].includes(value);
-
- if (isEnabled) {
- configNames.push(configName);
- }
- }
-
- return configNames.sort();
-}
-
-/**
- * Convert list of configs to string list of formatted names.
- */
-function configNamesToList(configNames: readonly string[]) {
- return `\`${configNames.join('`, `')}\``;
-}
-
-/**
- * Convert list of rule names to string list of links.
- */
-function rulesNamesToList(ruleNames: readonly string[]) {
- return ruleNames.map(ruleName => `[${ruleName}](${ruleName}.md)`).join(', ');
-}
-
-/**
- * Determine which notices should and should not be included at the top of a rule doc.
- */
-export function getNoticesForRule(rule: Rule) {
- const notices: {
- [key in MESSAGE_TYPE]: boolean;
- } = {
- [MESSAGE_TYPE.CONFIGS]: !rule.meta.deprecated,
- [MESSAGE_TYPE.DEPRECATED]: rule.meta.deprecated || false,
- [MESSAGE_TYPE.FIXABLE]: Boolean(rule.meta.fixable),
- [MESSAGE_TYPE.HAS_SUGGESTIONS]: rule.meta.hasSuggestions || false,
- };
-
- return notices;
-}
-
-/**
- * Get the lines for the notice section at the top of a rule doc.
- */
-export function getRuleNoticeLines(ruleName: string) {
- const lines: string[] = [];
-
- const rule = plugin.rules[ruleName];
- const notices = getNoticesForRule(rule);
- let messageType: keyof typeof notices;
-
- for (messageType in notices) {
- const expected = notices[messageType];
-
- if (!expected) {
- // This notice should not be included.
- continue;
- }
-
- lines.push(''); // Blank line first.
-
- if (messageType === MESSAGE_TYPE.CONFIGS) {
- // This notice should have a list of the rule's configs.
- const configsEnabled = getConfigsForRule(ruleName);
- const message = `${MESSAGES[MESSAGE_TYPE.CONFIGS]} ${configNamesToList(
- configsEnabled,
- )}.`;
-
- lines.push(message);
- } else if (messageType === MESSAGE_TYPE.DEPRECATED) {
- // This notice should include links to the replacement rule(s) if available.
- const message = rule.meta.replacedBy
- ? `${MESSAGES[messageType]} It was replaced by ${rulesNamesToList(
- rule.meta.replacedBy,
- )}.`
- : MESSAGES[messageType];
-
- lines.push(message);
- } else {
- lines.push(MESSAGES[messageType]);
- }
- }
-
- return lines;
-}
diff --git a/yarn.lock b/yarn.lock
index fbaf26df6..ddb6aa8e4 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -2817,7 +2817,7 @@ __metadata:
languageName: node
linkType: hard
-"@typescript-eslint/utils@npm:5.41.0, @typescript-eslint/utils@npm:^5.10.0":
+"@typescript-eslint/utils@npm:5.41.0, @typescript-eslint/utils@npm:^5.10.0, @typescript-eslint/utils@npm:^5.38.1":
version: 5.41.0
resolution: "@typescript-eslint/utils@npm:5.41.0"
dependencies:
@@ -3462,6 +3462,13 @@ __metadata:
languageName: node
linkType: hard
+"camelcase@npm:^7.0.0":
+ version: 7.0.0
+ resolution: "camelcase@npm:7.0.0"
+ checksum: 162d59607b3b46e910af151348d5e40af579048a5d07f3c06370b096ca0d42ba4a88bd92cf4e3482645ba1ffdd6f744d8273c1b9594e493fc10883d54adf7cbe
+ languageName: node
+ linkType: hard
+
"caniuse-lite@npm:^1.0.30001400":
version: 1.0.30001427
resolution: "caniuse-lite@npm:1.0.30001427"
@@ -3810,7 +3817,7 @@ __metadata:
languageName: node
linkType: hard
-"commander@npm:^9.3.0":
+"commander@npm:^9.3.0, commander@npm:^9.4.0":
version: 9.4.1
resolution: "commander@npm:9.4.1"
checksum: bfb18e325a5bdf772763c2213d5c7d9e77144d944124e988bcd8e5e65fb6d45d5d4e86b09155d0f2556c9a59c31e428720e57968bcd050b2306e910a0bf3cf13
@@ -4498,6 +4505,24 @@ __metadata:
languageName: node
linkType: hard
+"eslint-doc-generator@npm:^0.18.1":
+ version: 0.18.1
+ resolution: "eslint-doc-generator@npm:0.18.1"
+ dependencies:
+ "@typescript-eslint/utils": ^5.38.1
+ camelcase: ^7.0.0
+ commander: ^9.4.0
+ jest-diff: ^29.2.1
+ markdown-table: ^3.0.2
+ type-fest: ^3.0.0
+ peerDependencies:
+ eslint: ">= 7"
+ bin:
+ eslint-doc-generator: dist/bin/eslint-doc-generator.js
+ checksum: b03593fecf7fb01c76f6ccbd435fe5657e1a4eb6af1b8257d76c89ccbb4eb764df321847cbb444da720ffb67fac0e83ac37724e3a9d063d711a7f3bbeb438caa
+ languageName: node
+ linkType: hard
+
"eslint-import-resolver-node@npm:^0.3.6":
version: 0.3.6
resolution: "eslint-import-resolver-node@npm:0.3.6"
@@ -4606,6 +4631,7 @@ __metadata:
dedent: ^0.7.0
eslint: ^6.0.0 || ^7.0.0 || ^8.0.0
eslint-config-prettier: ^8.3.0
+ eslint-doc-generator: ^0.18.1
eslint-plugin-eslint-comments: ^3.1.2
eslint-plugin-eslint-plugin: ^5.0.6
eslint-plugin-import: ^2.25.1
@@ -7256,6 +7282,13 @@ __metadata:
languageName: node
linkType: hard
+"markdown-table@npm:^3.0.2":
+ version: 3.0.2
+ resolution: "markdown-table@npm:3.0.2"
+ checksum: 7bd9eb54e7ac15165f79730ac6357b8194294552f727bcb34e29f3f1b72823c1220cb61153ebf0962c8faac4d25e49c62e8e9471cd6352a67cdca99928ecade1
+ languageName: node
+ linkType: hard
+
"marked-terminal@npm:^5.0.0":
version: 5.1.1
resolution: "marked-terminal@npm:5.1.1"
@@ -9848,6 +9881,13 @@ __metadata:
languageName: node
linkType: hard
+"type-fest@npm:^3.0.0":
+ version: 3.1.0
+ resolution: "type-fest@npm:3.1.0"
+ checksum: 22a0402afafab05edb7b45456d6ebfdcfc616f84a98266857e89bd656a14b5007e86d1a50b12746624b6aafb17dad3f437065df8adfa1b04bb970894db1fe940
+ languageName: node
+ linkType: hard
+
"typescript@npm:^4.4.0, typescript@npm:^4.6.4":
version: 4.8.4
resolution: "typescript@npm:4.8.4"