eslint-plugin-jest 26.8.7 → 27.1.6

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

@@ -1,4 +1,6 @@
-# disallow large snapshots (`no-large-snapshots`)
+# Disallow large snapshots (`no-large-snapshots`)
+
+<!-- end auto-generated rule header -->
 
 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
@@ -22,7 +24,7 @@ module.exports = {
 };
 ```
 
-## Rule Details
+## Rule details
 
 This rule looks at all Jest inline and external snapshots (files with `.snap`
 extension) and validates that each stored snapshot within those files does not

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

@@ -1,5 +1,10 @@
 # Disallow manually importing from `__mocks__` (`no-mocks-import`)
 
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
+
+<!-- end auto-generated rule header -->
+
 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 +19,7 @@ test('x', () => {
 });
 ```
 
-### Rule details
+## Rule details
 
 This rule reports imports from a path containing a `__mocks__` component.
 

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

@@ -0,0 +1,51 @@
+# Disallow specific `jest.` methods (`no-restricted-jest-methods`)
+
+<!-- end auto-generated rule header -->
+
+You may wish to restrict the use of specific `jest` methods.
+
+## Rule details
+
+This rule checks for the usage of specific methods on the `jest` object, which
+can be used to disallow certain patterns such as spies and mocks.
+
+## Options
+
+Restrictions are expressed in the form of a map, with the value being either a
+string message to be shown, or `null` if a generic default message should be
+used.
+
+By default, this map is empty, meaning no `jest` methods are banned.
+
+For example:
+
+```json
+{
+  "jest/no-restricted-jest-methods": [
+    "error",
+    {
+      "advanceTimersByTime": null,
+      "spyOn": "Don't use spies"
+    }
+  ]
+}
+```
+
+Examples of **incorrect** code for this rule with the above configuration
+
+```js
+jest.useFakeTimers();
+it('calls the callback after 1 second via advanceTimersByTime', () => {
+  // ...
+
+  jest.advanceTimersByTime(1000);
+
+  // ...
+});
+
+test('plays video', () => {
+  const spy = jest.spyOn(video, 'play');
+
+  // ...
+});
+```

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

@@ -1,15 +1,22 @@
 # Disallow specific matchers & modifiers (`no-restricted-matchers`)
 
+<!-- end auto-generated rule header -->
+
+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.
 
-Both matchers, modifiers, and chains of the two are checked, allowing for
-specific variations of a matcher to be banned if desired.
+Bans are checked against the start of the `expect` chain - this means that to
+ban a specific matcher entirely you must specify all six permutations, but
+allows you to ban modifiers as well.
 
 By default, this map is empty, meaning no matchers or modifiers are banned.
 
@@ -22,7 +29,12 @@ For example:
     {
       "toBeFalsy": null,
       "resolves": "Use `expect(await promise)` instead.",
-      "not.toHaveBeenCalledWith": null
+      "toHaveBeenCalledWith": null,
+      "not.toHaveBeenCalledWith": null,
+      "resolves.toHaveBeenCalledWith": null,
+      "rejects.toHaveBeenCalledWith": null,
+      "resolves.not.toHaveBeenCalledWith": null,
+      "rejects.not.toHaveBeenCalledWith": null
     }
   ]
 }
@@ -32,15 +44,18 @@ Examples of **incorrect** code for this rule with the above configuration
 
 ```js
 it('is false', () => {
+  // if this has a modifer (i.e. `not.toBeFalsy`), it would be considered fine
   expect(a).toBeFalsy();
 });
 
 it('resolves', async () => {
+  // all uses of this modifier are disallowed, regardless of matcher
   await expect(myPromise()).resolves.toBe(true);
 });
 
 describe('when an error happens', () => {
   it('does not upload the file', async () => {
+    // all uses of this matcher are disallowed
     expect(uploadFileMock).not.toHaveBeenCalledWith('file.name');
   });
 });

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

@@ -1,10 +1,15 @@
 # Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`)
 
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
+
+<!-- end auto-generated rule header -->
+
 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.
 
