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

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

@@ -0,0 +1,62 @@
+# jest/prefer-expect-resolves
+
+📝 Prefer `await expect(...).resolves` over `expect(await ...)` syntax.
+
+🔧 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:
+
+1. use the `resolve` modifier on `expect`
+   (`await expect(...).resolves.<matcher>` style)
+2. `await` the promise and assert against its result
+   (`expect(await ...).<matcher>` style)
+
+While the second style is arguably less dependent on `jest`, if the promise
+rejects it will be treated as a general error, resulting in less predictable
+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
+
+This rule triggers a warning if an `await` is done within an `expect`, and
+recommends using `resolves` instead.
+
+Examples of **incorrect** code for this rule
+
+```js
+it('passes', async () => {
+  expect(await someValue()).toBe(true);
+});
+
+it('is true', async () => {
+  const myPromise = Promise.resolve(true);
+
+  expect(await myPromise).toBe(true);
+});
+```
+
+Examples of **correct** code for this rule
+
+```js
+it('passes', async () => {
+  await expect(someValue()).resolves.toBe(true);
+});
+
+it('is true', async () => {
+  const myPromise = Promise.resolve(true);
+
+  await expect(myPromise).resolves.toBe(true);
+});
+
+it('errors', async () => {
+  await expect(Promise.reject(new Error('oh noes!'))).rejects.toThrowError(
+    'oh noes!',
+  );
+});
+```

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

