From 9209b146dbe502d27f21784a92f5df2855841c1b 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 --- README.md | 159 ++++++------ docs/rules/consistent-test-it.md | 13 +- 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 | 7 +- 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 | 12 +- 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 | 12 +- 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 | 7 +- docs/rules/valid-expect.md | 9 +- docs/rules/valid-title.md | 12 +- package.json | 3 +- tools/regenerate-docs.ts | 264 -------------------- tools/rule-notices.ts | 116 --------- yarn.lock | 107 +++++++- 56 files changed, 328 insertions(+), 775 deletions(-) delete mode 100644 tools/regenerate-docs.ts delete mode 100644 tools/rule-notices.ts diff --git a/README.md b/README.md index 6f1b6a3ad..bc83e54c1 100644 --- a/README.md +++ b/README.md @@ -195,70 +195,82 @@ 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).\ +🎨 Enabled 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) | Have control over `test` and `it` usages | | πŸ”§ | | | +| [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) | Prevent 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) | Avoid 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) | Use `.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) | Ensure promises that have expectations in their chain are 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 +281,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 +294,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..714b00a19 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`) -πŸ’Ό 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..e5fe0e369 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 will _warn_ 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..2dee357fe 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 will _warn_ 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..6968a1590 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 will _warn_ 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..68e1f2121 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`) -πŸ’Ό 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..ee18ea401 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 will _warn_ 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..e769476ae 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`) -πŸ’Ό 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..61025331b 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`) -πŸ’Ό 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..8d071b8b4 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`) -πŸ’Ό 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..8e3db76c5 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\"", "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.16.0", "eslint-plugin-eslint-comments": "^3.1.2", "eslint-plugin-eslint-plugin": "^5.0.6", "eslint-plugin-import": "^2.25.1", 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 8a8aa1a32..10c3b5d0f 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2777,6 +2777,16 @@ __metadata: languageName: node linkType: hard +"@typescript-eslint/scope-manager@npm:5.41.0": + version: 5.41.0 + resolution: "@typescript-eslint/scope-manager@npm:5.41.0" + dependencies: + "@typescript-eslint/types": 5.41.0 + "@typescript-eslint/visitor-keys": 5.41.0 + checksum: f588e7e7e953dfa19632b676f1287a7a4f5e9390282b103b3cf46cc28bb597c1229df2489eb687ab9285674076eb2569b821eac9b3110572d70fd230bdc5d703 + languageName: node + linkType: hard + "@typescript-eslint/type-utils@npm:5.40.1": version: 5.40.1 resolution: "@typescript-eslint/type-utils@npm:5.40.1" @@ -2801,6 +2811,13 @@ __metadata: languageName: node linkType: hard +"@typescript-eslint/types@npm:5.41.0": + version: 5.41.0 + resolution: "@typescript-eslint/types@npm:5.41.0" + checksum: d7500bcc67b68032ccf19d983a69efa2750f4d82f5cc027090d2686d4e662b3a7b0b5fa55ed90710eca2528867d39964d76c207ac3c6f734505efbe21dccac7d + languageName: node + linkType: hard + "@typescript-eslint/typescript-estree@npm:5.40.1": version: 5.40.1 resolution: "@typescript-eslint/typescript-estree@npm:5.40.1" @@ -2819,7 +2836,25 @@ __metadata: languageName: node linkType: hard -"@typescript-eslint/utils@npm:5.40.1, @typescript-eslint/utils@npm:^5.10.0": +"@typescript-eslint/typescript-estree@npm:5.41.0": + version: 5.41.0 + resolution: "@typescript-eslint/typescript-estree@npm:5.41.0" + dependencies: + "@typescript-eslint/types": 5.41.0 + "@typescript-eslint/visitor-keys": 5.41.0 + debug: ^4.3.4 + globby: ^11.1.0 + is-glob: ^4.0.3 + semver: ^7.3.7 + tsutils: ^3.21.0 + peerDependenciesMeta: + typescript: + optional: true + checksum: cfb61b5971108807ad4b1e26e71455a0451e8b5ee06e9ae7d2e45caa8e978f0a3bb58bb877eff42a134d3ab21ad23bf138d2b829c407607e3d1fc616f0f87cc9 + languageName: node + linkType: hard + +"@typescript-eslint/utils@npm:5.40.1": version: 5.40.1 resolution: "@typescript-eslint/utils@npm:5.40.1" dependencies: @@ -2837,6 +2872,24 @@ __metadata: languageName: node linkType: hard +"@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: + "@types/json-schema": ^7.0.9 + "@types/semver": ^7.3.12 + "@typescript-eslint/scope-manager": 5.41.0 + "@typescript-eslint/types": 5.41.0 + "@typescript-eslint/typescript-estree": 5.41.0 + eslint-scope: ^5.1.1 + eslint-utils: ^3.0.0 + semver: ^7.3.7 + peerDependencies: + eslint: ^6.0.0 || ^7.0.0 || ^8.0.0 + checksum: 293a0de39639983048b7fe203a4191b97cfc3c868866c1e485ec63c6eab9013002e58f0ac23ec7584f71d28390bf2d6c23ee10d6863ea067567e572cd9d75dae + languageName: node + linkType: hard + "@typescript-eslint/visitor-keys@npm:5.40.1": version: 5.40.1 resolution: "@typescript-eslint/visitor-keys@npm:5.40.1" @@ -2847,6 +2900,16 @@ __metadata: languageName: node linkType: hard +"@typescript-eslint/visitor-keys@npm:5.41.0": + version: 5.41.0 + resolution: "@typescript-eslint/visitor-keys@npm:5.41.0" + dependencies: + "@typescript-eslint/types": 5.41.0 + eslint-visitor-keys: ^3.3.0 + checksum: ff76694170d77c96d6166a1973ca11b4a6de2051e396fc3581534b3d6f574440e0a3af71f0690dfb2368bb5300a412b363c1795ac1ba1f363b1bc115550808cd + languageName: node + linkType: hard + "JSONStream@npm:^1.0.4, JSONStream@npm:^1.3.5": version: 1.3.5 resolution: "JSONStream@npm:1.3.5" @@ -3464,6 +3527,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.30001423 resolution: "caniuse-lite@npm:1.0.30001423" @@ -3812,7 +3882,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 @@ -4500,6 +4570,24 @@ __metadata: languageName: node linkType: hard +"eslint-doc-generator@npm:^0.16.0": + version: 0.16.0 + resolution: "eslint-doc-generator@npm:0.16.0" + dependencies: + "@typescript-eslint/utils": ^5.38.1 + camelcase: ^7.0.0 + commander: ^9.4.0 + markdown-table: ^3.0.2 + type-fest: ^3.0.0 + peerDependencies: + eslint: ">= 7" + prettier: ">= 2" + bin: + eslint-doc-generator: dist/bin/eslint-doc-generator.js + checksum: e531a38e2cc45915b879071071ffffa7d5d8e3ca0d7624e735767aeca7c515f55e805aced8590f876f1bbad900581347c8e9bb7d1d5a8ffc7aaffc7b36013573 + 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" @@ -4608,6 +4696,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.16.0 eslint-plugin-eslint-comments: ^3.1.2 eslint-plugin-eslint-plugin: ^5.0.6 eslint-plugin-import: ^2.25.1 @@ -7258,6 +7347,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" @@ -9850,6 +9946,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"