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

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

@@ -0,0 +1,192 @@
+# jest/prefer-snapshot-hint
+
+📝 Prefer including a hint with external snapshots.
+
+<!-- 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.
+
+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
+
+This rule looks for any use of an external snapshot matcher (e.g.
+`toMatchSnapshot` and `toThrowErrorMatchingSnapshot`) and checks if they include
+a snapshot hint.
+
+## Options
+
+### `'always'`
+
+Require a hint to _always_ be provided when using external snapshot matchers.
+
+Examples of **incorrect** code for the `'always'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }) => {
+  expect(stdout).toMatchSnapshot();
+  expect(stderr).toMatchSnapshot();
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']));
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout, parsedConfig } = await runCli([
+        '--config',
+        'jest.config.js',
+      ]);
+
+      expect(stdout).toMatchSnapshot();
+      expect(parsedConfig).toMatchSnapshot();
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchSnapshot();
+    });
+
+    describe('when the file does not exist', () => {
+      it('throws an error', async () => {
+        await expect(
+          runCli(['--config', 'does-not-exist.js']),
+        ).rejects.toThrowErrorMatchingSnapshot();
+      });
+    });
+  });
+});
+```
+
+Examples of **correct** code for the `'always'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }, hints) => {
+  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
+  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']), {
+        stdout: 'version string',
+        stderr: 'empty',
+      });
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stdout).toMatchSnapshot({}, 'stdout: config settings');
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchInlineSnapshot();
+    });
+
+    describe('when the file does not exist', () => {
+      it('throws an error', async () => {
+        await expect(
+          runCli(['--config', 'does-not-exist.js']),
+        ).rejects.toThrowErrorMatchingSnapshot('stderr: config error');
+      });
+    });
+  });
+});
+```
+
+### `'multi'` (default)
+
+Require a hint to be provided when there are multiple external snapshot matchers
+within the scope (meaning it includes nested calls).
+
+Examples of **incorrect** code for the `'multi'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }) => {
+  expect(stdout).toMatchSnapshot();
+  expect(stderr).toMatchSnapshot();
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']));
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout, parsedConfig } = await runCli([
+        '--config',
+        'jest.config.js',
+      ]);
+
+      expect(stdout).toMatchSnapshot();
+      expect(parsedConfig).toMatchSnapshot();
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchSnapshot();
+    });
+  });
+});
+```
+
+Examples of **correct** code for the `'multi'` option:
+
+```js
+const snapshotOutput = ({ stdout, stderr }, hints) => {
+  expect(stdout).toMatchSnapshot({}, `stdout: ${hints.stdout}`);
+  expect(stderr).toMatchSnapshot({}, `stderr: ${hints.stderr}`);
+};
+
+describe('cli', () => {
+  describe('--version flag', () => {
+    it('prints the version', async () => {
+      snapshotOutput(await runCli(['--version']), {
+        stdout: 'version string',
+        stderr: 'empty',
+      });
+    });
+  });
+
+  describe('--config flag', () => {
+    it('reads the config', async () => {
+      const { stdout } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stdout).toMatchSnapshot();
+    });
+
+    it('prints nothing to stderr', async () => {
+      const { stderr } = await runCli(['--config', 'jest.config.js']);
+
+      expect(stderr).toMatchInlineSnapshot();
+    });
+
+    describe('when the file does not exist', () => {
+      it('throws an error', async () => {
+        await expect(
+          runCli(['--config', 'does-not-exist.js']),
+        ).rejects.toThrowErrorMatchingSnapshot();
+      });
+    });
+  });
+});
+```

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

