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

package/docs/rules/require-hook.md

@@ -0,0 +1,187 @@
+# jest/require-hook
+
+📝 Require setup and teardown code to be within a hook.
+
+<!-- end auto-generated rule header -->
+
+It's common when writing tests to need to perform setup work that has to happen
+before tests run, and finishing work after tests run.
+
+Because Jest executes all `describe` handlers in a test file _before_ it
+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
+
+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:
+
+- `import` statements
+- `const` variables
+- `let` _declarations_, and initializations to `null` or `undefined`
+- Classes
+- Types
+- Calls to the standard Jest globals
+
+This rule flags any function calls within test files that are directly within
+the body of a `describe`, and suggests wrapping them in one of the four
+lifecycle hooks.
+
+Here is a slightly contrived test file showcasing some common cases that would
+be flagged:
+
+```js
+import { database, isCity } from '../database';
+import { Logger } from '../../../src/Logger';
+import { loadCities } from '../api';
+
+jest.mock('../api');
+
+const initializeCityDatabase = () => {
+  database.addCity('Vienna');
+  database.addCity('San Juan');
+  database.addCity('Wellington');
+};
+
+const clearCityDatabase = () => {
+  database.clear();
+};
+
+initializeCityDatabase();
+
+test('that persists cities', () => {
+  expect(database.cities.length).toHaveLength(3);
+});
+
+test('city database has Vienna', () => {
+  expect(isCity('Vienna')).toBeTruthy();
+});
+
+test('city database has San Juan', () => {
+  expect(isCity('San Juan')).toBeTruthy();
+});
+
+describe('when loading cities from the api', () => {
+  let consoleWarnSpy = jest.spyOn(console, 'warn');
+
+  loadCities.mockResolvedValue(['Wellington', 'London']);
+
+  it('does not duplicate cities', async () => {
+    await database.loadCities();
+
+    expect(database.cities).toHaveLength(4);
+  });
+
+  it('logs any duplicates', async () => {
+    await database.loadCities();
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      'Ignored duplicate cities: Wellington',
+    );
+  });
+});
+
+clearCityDatabase();
+```
+
+Here is the same slightly contrived test file showcasing the same common cases
+but in ways that would be **not** flagged:
+
+```js
+import { database, isCity } from '../database';
+import { Logger } from '../../../src/Logger';
+import { loadCities } from '../api';
+
+jest.mock('../api');
+
+const initializeCityDatabase = () => {
+  database.addCity('Vienna');
+  database.addCity('San Juan');
+  database.addCity('Wellington');
+};
+
+const clearCityDatabase = () => {
+  database.clear();
+};
+
+beforeEach(() => {
+  initializeCityDatabase();
+});
+
+test('that persists cities', () => {
+  expect(database.cities.length).toHaveLength(3);
+});
+
+test('city database has Vienna', () => {
+  expect(isCity('Vienna')).toBeTruthy();
+});
+
+test('city database has San Juan', () => {
+  expect(isCity('San Juan')).toBeTruthy();
+});
+
+describe('when loading cities from the api', () => {
+  let consoleWarnSpy;
+
+  beforeEach(() => {
+    consoleWarnSpy = jest.spyOn(console, 'warn');
+    loadCities.mockResolvedValue(['Wellington', 'London']);
+  });
+
+  it('does not duplicate cities', async () => {
+    await database.loadCities();
+
+    expect(database.cities).toHaveLength(4);
+  });
+
+  it('logs any duplicates', async () => {
+    await database.loadCities();
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      'Ignored duplicate cities: Wellington',
+    );
+  });
+});
+
+afterEach(() => {
+  clearCityDatabase();
+});
+```
+
+## Options
+
+If there are methods that you want to call outside of hooks and tests, you can
+mark them as allowed using the `allowedFunctionCalls` option.
+
+```json
+{
+  "jest/require-hook": [
+    "error",
+    {
+      "allowedFunctionCalls": ["enableAutoDestroy"]
+    }
+  ]
+}
+```
+
+Examples of **correct** code when using
+`{ "allowedFunctionCalls": ["enableAutoDestroy"] }` option:
+
+```js
+/* eslint jest/require-hook: ["error", { "allowedFunctionCalls": ["enableAutoDestroy"] }] */
+
+import { enableAutoDestroy, mount } from '@vue/test-utils';
+import { initDatabase, tearDownDatabase } from './databaseUtils';
+
+enableAutoDestroy(afterEach);
+
+beforeEach(initDatabase);
+afterEach(tearDownDatabase);
+
+describe('Foo', () => {
+  test('always returns 42', () => {
+    expect(global.getAnswer()).toBe(42);
+  });
+});
+```

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