-## Rule Details
+## Rule details
 
 This rule aims to eliminate `expect` statements that will not be executed. An
 `expect` inside of a `describe` block but outside of a `test` or `it` block or

package/docs/rules/no-test-prefixes.md

@@ -1,4 +1,12 @@
-# Use `.only` and `.skip` over `f` and `x` (`no-test-prefixes`)
+# Require using `.only` and `.skip` over `f` and `x` (`no-test-prefixes`)
+
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
+
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
 
 Jest allows you to choose how you want to define focused and skipped tests, with
 multiple permutations for each:

package/docs/rules/no-test-return-statement.md

@@ -1,5 +1,7 @@
 # Disallow explicitly returning from tests (`no-test-return-statement`)
 
+<!-- end auto-generated rule header -->
+
 Tests in Jest should be void and not return values.
 
 If you are returning Promises then you should update the test to use

package/docs/rules/prefer-called-with.md

@@ -1,5 +1,7 @@
 # Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`)
 
+<!-- end auto-generated rule header -->
+
 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()`

package/docs/rules/prefer-comparison-matcher.md

@@ -1,5 +1,10 @@
 # Suggest using the built-in comparison matchers (`prefer-comparison-matcher`)
 
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 Jest has a number of built-in matchers for comparing numbers, which allow for
 more readable tests and error messages if an expectation fails.
 

package/docs/rules/prefer-each.md

@@ -0,0 +1,56 @@
+# Prefer using `.each` rather than manual loops (`prefer-each`)
+
+<!-- end auto-generated rule header -->
+
+Reports where you might be able to use `.each` instead of native loops.
+
+## 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`
+instead which gives better output and makes it easier to run specific cases.
+
+Examples of **incorrect** code for this rule:
+
+```js
+for (const number of getNumbers()) {
+  it('is greater than five', function () {
+    expect(number).toBeGreaterThan(5);
+  });
+}
+
+for (const [input, expected] of data) {
+  beforeEach(() => setupSomething(input));
+
+  test(`results in ${expected}`, () => {
+    expect(doSomething()).toBe(expected);
+  });
+}
+```
+
+Examples of **correct** code for this rule:
+
+```js
+it.each(getNumbers())(
+  'only returns numbers that are greater than seven',
+  number => {
+    expect(number).toBeGreaterThan(7);
+  },
+);
+
+describe.each(data)('when input is %s', ([input, expected]) => {
+  beforeEach(() => setupSomething(input));
+
+  test(`results in ${expected}`, () => {
+    expect(doSomething()).toBe(expected);
+  });
+});
+
+// we don't warn on loops _in_ test functions because those typically involve
+// complex setup that is better done in the test function itself
+it('returns numbers that are greater than five', () => {
+  for (const number of getNumbers()) {
+    expect(number).toBeGreaterThan(5);
+  }
+});
+```

package/docs/rules/prefer-equality-matcher.md

@@ -1,5 +1,10 @@
 # Suggest using the built-in equality matchers (`prefer-equality-matcher`)
 
+💡 This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
+<!-- end auto-generated rule header -->
+
 Jest has built-in matchers for expecting equality, which allow for more readable
 tests and error messages if an expectation fails.
 

package/docs/rules/prefer-expect-assertions.md

@@ -1,5 +1,10 @@
 # Suggest using `expect.assertions()` OR `expect.hasAssertions()` (`prefer-expect-assertions`)
 
+💡 This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
+<!-- end auto-generated rule header -->
+
 Ensure every test to have either `expect.assertions(<number of assertions>)` OR
 `expect.hasAssertions()` as its first expression.
 
@@ -27,8 +32,6 @@ test('my test', () => {
 });
 ```
 
-### Default configuration
-
 The following patterns are considered warnings:
 
 ```js

package/docs/rules/prefer-expect-resolves.md

