diff --git a/docs/rules/consistent-test-it.md b/docs/rules/consistent-test-it.md index 94e74e61b..881073c9c 100644 --- a/docs/rules/consistent-test-it.md +++ b/docs/rules/consistent-test-it.md @@ -1,14 +1,22 @@ # 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#shareable-configurations): `all`. + + +πŸ”§ 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: - **it:** `it`, `xit`, `fit`, `it.only`, `it.skip`. - **test:** `test`, `xtest`, `test.only`, `test.skip`. +## Rule Details + This rule gives you control over the usage of these keywords in your codebase. -## Rule Details +## Options This rule can be configured as follows diff --git a/docs/rules/expect-expect.md b/docs/rules/expect-expect.md index 636216067..c9747ea61 100644 --- a/docs/rules/expect-expect.md +++ b/docs/rules/expect-expect.md @@ -1,8 +1,11 @@ # 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#shareable-configurations): `all`. + Ensure that there is at least one `expect` call made in a test. -## Rule details +## Rule Details This rule triggers when there is no call made to `expect` in a test, to prevent users from forgetting to add assertions. diff --git a/docs/rules/max-expects.md b/docs/rules/max-expects.md index 1efa59ae7..d5fa1f752 100644 --- a/docs/rules/max-expects.md +++ b/docs/rules/max-expects.md @@ -1,5 +1,8 @@ # 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#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 the maximum number of assertions is exceeded. diff --git a/docs/rules/max-nested-describe.md b/docs/rules/max-nested-describe.md index 9f10f9828..0fc83553c 100644 --- a/docs/rules/max-nested-describe.md +++ b/docs/rules/max-nested-describe.md @@ -1,5 +1,8 @@ # 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#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 them difficult to read. diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md index d439104de..341151124 100644 --- a/docs/rules/no-alias-methods.md +++ b/docs/rules/no-alias-methods.md @@ -1,5 +1,11 @@ # Disallow alias methods (`no-alias-methods`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + + +πŸ”§ This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line. + > These aliases are going to be removed in the next major version of Jest - see > https://github.com/facebook/jest/issues/13164 for more @@ -9,7 +15,7 @@ Jest documentation is used in the code. This makes it easier to search for all occurrences of the method within code, and it ensures consistency among the method names used. -## Rule details +## Rule Details This rule triggers a warning if the alias name, rather than the canonical name, of a method is used. diff --git a/docs/rules/no-commented-out-tests.md b/docs/rules/no-commented-out-tests.md index b12755c47..adce60fed 100644 --- a/docs/rules/no-commented-out-tests.md +++ b/docs/rules/no-commented-out-tests.md @@ -1,5 +1,8 @@ # Disallow commented out tests (`no-commented-out-tests`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`. + 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 fc46d3ff7..14d5ae6c3 100644 --- a/docs/rules/no-conditional-expect.md +++ b/docs/rules/no-conditional-expect.md @@ -1,5 +1,8 @@ # Prevent calling `expect` conditionally (`no-conditional-expect`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + 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 6850cc47f..073724019 100644 --- a/docs/rules/no-conditional-in-test.md +++ b/docs/rules/no-conditional-in-test.md @@ -1,5 +1,8 @@ # 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#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 executing within a conditional statement will usually be better served by a test diff --git a/docs/rules/no-deprecated-functions.md b/docs/rules/no-deprecated-functions.md index e5c0bca67..8f21028fe 100644 --- a/docs/rules/no-deprecated-functions.md +++ b/docs/rules/no-deprecated-functions.md @@ -1,5 +1,11 @@ # Disallow use of deprecated functions (`no-deprecated-functions`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + + +πŸ”§ This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line. + 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. @@ -11,7 +17,7 @@ This rule requires knowing which version of Jest you're using - see on how that is obtained automatically and how you can explicitly provide a version if needed. -## Rule details +## Rule Details This rule warns about calls to deprecated functions, and provides details on what to replace them with, based on the version of Jest that is installed. diff --git a/docs/rules/no-disabled-tests.md b/docs/rules/no-disabled-tests.md index c6726686a..1e08ff1ac 100644 --- a/docs/rules/no-disabled-tests.md +++ b/docs/rules/no-disabled-tests.md @@ -1,5 +1,8 @@ # Disallow disabled tests (`no-disabled-tests`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`. + 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 tests. Before committing changes we may want to check that all tests are diff --git a/docs/rules/no-done-callback.md b/docs/rules/no-done-callback.md index abae2b017..9c4bfe4c5 100644 --- a/docs/rules/no-done-callback.md +++ b/docs/rules/no-done-callback.md @@ -1,5 +1,11 @@ # 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#shareable-configurations): `all`, `recommended`. + + +πŸ’‘ 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. @@ -49,7 +55,7 @@ test('the data is peanut butter', async () => { }); ``` -## Rule details +## Rule Details This rule checks the function parameter of hooks & tests for use of the `done` argument, suggesting you return a promise instead. diff --git a/docs/rules/no-duplicate-hooks.md b/docs/rules/no-duplicate-hooks.md index 58b69d5dd..78397e354 100644 --- a/docs/rules/no-duplicate-hooks.md +++ b/docs/rules/no-duplicate-hooks.md @@ -1,5 +1,8 @@ # 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#shareable-configurations): `all`. + A `describe` block should not contain duplicate hooks. ## Rule Details diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md index f8379b72e..b3b29d2d4 100644 --- a/docs/rules/no-export.md +++ b/docs/rules/no-export.md @@ -1,5 +1,8 @@ # 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#shareable-configurations): `all`, `recommended`. + Prevents using `exports` if a file has one or more tests in it. ## Rule Details diff --git a/docs/rules/no-focused-tests.md b/docs/rules/no-focused-tests.md index 22f00bd99..456c09596 100644 --- a/docs/rules/no-focused-tests.md +++ b/docs/rules/no-focused-tests.md @@ -1,5 +1,11 @@ # Disallow focused tests (`no-focused-tests`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + + +πŸ’‘ 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 prepending `f` to a test-suite or a test-case. This feature is really helpful to debug a failing test, so you don’t have to execute all of your tests. After you diff --git a/docs/rules/no-hooks.md b/docs/rules/no-hooks.md index 708d3550d..11f040158 100644 --- a/docs/rules/no-hooks.md +++ b/docs/rules/no-hooks.md @@ -1,5 +1,8 @@ # Disallow setup and teardown hooks (`no-hooks`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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 shared state between tests. diff --git a/docs/rules/no-identical-title.md b/docs/rules/no-identical-title.md index d56e41e90..ee9b88e41 100644 --- a/docs/rules/no-identical-title.md +++ b/docs/rules/no-identical-title.md @@ -1,5 +1,8 @@ # Disallow identical titles (`no-identical-title`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + 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 same test suite fails, it is harder to know which one failed and thus harder to diff --git a/docs/rules/no-if.md b/docs/rules/no-if.md index e44015e0b..b03a066e0 100644 --- a/docs/rules/no-if.md +++ b/docs/rules/no-if.md @@ -1,6 +1,6 @@ # Disallow conditional logic (`no-if`) -## Deprecated +❌ This rule is deprecated. This rule has been deprecated in favor of [`no-conditional-in-test`](no-conditional-in-test.md). diff --git a/docs/rules/no-interpolation-in-snapshots.md b/docs/rules/no-interpolation-in-snapshots.md index 0ac13540e..128e07258 100644 --- a/docs/rules/no-interpolation-in-snapshots.md +++ b/docs/rules/no-interpolation-in-snapshots.md @@ -1,5 +1,8 @@ # 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#shareable-configurations): `all`, `recommended`. + Prevents the use of string interpolations in snapshots. ## Rule Details diff --git a/docs/rules/no-jasmine-globals.md b/docs/rules/no-jasmine-globals.md index 8fbb47356..299e11e3c 100644 --- a/docs/rules/no-jasmine-globals.md +++ b/docs/rules/no-jasmine-globals.md @@ -1,5 +1,11 @@ # Disallow Jasmine globals (`no-jasmine-globals`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + + +πŸ”§ 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` 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 environment. Most functionality offered by Jasmine has been ported to Jest, and @@ -7,7 +13,7 @@ the Jasmine globals will stop working in the future. Developers should therefore migrate to Jest's documented API instead of relying on the undocumented Jasmine API. -### Rule details +## Rule Details This rule reports on any usage of Jasmine globals, which is not ported to Jest, and suggests alternatives from Jest's own API. diff --git a/docs/rules/no-large-snapshots.md b/docs/rules/no-large-snapshots.md index 8572fda98..0c2416ef8 100644 --- a/docs/rules/no-large-snapshots.md +++ b/docs/rules/no-large-snapshots.md @@ -1,5 +1,8 @@ # disallow large snapshots (`no-large-snapshots`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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 size in order to be more manageable and reviewable. A stored snapshot is only as diff --git a/docs/rules/no-mocks-import.md b/docs/rules/no-mocks-import.md index 429ed3241..483ee7851 100644 --- a/docs/rules/no-mocks-import.md +++ b/docs/rules/no-mocks-import.md @@ -1,5 +1,8 @@ # Disallow manually importing from `__mocks__` (`no-mocks-import`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + 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 confusion, because you will have multiple instances of the mocked module: @@ -14,7 +17,7 @@ test('x', () => { }); ``` -### Rule details +## Rule Details This rule reports imports from a path containing a `__mocks__` component. diff --git a/docs/rules/no-restricted-matchers.md b/docs/rules/no-restricted-matchers.md index 77138b558..844d308fe 100644 --- a/docs/rules/no-restricted-matchers.md +++ b/docs/rules/no-restricted-matchers.md @@ -1,9 +1,16 @@ # Disallow specific matchers & modifiers (`no-restricted-matchers`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`. + +You may want to ban specific matchers & modifiers from being used. + +## Rule Details + This rule bans specific matchers & modifiers from being used, and can suggest alternatives. -## Rule Details +## Options Bans are expressed in the form of a map, with the value being either a string message to be shown, or `null` if the default rule message should be used. diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md index efdd4f9cf..36cbf5221 100644 --- a/docs/rules/no-standalone-expect.md +++ b/docs/rules/no-standalone-expect.md @@ -1,5 +1,8 @@ # 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#shareable-configurations): `all`, `recommended`. + 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 trigger this rule. diff --git a/docs/rules/no-test-prefixes.md b/docs/rules/no-test-prefixes.md index 21b0ba059..65405f8b7 100644 --- a/docs/rules/no-test-prefixes.md +++ b/docs/rules/no-test-prefixes.md @@ -1,5 +1,11 @@ # 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#shareable-configurations): `all`, `recommended`. + + +πŸ”§ 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 focused and skipped tests, with multiple permutations for each: @@ -9,7 +15,7 @@ multiple permutations for each: This rule enforces usages from the **only & skip** list. -## Rule details +## Rule Details This rule triggers a warning if you use one of the keywords from the **'f' & 'x'** list to focus/skip a test. diff --git a/docs/rules/no-test-return-statement.md b/docs/rules/no-test-return-statement.md index 6577062cc..e3f7a3694 100644 --- a/docs/rules/no-test-return-statement.md +++ b/docs/rules/no-test-return-statement.md @@ -1,11 +1,14 @@ # 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#shareable-configurations): `all`. + Tests in Jest should be void and not return values. If you are returning Promises then you should update the test to use `async/await`. -## Rule details +## Rule Details This rule triggers a warning if you use a return statement inside a test body. diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md index 09bf7360c..f38eda7e7 100644 --- a/docs/rules/prefer-called-with.md +++ b/docs/rules/prefer-called-with.md @@ -1,5 +1,8 @@ # Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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 is stronger when arguments are also validated using the `toBeCalledWith()` @@ -9,7 +12,7 @@ matcher. When some arguments are difficult to check, using generic match like This rule warns if the form without argument checking is used, except for `.not` enforcing a function has never been called. -## Rule details +## Rule Details The following patterns are warnings: diff --git a/docs/rules/prefer-comparison-matcher.md b/docs/rules/prefer-comparison-matcher.md index 33c740535..3757d8340 100644 --- a/docs/rules/prefer-comparison-matcher.md +++ b/docs/rules/prefer-comparison-matcher.md @@ -1,9 +1,15 @@ # 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#shareable-configurations): `all`. + + +πŸ”§ 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. -## Rule details +## Rule Details This rule checks for comparisons in tests that could be replaced with one of the following built-in comparison matchers: diff --git a/docs/rules/prefer-each.md b/docs/rules/prefer-each.md index cb995ba00..4d42b9060 100644 --- a/docs/rules/prefer-each.md +++ b/docs/rules/prefer-each.md @@ -1,8 +1,11 @@ # 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#shareable-configurations): `all`. + Reports where you might be able to use `.each` instead of native loops. -## Rule details +## Rule Details This rule triggers a warning if you use test case functions like `describe`, `test`, and `it`, in a native loop - generally you should be able to use `.each` diff --git a/docs/rules/prefer-equality-matcher.md b/docs/rules/prefer-equality-matcher.md index d27eb433a..938ad3f8e 100644 --- a/docs/rules/prefer-equality-matcher.md +++ b/docs/rules/prefer-equality-matcher.md @@ -1,9 +1,15 @@ # 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#shareable-configurations): `all`. + + +πŸ’‘ This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions). + Jest has built-in matchers for expecting equality, which allow for more readable tests and error messages if an expectation fails. -## Rule details +## Rule Details This rule checks for _strict_ equality checks (`===` & `!==`) in tests that could be replaced with one of the following built-in equality matchers: diff --git a/docs/rules/prefer-expect-assertions.md b/docs/rules/prefer-expect-assertions.md index 512797217..2638368c1 100644 --- a/docs/rules/prefer-expect-assertions.md +++ b/docs/rules/prefer-expect-assertions.md @@ -1,9 +1,15 @@ # 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#shareable-configurations): `all`. + + +πŸ’‘ This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions). + Ensure every test to have either `expect.assertions()` OR `expect.hasAssertions()` as its first expression. -## Rule details +## Rule Details This rule triggers a warning if, diff --git a/docs/rules/prefer-expect-resolves.md b/docs/rules/prefer-expect-resolves.md index baba945b7..f5f633f30 100644 --- a/docs/rules/prefer-expect-resolves.md +++ b/docs/rules/prefer-expect-resolves.md @@ -1,5 +1,11 @@ # 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#shareable-configurations): `all`. + + +πŸ”§ 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: @@ -15,7 +21,7 @@ behaviour and output from `jest`. Additionally, favoring the first style ensures consistency with its `rejects` counterpart, as there is no way of "awaiting" a rejection. -## Rule details +## Rule Details This rule triggers a warning if an `await` is done within an `expect`, and recommends using `resolves` instead. diff --git a/docs/rules/prefer-hooks-in-order.md b/docs/rules/prefer-hooks-in-order.md index f83ff9238..e3aa81805 100644 --- a/docs/rules/prefer-hooks-in-order.md +++ b/docs/rules/prefer-hooks-in-order.md @@ -1,5 +1,8 @@ # 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#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 75e4413c7..03956a57a 100644 --- a/docs/rules/prefer-hooks-on-top.md +++ b/docs/rules/prefer-hooks-on-top.md @@ -1,5 +1,8 @@ # 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#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 cases. diff --git a/docs/rules/prefer-lowercase-title.md b/docs/rules/prefer-lowercase-title.md index 5099fcdfe..fb4c7a77d 100644 --- a/docs/rules/prefer-lowercase-title.md +++ b/docs/rules/prefer-lowercase-title.md @@ -1,6 +1,12 @@ # Enforce lowercase test names (`prefer-lowercase-title`) -## Rule details + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`. + + +πŸ”§ 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 Enforce `it`, `test` and `describe` to have descriptions that begin with a lowercase letter. This provides more readable test failures. This rule is not diff --git a/docs/rules/prefer-mock-promise-shorthand.md b/docs/rules/prefer-mock-promise-shorthand.md index f7dda79a3..f1ff9fe56 100644 --- a/docs/rules/prefer-mock-promise-shorthand.md +++ b/docs/rules/prefer-mock-promise-shorthand.md @@ -1,5 +1,11 @@ # 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#shareable-configurations): `all`. + + +πŸ”§ 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 4c4dbc515..fc4294721 100644 --- a/docs/rules/prefer-snapshot-hint.md +++ b/docs/rules/prefer-snapshot-hint.md @@ -1,5 +1,8 @@ # 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#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 snapshot content that will be included in the snapshots name by Jest. @@ -8,7 +11,7 @@ This makes it easier for reviewers to verify the snapshots during review, and for anyone to know whether an outdated snapshot is the correct behavior before updating. -## Rule details +## Rule Details This rule looks for any use of an external snapshot matcher (e.g. `toMatchSnapshot` and `toThrowErrorMatchingSnapshot`) and checks if they include diff --git a/docs/rules/prefer-spy-on.md b/docs/rules/prefer-spy-on.md index 25877d629..f52eb5712 100644 --- a/docs/rules/prefer-spy-on.md +++ b/docs/rules/prefer-spy-on.md @@ -1,5 +1,11 @@ # Suggest using `jest.spyOn()` (`prefer-spy-on`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`. + + +πŸ”§ 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 keeps track of changes, and they can be restored with `jest.restoreAllMocks()`, @@ -19,7 +25,7 @@ jest.spyOn(Date, 'now').mockImplementation(() => 10); // Will always return 10 jest.spyOn(Date, 'now').mockReturnValue(10); // Will always return 10 ``` -## Rule details +## Rule Details This rule triggers a warning if an object's property is overwritten with a jest mock. diff --git a/docs/rules/prefer-strict-equal.md b/docs/rules/prefer-strict-equal.md index 81a2b5f92..fe62ef3b4 100644 --- a/docs/rules/prefer-strict-equal.md +++ b/docs/rules/prefer-strict-equal.md @@ -1,11 +1,17 @@ # Suggest using `toStrictEqual()` (`prefer-strict-equal`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`. + + +πŸ’‘ This rule is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions). + `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 have identical values but also to have identical keys. A stricter equality will catch cases where two objects do not have identical keys. -## Rule details +## Rule Details This rule triggers a warning if `toEqual()` is used to assert equality. diff --git a/docs/rules/prefer-to-be.md b/docs/rules/prefer-to-be.md index 8611b42cf..130b0c90d 100644 --- a/docs/rules/prefer-to-be.md +++ b/docs/rules/prefer-to-be.md @@ -1,5 +1,11 @@ # 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#shareable-configurations): `all`, `style`. + + +πŸ”§ 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 asserting against primitive literals such as numbers and strings, the equality matchers all operate the same, but read slightly differently in code. @@ -8,7 +14,7 @@ the most grammatically natural sentence. For `null`, `undefined`, and `NaN` this rule recommends using their specific `toBe` matchers, as they give better error messages as well. -## Rule details +## Rule Details This rule triggers a warning if `toEqual()` or `toStrictEqual()` are used to assert a primitive literal value such as numbers, strings, and booleans. diff --git a/docs/rules/prefer-to-contain.md b/docs/rules/prefer-to-contain.md index b1144bc26..899e719f6 100644 --- a/docs/rules/prefer-to-contain.md +++ b/docs/rules/prefer-to-contain.md @@ -1,9 +1,15 @@ # Suggest using `toContain()` (`prefer-to-contain`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`. + + +πŸ”§ This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line. + In order to have a better failure message, `toContain()` should be used upon asserting expectations on an array containing an object. -## Rule details +## Rule Details This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is used to assert object inclusion in an array diff --git a/docs/rules/prefer-to-have-length.md b/docs/rules/prefer-to-have-length.md index d44e9e079..625170963 100644 --- a/docs/rules/prefer-to-have-length.md +++ b/docs/rules/prefer-to-have-length.md @@ -1,9 +1,15 @@ # Suggest using `toHaveLength()` (`prefer-to-have-length`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `style`. + + +πŸ”§ This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line. + In order to have a better failure message, `toHaveLength()` should be used upon asserting expectations on objects length property. -## Rule details +## Rule Details This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is used to assert objects length property. diff --git a/docs/rules/prefer-todo.md b/docs/rules/prefer-todo.md index c294cbdbf..7b22a590b 100644 --- a/docs/rules/prefer-todo.md +++ b/docs/rules/prefer-todo.md @@ -1,9 +1,15 @@ # Suggest using `test.todo` (`prefer-todo`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`. + + +πŸ”§ 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. -## Rule details +## Rule Details This rule triggers a warning if empty test cases are used without 'test.todo'. diff --git a/docs/rules/require-hook.md b/docs/rules/require-hook.md index 41b83bc7f..29563d3b4 100644 --- a/docs/rules/require-hook.md +++ b/docs/rules/require-hook.md @@ -1,5 +1,8 @@ # 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#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 run. Jest provides helper functions to handle this. @@ -12,7 +15,7 @@ executes any of the actual tests, it's important to ensure setup and teardown work is done inside `before*` and `after*` handlers respectively, rather than inside the `describe` blocks. -## Rule details +## Rule Details This rule flags any expression that is either at the toplevel of a test file or directly within the body of a `describe`, _except_ for the following: diff --git a/docs/rules/require-to-throw-message.md b/docs/rules/require-to-throw-message.md index 4eea732f2..c9f6c5a17 100644 --- a/docs/rules/require-to-throw-message.md +++ b/docs/rules/require-to-throw-message.md @@ -1,11 +1,14 @@ # 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#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 no message is defined, then the test will pass for any thrown error. Requiring a message ensures that the intended error is thrown. -## Rule details +## Rule Details This rule triggers a warning if `toThrow()` or `toThrowError()` is used without an error message. diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md index 389b8dbdb..146de24da 100644 --- a/docs/rules/require-top-level-describe.md +++ b/docs/rules/require-top-level-describe.md @@ -1,5 +1,8 @@ # 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#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 files. This rule makes sure you provide at least a top-level `describe` block in @@ -47,6 +50,8 @@ describe('test suite', () => { }); ``` +## Options + You can also enforce a limit on the number of describes allowed at the top-level using the `maxNumberOfTopLevelDescribes` option: diff --git a/docs/rules/unbound-method.md b/docs/rules/unbound-method.md index d4bef0920..f8b25a4c7 100644 --- a/docs/rules/unbound-method.md +++ b/docs/rules/unbound-method.md @@ -1,5 +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#shareable-configurations): `all`. + ## Rule Details This rule extends the base [`@typescript-eslint/unbound-method`][original-rule] diff --git a/docs/rules/valid-describe-callback.md b/docs/rules/valid-describe-callback.md index 32ef3a18e..7993660e5 100644 --- a/docs/rules/valid-describe-callback.md +++ b/docs/rules/valid-describe-callback.md @@ -1,5 +1,8 @@ # Enforce valid `describe()` callback (`valid-describe-callback`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + 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 03c3fb6d0..ea1b442c3 100644 --- a/docs/rules/valid-expect-in-promise.md +++ b/docs/rules/valid-expect-in-promise.md @@ -1,8 +1,11 @@ # 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#shareable-configurations): `all`, `recommended`. + Ensure promises that include expectations are returned or awaited. -## Rule details +## Rule Details This rule flags any promises within the body of a test that include expectations that have either not been returned or awaited. diff --git a/docs/rules/valid-expect.md b/docs/rules/valid-expect.md index 39f0518b4..ae3b9fc17 100644 --- a/docs/rules/valid-expect.md +++ b/docs/rules/valid-expect.md @@ -1,9 +1,12 @@ # Enforce valid `expect()` usage (`valid-expect`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + Ensure `expect()` is called with a single argument and there is an actual expectation made. -## Rule details +## Rule Details This rule triggers a warning if `expect()` is called with more than one argument or without arguments. It would also issue a warning if there is nothing called diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md index ab1ae76ad..261b5b6b8 100644 --- a/docs/rules/valid-title.md +++ b/docs/rules/valid-title.md @@ -1,5 +1,11 @@ # Enforce valid titles (`valid-title`) + +πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#shareable-configurations): `all`, `recommended`. + + +πŸ”§ This rule is automatically fixable using the `--fix` [option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) on the command line. + Checks that the title of Jest blocks are valid by ensuring that titles are: - not empty, diff --git a/src/__tests__/rules.test.ts b/src/__tests__/rules.test.ts index a8c66cc18..d53697b0c 100644 --- a/src/__tests__/rules.test.ts +++ b/src/__tests__/rules.test.ts @@ -1,5 +1,6 @@ -import { existsSync } from 'fs'; -import { resolve } from 'path'; +import { existsSync, readFileSync } from 'fs'; +import { EOL } from 'os'; +import { join, resolve } from 'path'; import plugin from '../'; const numberOfRules = 50; @@ -76,4 +77,136 @@ describe('rules', () => { expect(() => require(`../rules/${ruleName}`)).not.toThrow(); }); }); + + describe('rule documentation files have the correct content', () => { + enum MESSAGE_TYPE { + CONFIGS = 1, + DEPRECATED = 2, + FIXABLE = 3, + HAS_SUGGESTIONS = 4, + } + const MESSAGES = { + [MESSAGE_TYPE.CONFIGS]: + 'πŸ’Ό This rule is enabled in the following [configs](https://github.com/jest-community/eslint-plugin-jest#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 is manually fixable by editor [suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).', + }; + + function getConfigsForRule(ruleName: keyof typeof plugin.rules) { + const { configs } = plugin; + const configNames: Array = []; + let configName: keyof typeof configs; + + for (configName in configs) { + const config = configs[configName]; + // eslint-disable-next-line @typescript-eslint/ban-ts-comment -- we don't have a static type for rule names + // @ts-ignore + const value = config.rules[`jest/${ruleName}`]; + const isEnabled = [2, 'error'].includes(value); + + if (isEnabled) { + configNames.push(configName); + } + } + + return configNames.sort(); + } + + function configNamesToList(configNames: string[]) { + return `\`${configNames.join('`, `')}\``; + } + + it.each(ruleNames)('%s', ruleName => { + const rule = plugin.rules[ruleName]; + const documentPath = join('docs', 'rules', `${ruleName}.md`); + const documentContents = readFileSync(documentPath, 'utf8'); + const documentLines = documentContents.split(EOL); + + // Check title. + const expectedTitle = `# ${rule.meta.docs.description} (\`${ruleName}\`)`; + + expect(documentLines[0]).toStrictEqual(expectedTitle); // Includes the rule description and name in title. + + // Decide which notices should be shown at the top of the doc. + const expectedNotices: MESSAGE_TYPE[] = []; + const unexpectedNotices: MESSAGE_TYPE[] = []; + + if (rule.meta.deprecated) { + expectedNotices.push(MESSAGE_TYPE.DEPRECATED); + unexpectedNotices.push(MESSAGE_TYPE.CONFIGS); + } else { + unexpectedNotices.push(MESSAGE_TYPE.DEPRECATED); + expectedNotices.push(MESSAGE_TYPE.CONFIGS); + } + if (rule.meta.fixable) { + expectedNotices.push(MESSAGE_TYPE.FIXABLE); + } else { + unexpectedNotices.push(MESSAGE_TYPE.FIXABLE); + } + if (rule.meta.hasSuggestions) { + expectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS); + } else { + unexpectedNotices.push(MESSAGE_TYPE.HAS_SUGGESTIONS); + } + + // Ensure that expected notices are present in the correct order. + let currentLineNumber = 1; + + expectedNotices.forEach(expectedNotice => { + expect(documentLines[currentLineNumber]).toStrictEqual(''); // Blank line first. + + if ( + documentLines[currentLineNumber + 1] === '' + ) { + // Ignore any Prettier ignore comment that may be needed so that the notice doesn't get split onto multiple lines. + currentLineNumber++; + } + + if (expectedNotice === MESSAGE_TYPE.CONFIGS) { + // Check that the rule has a notice with a list of its configs. + const configsEnabled = getConfigsForRule(ruleName); + const expectedMessage = `${ + MESSAGES[MESSAGE_TYPE.CONFIGS] + } ${configNamesToList(configsEnabled)}.`; + + expect(documentLines[currentLineNumber + 1]).toStrictEqual( + expectedMessage, + ); + } else { + // For other notice types, just check the whole line. + expect(documentLines[currentLineNumber + 1]).toStrictEqual( + MESSAGES[expectedNotice], + ); + } + currentLineNumber += 2; + }); + + // Ensure that unexpected notices are not present. + unexpectedNotices.forEach(unexpectedNotice => { + expect( + documentContents.includes(MESSAGES[unexpectedNotice]), + ).toStrictEqual(false); + }); + + // Check for Rule Details section. + expect(documentContents).toContain('## Rule Details'); + + // Check if the rule has configuration options. + if ( + (Array.isArray(rule.meta.schema) && rule.meta.schema.length > 0) || + (typeof rule.meta.schema === 'object' && + Object.keys(rule.meta.schema).length > 0) + ) { + // Should have an options section header: + expect(documentContents).toContain('## Options'); + } else { + // Should NOT have any options section header: + expect(documentContents.includes('## Options')).toStrictEqual(false); + expect(documentContents.includes('## Config')).toStrictEqual(false); + } + }); + }); });