@depup/eslint-plugin-jest 29.15.1-depup.0

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

@@ -0,0 +1,53 @@
+# jest/no-restricted-jest-methods
+
+📝 Disallow specific `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

@@ -0,0 +1,64 @@
+# jest/no-restricted-matchers
+
+📝 Disallow specific matchers & modifiers.
+
+<!-- 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.
+
+## 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.
+
+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.
+
+For example:
+
+```json
+{
+  "jest/no-restricted-matchers": [
+    "error",
+    {
+      "toBeFalsy": null,
+      "resolves": "Use `expect(await promise)` instead.",
+      "toHaveBeenCalledWith": null,
+      "not.toHaveBeenCalledWith": null,
+      "resolves.toHaveBeenCalledWith": null,
+      "rejects.toHaveBeenCalledWith": null,
+      "resolves.not.toHaveBeenCalledWith": null,
+      "rejects.not.toHaveBeenCalledWith": null
+    }
+  ]
+}
+```
+
+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

@@ -0,0 +1,106 @@
+# jest/no-standalone-expect
+
+📝 Disallow using `expect` outside of `it` or `test` blocks.
+
+💼 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
+
+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
+outside a `describe` will not execute and therefore will trigger this rule. It
+is viable, however, to have an `expect` in a helper function that is called from
+within a `test` or `it` block so `expect` statements in a function will not
+trigger this rule.
+
+Statements like `expect.hasAssertions()` will NOT trigger this rule since these
+calls will execute if they are not in a test block.
+
+Examples of **incorrect** code for this rule:
+
+```js
+// in describe
+describe('a test', () => {
+  expect(1).toBe(1);
+});
+
+// below other tests
+describe('a test', () => {
+  it('an it', () => {
+    expect(1).toBe(1);
+  });
+
+  expect(1).toBe(1);
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+// in it block
+describe('a test', () => {
+  it('an it', () => {
+    expect(1).toBe(1);
+  });
+});
+
+// in helper function
+describe('a test', () => {
+  const helper = () => {
+    expect(1).toBe(1);
+  };
+
+  it('an it', () => {
+    helper();
+  });
+});
+
+describe('a test', () => {
+  expect.hasAssertions(1);
+});
+```
+
+\*Note that this rule will not trigger if the helper function is never used even
+though the `expect` will not execute. Rely on a rule like no-unused-vars for
+this case.
+
+### Options
+
+#### `additionalTestBlockFunctions`
+
+This array can be used to specify the names of functions that should also be
+treated as test blocks:
+
+```json
+{
+  "rules": {
+    "jest/no-standalone-expect": [
+      "error",
+      { "additionalTestBlockFunctions": ["each.test"] }
+    ]
+  }
+}
+```
+
+The following is _correct_ when using the above configuration:
+
+```js
+each([
+  [1, 1, 2],
+  [1, 2, 3],
+  [2, 1, 3],
+]).test('returns the result of adding %d to %d', (a, b, expected) => {
+  expect(a + b).toBe(expected);
+});
+```
+
+## When Not To Use It
+
+Don't use this rule on non-jest test files.

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

@@ -0,0 +1,42 @@
+# jest/no-test-prefixes
+
+📝 Require using `.only` and `.skip` over `f` and `x`.
+
+💼 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:
+
+- **only & skip:** `it.only`, `test.only`, `describe.only`, `it.skip`,
+  `test.skip`, `describe.skip`.
+- **'f' & 'x':** `fit`, `fdescribe`, `xit`, `xtest`, `xdescribe`.
+
+This rule enforces usages from the **only & skip** list.
+
+## Rule details
+
+This rule triggers a warning if you use one of the keywords from the **'f' &
+'x'** list to focus/skip a test.
+
+```js
+/*eslint jest/no-test-prefixes: "error"*/
+
+it.only('foo'); // valid
+test.only('foo'); // valid
+describe.only('foo'); // valid
+it.skip('foo'); // valid
+test.skip('foo'); // valid
+describe.skip('foo'); // valid
+
+fit('foo'); // invalid
+fdescribe('foo'); // invalid
+xit('foo'); // invalid
+xtest('foo'); // invalid
+xdescribe('foo'); // invalid
+```

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

@@ -0,0 +1,50 @@
+# jest/no-test-return-statement
+
+📝 Disallow explicitly returning from tests.
+
+<!-- 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
+`async/await`.
+
+## Rule details
+
+This rule triggers a warning if you use a return statement inside a test body.
+
+```js
+/*eslint jest/no-test-return-statement: "error"*/
+
+// valid:
+
+it('noop', function () {});
+
+test('noop', () => {});
+
+test('one arrow', () => expect(1).toBe(1));
+
+test('empty');
+
+test('one', () => {
+  expect(1).toBe(1);
+});
+
+it('one', function () {
+  expect(1).toBe(1);
+});
+
+it('returning a promise', async () => {
+  await new Promise(res => setTimeout(res, 100));
+  expect(1).toBe(1);
+});
+
+// invalid:
+test('return an expect', () => {
+  return expect(1).toBe(1);
+});
+
+it('returning a promise', function () {
+  return new Promise(res => setTimeout(res, 100)).then(() => expect(1).toBe(1));
+});
+```

package/docs/rules/no-unnecessary-assertion.md

@@ -0,0 +1,41 @@
+# jest/no-unnecessary-assertion
+
+📝 Disallow unnecessary assertions based on types.
+
+💭 This rule requires
+[type information](https://typescript-eslint.io/linting/typed-linting).
+
+<!-- end auto-generated rule header -->
+
+When using TypeScript, runtime assertions based on types can often be omitted
+provided that the types are accurate.
+
+## Rule details
+
+This rule warns when you do an assertion about being `null`, `undefined`, or
+`NaN` on something that cannot be those types, as that indicates either the
+assertion can be removed or the types need to be adjusted.
+
+The following patterns are considered warnings:
+
+```ts
+expect('hello world'.match('sunshine') ?? []).toBeNull();
+
+expect(User.findOrThrow(1)).toBeDefined();
+
+expect(map.getOrInsert('key', 'default')).not.toBeUndefined();
+
+expect(user.name).not.toBeNaN();
+```
+
+The following patterns are not considered warnings:
+
+```ts
+expect('hello world'.match('sunshine')).toBeNull();
+
+expect(User.findOrNull(1)).toBeDefined();
+
+expect(map.get('key')).not.toBeUndefined();
+
+expect(user.age).not.toBeNaN();
+```

package/docs/rules/no-unneeded-async-expect-function.md

@@ -0,0 +1,41 @@
+# jest/no-unneeded-async-expect-function
+
+📝 Disallow unnecessary async function wrapper for expected promises.
+
+🔧 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` can handle fulfilled/rejected promisified function call normally but
+occassionally, engineers wrap said function in another `async` function that is
+excessively verbose and make the tests harder to read.
+
+## Rule details
+
+This rule triggers a warning if `expect` is passed with an an `async` function
+that has a single `await` call.
+
+Examples of **incorrect** code for this rule
+
+```js
+it('wrong1', async () => {
+  await expect(async () => {
+    await doSomethingAsync();
+  }).rejects.toThrow();
+});
+
+it('wrong2', async () => {
+  await expect(async function () {
+    await doSomethingAsync();
+  }).rejects.toThrow();
+});
+```
+
+Examples of **correct** code for this rule
+
+```js
+it('right1', async () => {
+  await expect(doSomethingAsync()).rejects.toThrow();
+});
+```

package/docs/rules/no-untyped-mock-factory.md

@@ -0,0 +1,74 @@
+# jest/no-untyped-mock-factory
+
+📝 Disallow using `jest.mock()` factories without an explicit type parameter.
+
+🔧 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 -->
+
+By default, `jest.mock` and `jest.doMock` allow any type to be returned by a
+mock factory. A generic type parameter can be used to enforce that the factory
+returns an object with the same shape as the original module, or some other
+strict type. Requiring a type makes it easier to use TypeScript to catch changes
+needed in test mocks when the source module changes.
+
+> **Warning**
+>
+> This rule expects to be run on TypeScript files **only**. If you are using a
+> codebase that has a mix of JavaScript and TypeScript tests, you can use
+> [overrides](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#how-do-overrides-work)
+> to apply this rule to just your TypeScript test files.
+
+## Rule details
+
+This rule triggers a warning if `mock()` or `doMock()` is used without a generic
+type parameter or return type.
+
+The following patterns are considered errors:
+
+```ts
+jest.mock('../moduleName', () => {
+  return jest.fn(() => 42);
+});
+
+jest.mock('./module', () => ({
+  ...jest.requireActual('./module'),
+  foo: jest.fn(),
+}));
+
+jest.mock('random-num', () => {
+  return jest.fn(() => 42);
+});
+```
+
+The following patterns are not considered errors:
+
+```ts
+// Uses typeof import()
+jest.mock<typeof import('../moduleName')>('../moduleName', () => {
+  return jest.fn(() => 42);
+});
+
+jest.mock<typeof import('./module')>('./module', () => ({
+  ...jest.requireActual('./module'),
+  foo: jest.fn(),
+}));
+
+// Uses custom type
+jest.mock<() => number>('random-num', () => {
+  return jest.fn(() => 42);
+});
+
+// No factory
+jest.mock('random-num');
+
+// Virtual mock
+jest.mock(
+  '../moduleName',
+  () => {
+    return jest.fn(() => 42);
+  },
+  { virtual: true },
+);
+```

package/docs/rules/padding-around-after-all-blocks.md

@@ -0,0 +1,34 @@
+# jest/padding-around-after-all-blocks
+
+📝 Enforce padding around `afterAll` blocks.
+
+🔧 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
+
+This rule enforces a line of padding before _and_ after 1 or more `afterAll`
+statements.
+
+Note that it doesn't add/enforce a padding line if it's the last statement in
+its scope.
+
+Examples of **incorrect** code for this rule:
+
+```js
+const someText = 'abc';
+afterAll(() => {});
+describe('someText', () => {});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const someText = 'abc';
+
+afterAll(() => {});
+
+describe('someText', () => {});
+```

package/docs/rules/padding-around-after-each-blocks.md

@@ -0,0 +1,38 @@
+# jest/padding-around-after-each-blocks
+
+📝 Enforce padding around `afterEach` blocks.
+
+🔧 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
+
+This rule enforces a line of padding before _and_ after 1 or more `afterEach`
+statements.
+
+Note that it doesn't add/enforce a padding line if it's the last statement in
+its scope.
+
+Examples of **incorrect** code for this rule:
+
+```js
+const something = 123;
+afterEach(() => {
+  // more stuff
+});
+describe('foo', () => {});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const something = 123;
+
+afterEach(() => {
+  // more stuff
+});
+
+describe('foo', () => {});
+```

package/docs/rules/padding-around-all.md

@@ -0,0 +1,20 @@
+# jest/padding-around-all
+
+📝 Enforce padding around Jest functions.
+
+🔧 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
+
+This is a meta rule that simply enables all of the following rules:
+
+- [padding-around-after-all-blocks](padding-around-after-all-blocks.md)
+- [padding-around-after-each-blocks](padding-around-after-each-blocks.md)
+- [padding-around-before-all-blocks](padding-around-before-all-blocks.md)
+- [padding-around-before-each-blocks](padding-around-before-each-blocks.md)
+- [padding-around-expect-groups](padding-around-expect-groups.md)
+- [padding-around-describe-blocks](padding-around-describe-blocks.md)
+- [padding-around-test-blocks](padding-around-test-blocks.md)

package/docs/rules/padding-around-before-all-blocks.md

@@ -0,0 +1,37 @@
+# jest/padding-around-before-all-blocks
+
+📝 Enforce padding around `beforeAll` blocks.
+
+🔧 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
+
+This rule enforces a line of padding before _and_ after `beforeAll` statements.
+
+Note that it doesn't add/enforce a padding line if it's the last statement in
+its scope.
+
+Examples of **incorrect** code for this rule:
+
+```js
+const something = 123;
+beforeAll(() => {
+  // more stuff
+});
+describe('foo', () => {});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const something = 123;
+
+beforeAll(() => {
+  // more stuff
+});
+
+describe('foo', () => {});
+```

package/docs/rules/padding-around-before-each-blocks.md

@@ -0,0 +1,38 @@
+# jest/padding-around-before-each-blocks
+
+📝 Enforce padding around `beforeEach` blocks.
+
+🔧 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
+
+This rule enforces a line of padding before _and_ after 1 or more `beforeEach`
+statements
+
+Note that it doesn't add/enforce a padding line if it's the last statement in
+its scope
+
+Examples of **incorrect** code for this rule:
+
+```js
+const something = 123;
+beforeEach(() => {
+  // more stuff
+});
+describe('foo', () => {});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const something = 123;
+
+beforeEach(() => {
+  // more stuff
+});
+
+describe('foo', () => {});
+```

package/docs/rules/padding-around-describe-blocks.md

@@ -0,0 +1,42 @@
+# jest/padding-around-describe-blocks
+
+📝 Enforce padding around `describe` blocks.
+
+🔧 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
+
+This rule enforces a line of padding before _and_ after 1 or more `describe`
+statements
+
+Note that it doesn't add/enforce a padding line if it's the last statement in
+its scope
+
+Examples of **incorrect** code for this rule:
+
+```js
+const thing = 123;
+describe('foo', () => {
+  // stuff
+});
+describe('bar', () => {
+  // more stuff
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const thing = 123;
+
+describe('foo', () => {
+  // stuff
+});
+
+describe('bar', () => {
+  // more stuff
+});
+```