@@ -1,5 +1,10 @@
 # Prefer `await expect(...).resolves` over `expect(await ...)` syntax (`prefer-expect-resolves`)
 
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 When working with promises, there are two primary ways you can test the resolved
 value:
 
@@ -48,6 +53,8 @@ it('is true', async () => {
 });
 
 it('errors', async () => {
-  await expect(Promise.rejects('oh noes!')).rejects.toThrow('oh noes!');
+  await expect(Promise.reject(new Error('oh noes!'))).rejects.toThrowError(
+    'oh noes!',
+  );
 });
 ```

package/docs/rules/prefer-hooks-in-order.md

@@ -1,5 +1,7 @@
 # Prefer having hooks in a consistent order (`prefer-hooks-in-order`)
 
+<!-- end auto-generated rule header -->
+
 While hooks can be setup in any order, they're always called by `jest` in this
 specific order:
 
@@ -11,7 +13,7 @@ specific order:
 This rule aims to make that more obvious by enforcing grouped hooks be setup in
 that order within tests.
 
-## Rule Details
+## Rule details
 
 Examples of **incorrect** code for this rule
 

package/docs/rules/prefer-hooks-on-top.md

@@ -1,12 +1,14 @@
 # Suggest having hooks before any test cases (`prefer-hooks-on-top`)
 
+<!-- end auto-generated rule header -->
+
 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.
 
 This rule helps to ensure that hooks are always defined before test cases.
 
-## Rule Details
+## Rule details
 
 Examples of **incorrect** code for this rule
 

package/docs/rules/prefer-lowercase-title.md

@@ -1,5 +1,10 @@
 # Enforce lowercase test names (`prefer-lowercase-title`)
 
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 ## Rule details
 
 Enforce `it`, `test` and `describe` to have descriptions that begin with a

package/docs/rules/prefer-mock-promise-shorthand.md

@@ -1,11 +1,16 @@
 # Prefer mock resolved/rejected shorthands for promises (`prefer-mock-promise-shorthand`)
 
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 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.
 
 These methods should be preferred when possible.
 
-## Rule Details
+## Rule details
 
 The following patterns are warnings:
 

package/docs/rules/prefer-snapshot-hint.md

@@ -1,5 +1,7 @@
 # Prefer including a hint with external snapshots (`prefer-snapshot-hint`)
 
+<!-- end auto-generated rule header -->
+
 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.

package/docs/rules/prefer-spy-on.md

@@ -1,5 +1,10 @@
 # Suggest using `jest.spyOn()` (`prefer-spy-on`)
 
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 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()`,
@@ -24,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

package/docs/rules/prefer-strict-equal.md

@@ -1,5 +1,10 @@
 # Suggest using `toStrictEqual()` (`prefer-strict-equal`)
 
+💡 This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/developer-guide/working-with-rules#providing-suggestions).
+
+<!-- end auto-generated rule header -->
+
 `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
@@ -9,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

package/docs/rules/prefer-to-be.md

@@ -1,5 +1,13 @@
 # Suggest using `toBe()` for primitive literals (`prefer-to-be`)
 
+💼 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 by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 When asserting against primitive literals such as numbers and strings, the
 equality matchers all operate the same, but read slightly differently in code.
 

package/docs/rules/prefer-to-contain.md

@@ -1,5 +1,13 @@
 # Suggest using `toContain()` (`prefer-to-contain`)
 
+💼 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 by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 In order to have a better failure message, `toContain()` should be used upon
 asserting expectations on an array containing an object.
 
@@ -20,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

package/docs/rules/prefer-to-have-length.md

@@ -1,5 +1,13 @@
 # Suggest using `toHaveLength()` (`prefer-to-have-length`)
 
+💼 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 by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 In order to have a better failure message, `toHaveLength()` should be used upon
 asserting expectations on objects length property.
 
@@ -14,8 +22,6 @@ expect(files.length).toBe(1);
 
 This rule is enabled by default.
 
-### Default configuration
-
 The following patterns are considered warnings:
 
 ```js