@@ -0,0 +1,43 @@
+# jest/require-to-throw-message
+
+📝 Require a message for `toThrow()`.
+
+<!-- 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
+message ensures that the intended error is thrown.
+
+## Rule details
+
+This rule triggers a warning if `toThrow()` or `toThrowError()` is used without
+an error message.
+
+The following patterns are considered warnings:
+
+```js
+test('all the things', async () => {
+  expect(() => a()).toThrow();
+
+  expect(() => a()).toThrowError();
+
+  await expect(a()).rejects.toThrow();
+
+  await expect(a()).rejects.toThrowError();
+});
+```
+
+The following patterns are not considered warnings:
+
+```js
+test('all the things', async () => {
+  expect(() => a()).toThrow('a');
+
+  expect(() => a()).toThrowError('a');
+
+  await expect(a()).rejects.toThrow('a');
+
+  await expect(a()).rejects.toThrowError('a');
+});
+```

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

@@ -0,0 +1,86 @@
+# jest/require-top-level-describe
+
+📝 Require test cases and hooks to be inside a `describe` block.
+
+<!-- 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
+
+This rule triggers a warning if a test case (`test` and `it`) or a hook
+(`beforeAll`, `beforeEach`, `afterEach`, `afterAll`) is not located in a
+top-level `describe` block.
+
+The following patterns are considered warnings:
+
+```js
+// Above a describe block
+test('my test', () => {});
+describe('test suite', () => {
+  it('test', () => {});
+});
+
+// Below a describe block
+describe('test suite', () => {});
+test('my test', () => {});
+
+// Same for hooks
+beforeAll('my beforeAll', () => {});
+describe('test suite', () => {});
+afterEach('my afterEach', () => {});
+```
+
+The following patterns are **not** considered warnings:
+
+```js
+// In a describe block
+describe('test suite', () => {
+  test('my test', () => {});
+});
+
+// In a nested describe block
+describe('test suite', () => {
+  test('my test', () => {});
+  describe('another test suite', () => {
+    test('my other test', () => {});
+  });
+});
+```
+
+## Options
+
+You can also enforce a limit on the number of describes allowed at the top-level
+using the `maxNumberOfTopLevelDescribes` option:
+
+```json
+{
+  "jest/require-top-level-describe": [
+    "error",
+    {
+      "maxNumberOfTopLevelDescribes": 2
+    }
+  ]
+}
+```
+
+Examples of **incorrect** code with the above config:
+
+```js
+describe('test suite', () => {
+  it('test', () => {});
+});
+
+describe('test suite', () => {});
+
+describe('test suite', () => {});
+```
+
+This option defaults to `Infinity`, allowing any number of top-level describes.
+
+## When Not To Use It
+
+Don't use this rule on non-jest test files.

package/docs/rules/unbound-method.md