@@ -0,0 +1,137 @@
+# jest/prefer-hooks-in-order
+
+📝 Prefer having hooks in a consistent order.
+
+<!-- end auto-generated rule header -->
+
+While hooks can be setup in any order, they're always called by `jest` in this
+specific order:
+
+1. `beforeAll`
+1. `beforeEach`
+1. `afterEach`
+1. `afterAll`
+
+This rule aims to make that more obvious by enforcing grouped hooks be setup in
+that order within tests.
+
+## Rule details
+
+Examples of **incorrect** code for this rule
+
+```js
+/* eslint jest/prefer-hooks-in-order: "error" */
+
+describe('foo', () => {
+  beforeEach(() => {
+    seedMyDatabase();
+  });
+
+  beforeAll(() => {
+    createMyDatabase();
+  });
+
+  it('accepts this input', () => {
+    // ...
+  });
+
+  it('returns that value', () => {
+    // ...
+  });
+
+  describe('when the database has specific values', () => {
+    const specificValue = '...';
+
+    beforeEach(() => {
+      seedMyDatabase(specificValue);
+    });
+
+    it('accepts that input', () => {
+      // ...
+    });
+
+    it('throws an error', () => {
+      // ...
+    });
+
+    afterEach(() => {
+      clearLogger();
+    });
+    beforeEach(() => {
+      mockLogger();
+    });
+
+    it('logs a message', () => {
+      // ...
+    });
+  });
+
+  afterAll(() => {
+    removeMyDatabase();
+  });
+});
+```
+
+Examples of **correct** code for this rule
+
+```js
+/* eslint jest/prefer-hooks-in-order: "error" */
+
+describe('foo', () => {
+  beforeAll(() => {
+    createMyDatabase();
+  });
+
+  beforeEach(() => {
+    seedMyDatabase();
+  });
+
+  it('accepts this input', () => {
+    // ...
+  });
+
+  it('returns that value', () => {
+    // ...
+  });
+
+  describe('when the database has specific values', () => {
+    const specificValue = '...';
+
+    beforeEach(() => {
+      seedMyDatabase(specificValue);
+    });
+
+    it('accepts that input', () => {
+      // ...
+    });
+
+    it('throws an error', () => {
+      // ...
+    });
+
+    beforeEach(() => {
+      mockLogger();
+    });
+
+    afterEach(() => {
+      clearLogger();
+    });
+
+    it('logs a message', () => {
+      // ...
+    });
+  });
+
+  afterAll(() => {
+    removeMyDatabase();
+  });
+});
+```
+
+## Also See
+
+- [`prefer-hooks-on-top`](prefer-hooks-on-top.md)
+
+## Further Reading
+
+- [Order of Execution](https://jestjs.io/docs/setup-teardown#order-of-execution)

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

@@ -0,0 +1,124 @@
+# jest/prefer-hooks-on-top
+
+📝 Suggest having hooks before any test cases.
+
+<!-- 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
+
+Examples of **incorrect** code for this rule
+
+```js
+/* eslint jest/prefer-hooks-on-top: "error" */
+
+describe('foo', () => {
+  beforeEach(() => {
+    seedMyDatabase();
+  });
+
+  it('accepts this input', () => {
+    // ...
+  });
+
+  beforeAll(() => {
+    createMyDatabase();
+  });
+
+  it('returns that value', () => {
+    // ...
+  });
+
+  describe('when the database has specific values', () => {
+    const specificValue = '...';
+
+    beforeEach(() => {
+      seedMyDatabase(specificValue);
+    });
+
+    it('accepts that input', () => {
+      // ...
+    });
+
+    it('throws an error', () => {
+      // ...
+    });
+
+    afterEach(() => {
+      clearLogger();
+    });
+    beforeEach(() => {
+      mockLogger();
+    });
+
+    it('logs a message', () => {
+      // ...
+    });
+  });
+
+  afterAll(() => {
+    removeMyDatabase();
+  });
+});
+```
+
+Examples of **correct** code for this rule
+
+```js
+/* eslint jest/prefer-hooks-on-top: "error" */
+
+describe('foo', () => {
+  beforeAll(() => {
+    createMyDatabase();
+  });
+
+  beforeEach(() => {
+    seedMyDatabase();
+  });
+
+  afterAll(() => {
+    clearMyDatabase();
+  });
+
+  it('accepts this input', () => {
+    // ...
+  });
+
+  it('returns that value', () => {
+    // ...
+  });
+
+  describe('when the database has specific values', () => {
+    const specificValue = '...';
+
+    beforeEach(() => {
+      seedMyDatabase(specificValue);
+    });
+
+    beforeEach(() => {
+      mockLogger();
+    });
+
+    afterEach(() => {
+      clearLogger();
+    });
+
+    it('accepts that input', () => {
+      // ...
+    });
+
+    it('throws an error', () => {
+      // ...
+    });
+
+    it('logs a message', () => {
+      // ...
+    });
+  });
+});
+```

package/docs/rules/prefer-importing-jest-globals.md

@@ -0,0 +1,85 @@
+# jest/prefer-importing-jest-globals
+
+📝 Prefer importing Jest globals.
+
+🔧 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 -->
+
+This rule aims to enforce explicit imports from `@jest/globals`.
+
+1. This is useful for ensuring that the Jest APIs are imported the same way in
+   the codebase.
+2. When you can't modify Jest's
+   [`injectGlobals`](https://jestjs.io/docs/configuration#injectglobals-boolean)
+   configuration property, this rule can help to ensure that the Jest globals
+   are imported explicitly and facilitate a migration to `@jest/globals`.
+
+## Rule details
+
+Examples of **incorrect** code for this rule
+
+```js
+/* eslint jest/prefer-importing-jest-globals: "error" */
+
+describe('foo', () => {
+  it('accepts this input', () => {
+    // ...
+  });
+});
+```
+
+Examples of **correct** code for this rule
+
+```js
+/* eslint jest/prefer-importing-jest-globals: "error" */
+
+import { describe, it } from '@jest/globals';
+
+describe('foo', () => {
+  it('accepts this input', () => {
+    // ...
+  });
+});
+```
+
+## Options
+
+This rule can be configured as follows
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "types": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["hook", "describe", "test", "expect", "jest", "unknown"]
+      }
+    }
+  },
+  "additionalProperties": false
+}
+```
+
+#### types
+
+A list of Jest global types to enforce explicit imports for. By default, all
+Jest globals are enforced.
+
+This option is useful when you only want to enforce explicit imports for a
+subset of Jest globals. For instance, when migrating to ESM, you might want to
+enforce explicit imports only for the `jest` global, as of
+[Jest's ESM documentation](https://jestjs.io/docs/ecmascript-modules#differences-between-esm-and-commonjs).
+
+```json5
+{
+  'jest/prefer-importing-jest-globals': ['error', { types: ['jest'] }],
+}
+```
+
+## Further Reading
+
+- [Documentation](https://jestjs.io/docs/api)

package/docs/rules/prefer-jest-mocked.md

@@ -0,0 +1,40 @@
+# jest/prefer-jest-mocked
+
+📝 Prefer `jest.mocked()` over `fn as jest.Mock`.
+
+🔧 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 using Jest, it's recommended to use the
+`jest.mocked()` helper function to properly type the mocked functions. This rule
+enforces the use of `jest.mocked()` for better type safety and readability.
+
+Restricted types:
+
+- `jest.Mock`
+- `jest.MockedFunction`
+- `jest.MockedClass`
+- `jest.MockedObject`
+
+## Rule details
+
+The following patterns are warnings:
+
+```typescript
+(foo as jest.Mock).mockReturnValue(1);
+const mock = (foo as jest.Mock).mockReturnValue(1);
+(foo as unknown as jest.Mock).mockReturnValue(1);
+(Obj.foo as jest.Mock).mockReturnValue(1);
+([].foo as jest.Mock).mockReturnValue(1);
+```
+
+The following patterns are not warnings:
+
+```js
+jest.mocked(foo).mockReturnValue(1);
+const mock = jest.mocked(foo).mockReturnValue(1);
+jest.mocked(Obj.foo).mockReturnValue(1);
+jest.mocked([].foo).mockReturnValue(1);
+```

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

@@ -0,0 +1,128 @@
+# jest/prefer-lowercase-title
+
+📝 Enforce lowercase test names.
+
+🔧 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
+lowercase letter. This provides more readable test failures. This rule is not
+enabled by default.
+
+The following pattern is considered a warning:
+
+```js
+it('Adds 1 + 2 to equal 3', () => {
+  expect(sum(1, 2)).toBe(3);
+});
+```
+
+The following pattern is not considered a warning:
+
+```js
+it('adds 1 + 2 to equal 3', () => {
+  expect(sum(1, 2)).toBe(3);
+});
+```
+
+## Options
+
+```json
+{
+  "jest/prefer-lowercase-title": [
+    "error",
+    {
+      "ignore": ["describe", "test"]
+    }
+  ]
+}
+```
+
+### `ignore`
+
+This array option controls which Jest functions are checked by this rule. There
+are three possible values:
+
+- `"describe"`
+- `"test"`
+- `"it"`
+
+By default, none of these options are enabled (the equivalent of
+`{ "ignore": [] }`).
+
+Example of **correct** code for the `{ "ignore": ["describe"] }` option:
+
+```js
+/* eslint jest/prefer-lowercase-title: ["error", { "ignore": ["describe"] }] */
+
+describe('Uppercase description');
+```
+
+Example of **correct** code for the `{ "ignore": ["test"] }` option:
+
+```js
+/* eslint jest/prefer-lowercase-title: ["error", { "ignore": ["test"] }] */
+
+test('Uppercase description');
+```
+
+Example of **correct** code for the `{ "ignore": ["it"] }` option:
+
+```js
+/* eslint jest/prefer-lowercase-title: ["error", { "ignore": ["it"] }] */
+
+it('Uppercase description');
+```
+
+### `allowedPrefixes`
+
+This array option allows specifying prefixes, which contain capitals that titles
+can start with. This can be useful when writing tests for API endpoints, where
+you'd like to prefix with the HTTP method.
+
+By default, nothing is allowed (the equivalent of `{ "allowedPrefixes": [] }`).
+
+Example of **correct** code for the `{ "allowedPrefixes": ["GET"] }` option:
+
+```js
+/* eslint jest/prefer-lowercase-title: ["error", { "allowedPrefixes": ["GET"] }] */
+
+describe('GET /live');
+```
+
+### `ignoreTopLevelDescribe`
+
+This option can be set to allow only the top-level `describe` blocks to have a
+title starting with an upper-case letter.
+
+Example of **correct** code for the `{ "ignoreTopLevelDescribe": true }` option:
+
+```js
+/* eslint jest/prefer-lowercase-title: ["error", { "ignoreTopLevelDescribe": true }] */
+describe('MyClass', () => {
+  describe('#myMethod', () => {
+    it('does things', () => {
+      //
+    });
+  });
+});
+```
+
+### `ignoreTodos`
+
+This option is used to control whether
+[`todo`](https://jestjs.io/docs/api#testtodoname) Jest functions to be checked
+by this rule. By the default, the option is set to false.
+
+Example of **correct** code for the `{ "ignoreTodos": true }` option:
+
+```js
+/* eslint jest/prefer-lowercase-title: ["error", { "ignoreTodos": true }] */
+test.todo('Uppercase description');
+
+it.todo('Uppercase description');
+```

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

@@ -0,0 +1,41 @@
+# jest/prefer-mock-promise-shorthand
+
+📝 Prefer mock resolved/rejected shorthands for 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 -->
+
+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
+
+The following patterns are warnings:
+
+```js
+jest.fn().mockImplementation(() => Promise.resolve(123));
+jest
+  .spyOn(fs.promises, 'readFile')
+  .mockReturnValue(Promise.reject(new Error('oh noes!')));
+
+myFunction
+  .mockReturnValueOnce(Promise.resolve(42))
+  .mockImplementationOnce(() => Promise.resolve(42))
+  .mockReturnValue(Promise.reject(new Error('too many calls!')));
+```
+
+The following patterns are not warnings:
+
+```js
+jest.fn().mockResolvedValue(123);
+jest.spyOn(fs.promises, 'readFile').mockRejectedValue(new Error('oh noes!'));
+
+myFunction
+  .mockResolvedValueOnce(42)
+  .mockResolvedValueOnce(42)
+  .mockRejectedValue(new Error('too many calls!'));
+```

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

@@ -0,0 +1,50 @@
+# jest/prefer-mock-return-shorthand
+
+📝 Prefer mock return shorthands.
+
+🔧 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 simple values, 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
+
+The following patterns are warnings:
+
+```js
+jest.fn().mockImplementation(() => 'hello world');
+
+jest
+  .spyOn(fs.promises, 'readFile')
+  .mockImplementationOnce(() => Promise.reject(new Error('oh noes!')));
+
+myFunction
+  .mockImplementationOnce(() => 42)
+  .mockImplementationOnce(() => Promise.resolve(42))
+  .mockReturnValue(0);
+```
+
+The following patterns are not warnings:
+
+```js
+jest.fn().mockResolvedValue(123);
+
+jest
+  .spyOn(fs.promises, 'readFile')
+  .mockReturnValue(Promise.reject(new Error('oh noes!')));
+jest.spyOn(fs.promises, 'readFile').mockRejectedValue(new Error('oh noes!'));
+
+jest.spyOn(fs, 'readFileSync').mockImplementationOnce(() => {
+  throw new Error('oh noes!');
+});
+
+myFunction
+  .mockResolvedValueOnce(42)
+  .mockResolvedValueOnce(42)
+  .mockReturnValue(0);
+```