package/docs/rules/prefer-todo.md

@@ -1,5 +1,10 @@
 # Suggest using `test.todo` (`prefer-todo`)
 
+🔧 This rule is automatically fixable by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 When test cases are empty then it is better to mark them as `test.todo` as it
 will be highlighted in the summary output.
 
@@ -11,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

package/docs/rules/require-hook.md

@@ -1,5 +1,7 @@
 # Require setup and teardown code to be within a hook (`require-hook`)
 
+<!-- end auto-generated rule header -->
+
 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.

package/docs/rules/require-to-throw-message.md

@@ -1,5 +1,7 @@
 # Require a message for `toThrow()` (`require-to-throw-message`)
 
+<!-- end auto-generated rule header -->
+
 `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
@@ -10,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

package/docs/rules/require-top-level-describe.md

@@ -1,11 +1,13 @@
 # Require test cases and hooks to be inside a `describe` block (`require-top-level-describe`)
 
+<!-- end auto-generated rule header -->
+
 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
 your test file.
 
-## Rule Details
+## Rule details
 
 This rule triggers a warning if a test case (`test` and `it`) or a hook
 (`beforeAll`, `beforeEach`, `afterEach`, `afterAll`) is not located in a
@@ -47,6 +49,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:
 

package/docs/rules/unbound-method.md

@@ -1,6 +1,10 @@
 # Enforce unbound methods are called with their expected scope (`unbound-method`)
 
-## Rule Details
+💭 This rule requires type information.
+
+<!-- end auto-generated rule header -->
+
+## Rule details
 
 This rule extends the base [`@typescript-eslint/unbound-method`][original-rule]
 rule, meaning you must depend on `@typescript-eslint/eslint-plugin` for it to
@@ -46,7 +50,8 @@ which should be applied to the rest of your codebase.
 
 ## Options
 
-See [`@typescript-eslint/unbound-method`][original-rule] options.
+See [`@typescript-eslint/unbound-method`][original-rule] options (e.g.
+`ignoreStatic`).
 
 <sup>Taken with ❤️ [from `@typescript-eslint` core][original-rule]</sup>
 

package/docs/rules/valid-describe-callback.md

@@ -1,9 +1,14 @@
 # Enforce valid `describe()` callback (`valid-describe-callback`)
 
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
+
+<!-- end auto-generated rule header -->
+
 Using an improper `describe()` callback function can lead to unexpected test
 errors.
 
-## Rule Details
+## Rule details
 
 This rule validates that the second parameter of a `describe()` function is a
 callback function. This callback function:

package/docs/rules/valid-expect-in-promise.md

@@ -1,4 +1,9 @@
-# Ensure promises that have expectations in their chain are valid (`valid-expect-in-promise`)
+# Require promises that have expectations in their chain to be valid (`valid-expect-in-promise`)
+
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
+
+<!-- end auto-generated rule header -->
 
 Ensure promises that include expectations are returned or awaited.
 

package/docs/rules/valid-expect.md

@@ -1,5 +1,10 @@
 # Enforce valid `expect()` usage (`valid-expect`)
 
+💼 This rule is enabled in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
+
+<!-- end auto-generated rule header -->
+
 Ensure `expect()` is called with a single argument and there is an actual
 expectation made.
 
@@ -103,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

package/docs/rules/valid-title.md

@@ -1,5 +1,13 @@
 # Enforce valid titles (`valid-title`)
 
+💼 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 by the
+[`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
+
 Checks that the title of Jest blocks are valid by ensuring that titles are:
 
 - not empty,
@@ -7,7 +15,7 @@ Checks that the title of Jest blocks are valid by ensuring that titles are:
 - not prefixed with their block name,
 - have no leading or trailing spaces
 
-## Rule Details
+## Rule details
 
 **emptyTitle**