@@ -0,0 +1,61 @@
+# jest/unbound-method
+
+📝 Enforce unbound methods are called with their expected scope.
+
+💭 This rule requires
+[type information](https://typescript-eslint.io/linting/typed-linting).
+
+<!-- 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
+work. It adds support for understanding when it's ok to pass an unbound method
+to `expect` calls.
+
+See the [`@typescript-eslint` documentation][original-rule] for more details on
+the `unbound-method` rule.
+
+Note that while this rule requires type information to work, it will fail
+silently when not available allowing you to safely enable it on projects that
+are not using TypeScript.
+
+## How to use
+
+```json5
+{
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: 'tsconfig.json',
+    ecmaVersion: 2020,
+    sourceType: 'module',
+  },
+  overrides: [
+    {
+      files: ['test/**'],
+      plugins: ['jest'],
+      rules: {
+        // you should turn the original rule off *only* for test files
+        '@typescript-eslint/unbound-method': 'off',
+        'jest/unbound-method': 'error',
+      },
+    },
+  ],
+  rules: {
+    '@typescript-eslint/unbound-method': 'error',
+  },
+}
+```
+
+This rule should be applied to your test files in place of the original rule,
+which should be applied to the rest of your codebase.
+
+## Options
+
+See [`@typescript-eslint/unbound-method`][original-rule] options (e.g.
+`ignoreStatic`).
+
+<sup>Taken with ❤️ [from `@typescript-eslint` core][original-rule]</sup>
+
+[original-rule]: https://typescript-eslint.io/rules/unbound-method

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

@@ -0,0 +1,69 @@
+# jest/valid-describe-callback
+
+📝 Enforce 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
+
+This rule validates that the second parameter of a `describe()` function is a
+callback function. This callback function:
+
+- should not be
+  [async](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
+- should not contain any parameters
+- should not contain any `return` statements
+
+The following `describe` function aliases are also validated:
+
+- `describe`
+- `describe.only`
+- `describe.skip`
+- `fdescribe`
+- `xdescribe`
+
+The following patterns are considered warnings:
+
+```js
+// Async callback functions are not allowed
+describe('myFunction()', async () => {
+  // ...
+});
+
+// Callback function parameters are not allowed
+describe('myFunction()', done => {
+  // ...
+});
+
+//
+describe('myFunction', () => {
+  // No return statements are allowed in block of a callback function
+  return Promise.resolve().then(() => {
+    it('breaks', () => {
+      throw new Error('Fail');
+    });
+  });
+});
+
+// Returning a value from a describe block is not allowed
+describe('myFunction', () =>
+  it('returns a truthy value', () => {
+    expect(myFunction()).toBeTruthy();
+  }));
+```
+
+The following patterns are not considered warnings:
+
+```js
+describe('myFunction()', () => {
+  it('returns a truthy value', () => {
+    expect(myFunction()).toBeTruthy();
+  });
+});
+```

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

@@ -0,0 +1,79 @@
+# jest/valid-expect-in-promise
+
+📝 Require promises that have expectations in their chain to be valid.
+
+💼 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.
+
+## Rule details
+
+This rule flags any promises within the body of a test that include expectations
+that have either not been returned or awaited.
+
+The following patterns is considered warning:
+
+```js
+it('promises a person', () => {
+  api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+});
+
+it('promises a counted person', () => {
+  const promise = api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+
+  promise.then(() => {
+    expect(analytics.gottenPeopleCount).toBe(1);
+  });
+});
+
+it('promises multiple people', () => {
+  const firstPromise = api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+  const secondPromise = api.getPersonByName('alice').then(person => {
+    expect(person).toHaveProperty('name', 'Alice');
+  });
+
+  return Promise.any([firstPromise, secondPromise]);
+});
+```
+
+The following pattern is not warning:
+
+```js
+it('promises a person', async () => {
+  await api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+});
+
+it('promises a counted person', () => {
+  let promise = api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+
+  promise = promise.then(() => {
+    expect(analytics.gottenPeopleCount).toBe(1);
+  });
+
+  return promise;
+});
+
+it('promises multiple people', () => {
+  const firstPromise = api.getPersonByName('bob').then(person => {
+    expect(person).toHaveProperty('name', 'Bob');
+  });
+  const secondPromise = api.getPersonByName('alice').then(person => {
+    expect(person).toHaveProperty('name', 'Alice');
+  });
+
+  return Promise.allSettled([firstPromise, secondPromise]);
+});
+```

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

@@ -0,0 +1,43 @@
+# jest/valid-expect-with-promise
+
+📝 Require that `resolve` and `reject` modifiers are present (and only) for
+promise-like types.
+
+💭 This rule requires
+[type information](https://typescript-eslint.io/linting/typed-linting).
+
+<!-- end auto-generated rule header -->
+
+When working with promises, you must remember to use `resolves` and `rejects` to
+assert on the value returned (or thrown) by the promise, rather than the promise
+itself.
+
+Inversely, while Jest does not prevent you from using `resolves` and `rejects`
+on non-promise values, it is not necessary.
+
+When TypeScript is in use, it is possible to determine when `resolves` and
+`rejects` should and should not be needed.
+
+## Rule details
+
+This rule warns when:
+
+- an `expect` is given a promise-like value but without `resolves` or `rejects`
+- an `expect` is not given a promise-like value, but is used with `resolves` or
+  `rejects`
+
+The following patterns are considered warnings:
+
+```ts
+expect('hello world').resolves.toBe('hello sunshine');
+
+expect(new Promise(r => r(0))).toThrow('oh noes!');
+```
+
+The following patterns are not considered warnings:
+
+```ts
+expect('hello world').toBe('hello sunshine');
+
+expect(new Promise(r => r(0))).rejects.toThrow('oh noes!');
+```