@@ -0,0 +1,46 @@
+# jest/prefer-spy-on
+
+📝 Suggest using `jest.spyOn()`.
+
+🔧 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()`,
+`mockFn.mockRestore()` or by setting `restoreMocks` to `true` in the Jest
+config.
+
+Note: The mock created by `jest.spyOn()` still behaves the same as the original
+function. The original function can be overwritten with
+`mockFn.mockImplementation()` or by some of the
+[other mock functions](https://jestjs.io/docs/en/mock-function-api).
+
+```js
+Date.now = jest.fn(); // Original behaviour lost, returns undefined
+
+jest.spyOn(Date, 'now'); // Turned into a mock function but behaviour hasn't changed
+jest.spyOn(Date, 'now').mockImplementation(() => 10); // Will always return 10
+jest.spyOn(Date, 'now').mockReturnValue(10); // Will always return 10
+```
+
+## Rule details
+
+This rule triggers a warning if an object's property is overwritten with a jest
+mock.
+
+The following patterns are considered warnings:
+
+```js
+Date.now = jest.fn();
+Date.now = jest.fn(() => 10);
+```
+
+These patterns would not be considered warnings:
+
+```js
+jest.spyOn(Date, 'now');
+jest.spyOn(Date, 'now').mockImplementation(() => 10);
+```

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

@@ -0,0 +1,29 @@
+# jest/prefer-strict-equal
+
+📝 Suggest using `toStrictEqual()`.
+
+💡 This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-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
+catch cases where two objects do not have identical keys.
+
+## Rule details
+
+This rule triggers a warning if `toEqual()` is used to assert equality.
+
+The following pattern is considered warning:
+
+```js
+expect({ a: 'a', b: undefined }).toEqual({ a: 'a' }); // true
+```
+
+The following pattern is not warning:
+
+```js
+expect({ a: 'a', b: undefined }).toStrictEqual({ a: 'a' }); // false
+```

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

@@ -0,0 +1,63 @@
+# jest/prefer-to-be
+
+📝 Suggest using `toBe()` for primitive literals.
+
+💼 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.
+
+This rule recommends using the `toBe` matcher in these situations, as it forms
+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
+
+This rule triggers a warning if `toEqual()` or `toStrictEqual()` are used to
+assert a primitive literal value such as numbers, strings, and booleans.
+
+The following patterns are considered warnings:
+
+```js
+expect(value).not.toEqual(5);
+expect(getMessage()).toStrictEqual('hello world');
+expect(loadMessage()).resolves.toEqual('hello world');
+```
+
+The following pattern is not warning:
+
+```js
+expect(value).not.toBe(5);
+expect(getMessage()).toBe('hello world');
+expect(loadMessage()).resolves.toBe('hello world');
+expect(didError).not.toBe(true);
+
+expect(catchError()).toStrictEqual({ message: 'oh noes!' });
+```
+
+For `null`, `undefined`, and `NaN`, this rule triggers a warning if `toBe` is
+used to assert against those literal values instead of their more specific
+`toBe` counterparts:
+
+```js
+expect(value).not.toBe(undefined);
+expect(getMessage()).toBe(null);
+expect(countMessages()).resolves.not.toBe(NaN);
+```
+
+The following pattern is not warning:
+
+```js
+expect(value).toBeDefined();
+expect(getMessage()).toBeNull();
+expect(countMessages()).resolves.not.toBeNaN();
+
+expect(catchError()).toStrictEqual({ message: undefined });
+```

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

@@ -0,0 +1,53 @@
+# jest/prefer-to-contain
+
+📝 Suggest using `toContain()`.
+
+💼 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.
+
+## Rule details
+
+This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
+used to assert object inclusion in an array
+
+```js
+expect(a.includes(b)).toBe(true);
+```
+
+```js
+expect(a.includes(b)).not.toBe(true);
+```
+
+```js
+expect(a.includes(b)).toBe(false);
+```
+
+The following patterns are considered warnings:
+
+```js
+expect(a.includes(b)).toBe(true);
+
+expect(a.includes(b)).not.toBe(true);
+
+expect(a.includes(b)).toBe(false);
+
+expect(a.includes(b)).toEqual(true);
+
+expect(a.includes(b)).toStrictEqual(true);
+```
+
+The following patterns are not considered warnings:
+
+```js
+expect(a).toContain(b);
+
+expect(a).not.toContain(b);
+```

package/docs/rules/prefer-to-have-been-called-times.md

@@ -0,0 +1,43 @@
+# jest/prefer-to-have-been-called-times
+
+📝 Suggest using `toHaveBeenCalledTimes()`.
+
+🔧 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, `toHaveBeenCalledTimes` should be
+used instead of directly checking the length of `mock.calls`.
+
+## Rule details
+
+This rule triggers a warning if `toHaveLength` is used to assert the number of
+times a mock is called.
+
+> [!NOTE]
+>
+> This rule should ideally be paired with
+> [`prefer-to-have-length`](./prefer-to-have-length.md)
+
+The following patterns are considered warnings:
+
+```js
+expect(someFunction.mock.calls).toHaveLength(1);
+expect(someFunction.mock.calls).toHaveLength(0);
+
+expect(someFunction.mock.calls).not.toHaveLength(1);
+```
+
+The following patterns are not warnings:
+
+```js
+expect(someFunction).toHaveBeenCalledTimes(1);
+expect(someFunction).toHaveBeenCalledTimes(0);
+
+expect(someFunction).not.toHaveBeenCalledTimes(0);
+
+expect(uncalledFunction).not.toBeCalled();
+
+expect(method.mock.calls[0][0]).toStrictEqual(value);
+```

package/docs/rules/prefer-to-have-been-called.md

@@ -0,0 +1,35 @@
+# jest/prefer-to-have-been-called
+
+📝 Suggest using `toHaveBeenCalled`.
+
+🔧 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, `toHaveBeenCalled` should be used
+instead of checking the number of times a mock has been called.
+
+## Rule details
+
+This rule triggers a warning if `toHaveBeenCalledTimes` is used to assert that a
+mock has or has not been called zero times
+
+> [!NOTE]
+>
+> This rule should ideally be paired with
+> [`prefer-to-have-been-called-times`](./prefer-to-have-been-called-times.md)
+
+The following patterns are considered warnings:
+
+```js
+expect(someFunction).toHaveBeenCalledTimes(0);
+expect(someFunction).not.toHaveBeenCalledTimes(0);
+```
+
+The following patterns are not warnings:
+
+```js
+expect(someFunction).not.toHaveBeenCalled();
+expect(someFunction).toHaveBeenCalled();
+```

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

@@ -0,0 +1,41 @@
+# jest/prefer-to-have-length
+
+📝 Suggest using `toHaveLength()`.
+
+💼 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.
+
+## Rule details
+
+This rule triggers a warning if `toBe()`, `toEqual()` or `toStrictEqual()` is
+used to assert objects length property.
+
+```js
+expect(files.length).toBe(1);
+```
+
+This rule is enabled by default.
+
+The following patterns are considered warnings:
+
+```js
+expect(files.length).toBe(1);
+
+expect(files.length).toEqual(1);
+
+expect(files.length).toStrictEqual(1);
+```
+
+The following pattern is not warning:
+
+```js
+expect(files).toHaveLength(1);
+```

package/docs/rules/prefer-todo.md

@@ -0,0 +1,33 @@
+# jest/prefer-todo
+
+📝 Suggest using `test.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.
+
+## Rule details
+
+This rule triggers a warning if empty test cases are used without 'test.todo'.
+
+```js
+test('i need to write this test');
+```
+
+The following pattern is considered warning:
+
+```js
+test('i need to write this test'); // Unimplemented test case
+test('i need to write this test', () => {}); // Empty test case body
+test.skip('i need to write this test', () => {}); // Empty test case body
+```
+
+The following pattern is not warning:
+
+```js
+test.todo('i need to write this test');
+```