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

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

@@ -0,0 +1,142 @@
+# jest/no-conditional-expect
+
+📝 Disallow calling `expect` conditionally.
+
+💼 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 -->
+
+This rule prevents the use of `expect` in conditional blocks, such as `if`s &
+`catch`s.
+
+This includes using `expect` in callbacks to functions named `catch`, which are
+assumed to be promises.
+
+## Rule details
+
+Jest only considers a test to have failed if it throws an error, meaning if
+calls to assertion functions like `expect` occur in conditional code such as a
+`catch` statement, tests can end up passing but not actually test anything.
+
+Additionally, conditionals tend to make tests more brittle and complex, as they
+increase the amount of mental thinking needed to understand what is actually
+being tested.
+
+While `expect.assertions` & `expect.hasAssertions` can help prevent tests from
+silently being skipped, when combined with conditionals they typically result in
+even more complexity being introduced.
+
+The following patterns are warnings:
+
+```js
+it('foo', () => {
+  doTest && expect(1).toBe(2);
+});
+
+it('bar', () => {
+  if (!skipTest) {
+    expect(1).toEqual(2);
+  }
+});
+
+it('baz', async () => {
+  try {
+    await foo();
+  } catch (err) {
+    expect(err).toMatchObject({ code: 'MODULE_NOT_FOUND' });
+  }
+});
+
+it('throws an error', async () => {
+  await foo().catch(error => expect(error).toBeInstanceOf(error));
+});
+```
+
+The following patterns are not warnings:
+
+```js
+it('foo', () => {
+  expect(!value).toBe(false);
+});
+
+function getValue() {
+  if (process.env.FAIL) {
+    return 1;
+  }
+
+  return 2;
+}
+
+it('foo', () => {
+  expect(getValue()).toBe(2);
+});
+
+it('validates the request', () => {
+  try {
+    processRequest(request);
+  } catch {
+    // ignore errors
+  } finally {
+    expect(validRequest).toHaveBeenCalledWith(request);
+  }
+});
+
+it('throws an error', async () => {
+  await expect(foo).rejects.toThrow(Error);
+});
+```
+
+### How to catch a thrown error for testing without violating this rule
+
+A common situation that comes up with this rule is when wanting to test
+properties on a thrown error, as Jest's `toThrow` matcher only checks the
+`message` property.
+
+Most people write something like this:
+
+```typescript
+describe('when the http request fails', () => {
+  it('includes the status code in the error', async () => {
+    try {
+      await makeRequest(url);
+    } catch (error) {
+      expect(error).toHaveProperty('statusCode', 404);
+    }
+  });
+});
+```
+
+As stated above, the problem with this is that if `makeRequest()` doesn't throw
+the test will still pass as if the `expect` had been called.
+
+While you can use `expect.assertions` & `expect.hasAssertions` for these
+situations, they only work with `expect`.
+
+A better way to handle this situation is to introduce a wrapper to handle the
+catching, and otherwise return a specific "no error thrown" error if nothing is
+thrown by the wrapped function:
+
+```typescript
+class NoErrorThrownError extends Error {}
+
+const getError = async <TError>(call: () => unknown): Promise<TError> => {
+  try {
+    await call();
+
+    throw new NoErrorThrownError();
+  } catch (error: unknown) {
+    return error as TError;
+  }
+};
+
+describe('when the http request fails', () => {
+  it('includes the status code in the error', async () => {
+    const error = await getError(async () => makeRequest(url));
+
+    // check that the returned error wasn't that no error was thrown
+    expect(error).not.toBeInstanceOf(NoErrorThrownError);
+    expect(error).toHaveProperty('statusCode', 404);
+  });
+});
+```

package/docs/rules/no-conditional-in-test.md

@@ -0,0 +1,123 @@
+# jest/no-conditional-in-test
+
+📝 Disallow conditional logic in tests.
+
+<!-- end auto-generated rule header -->
+
+Conditional logic in tests is usually an indication that a test is attempting to
+cover too much, and not testing the logic it intends to. Each branch of code
+executing within a conditional statement will usually be better served by a test
+devoted to it.
+
+## Rule details
+
+This rule reports on any use of a conditional statement such as `if`, `switch`,
+and ternary expressions.
+
+Examples of **incorrect** code for this rule:
+
+```js
+it('foo', () => {
+  if (true) {
+    doTheThing();
+  }
+});
+
+it('bar', () => {
+  switch (mode) {
+    case 'none':
+      generateNone();
+    case 'single':
+      generateOne();
+    case 'multiple':
+      generateMany();
+  }
+
+  expect(fixtures.length).toBeGreaterThan(-1);
+});
+
+it('qux', async () => {
+  const promiseValue = () => {
+    return something instanceof Promise
+      ? something
+      : Promise.resolve(something);
+  };
+
+  await expect(promiseValue()).resolves.toBe(1);
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+describe('my tests', () => {
+  if (true) {
+    it('foo', () => {
+      doTheThing();
+    });
+  }
+});
+
+beforeEach(() => {
+  switch (mode) {
+    case 'none':
+      generateNone();
+    case 'single':
+      generateOne();
+    case 'multiple':
+      generateMany();
+  }
+});
+
+it('bar', () => {
+  expect(fixtures.length).toBeGreaterThan(-1);
+});
+
+const promiseValue = something => {
+  return something instanceof Promise ? something : Promise.resolve(something);
+};
+
+it('qux', async () => {
+  await expect(promiseValue()).resolves.toBe(1);
+});
+```
+
+## Options
+
+```json
+{
+  "jest/no-conditional-in-test": [
+    "error",
+    {
+      "allowOptionalChaining": true
+    }
+  ]
+}
+```
+
+### `allowOptionalChaining`
+
+Default: `true`
+
+When set to `false`, optional chaining (`?.`) inside test bodies will be
+reported as a conditional.
+
+Examples of **incorrect** code when `allowOptionalChaining` is `false`:
+
+```js
+it('foo', () => {
+  const value = obj?.bar;
+});
+
+it('bar', () => {
+  obj?.foo();
+});
+```
+
+Examples of **correct** code when `allowOptionalChaining` is `false`:
+
+```js
+it('foo', () => {
+  const value = obj!.bar;
+});
+```

package/docs/rules/no-confusing-set-timeout.md

@@ -0,0 +1,64 @@
+# jest/no-confusing-set-timeout
+
+📝 Disallow confusing usages of jest.setTimeout.
+
+<!-- end auto-generated rule header -->
+
+While `jest.setTimeout` can be called multiple times anywhere within a single
+test file only the last call before any test functions run will have an effect.
+
+## Rule details
+
+this rule checks for several confusing usages of `jest.setTimeout` that looks
+like it applies to specific tests within the same file, such as:
+
+- being called anywhere other than in global scope
+- being called multiple times
+- being called after other Jest functions like hooks, `describe`, `test`, or
+  `it`
+
+Examples of **incorrect** code for this rule:
+
+```js
+describe('test foo', () => {
+  jest.setTimeout(1000);
+  it('test-description', () => {
+    // test logic;
+  });
+});
+
+describe('test bar', () => {
+  it('test-description', () => {
+    jest.setTimeout(1000);
+    // test logic;
+  });
+});
+
+test('foo-bar', () => {
+  jest.setTimeout(1000);
+});
+
+describe('unit test', () => {
+  beforeEach(() => {
+    jest.setTimeout(1000);
+  });
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+jest.setTimeout(500);
+test('test test', () => {
+  // do some stuff
+});
+```
+
+```js
+jest.setTimeout(1000);
+describe('test bar bar', () => {
+  it('test-description', () => {
+    // test logic;
+  });
+});
+```

package/docs/rules/no-deprecated-functions.md

@@ -0,0 +1,59 @@
+# jest/no-deprecated-functions
+
+📝 Disallow use of deprecated functions.
+
+💼 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 -->
+
+Over the years Jest has accrued some debt in the form of functions that have
+either been renamed for clarity, or replaced with more powerful APIs.
+
+While typically these deprecated functions are kept in the codebase for a number
+of majors, eventually they are removed completely.
+
+This rule requires knowing which version of Jest you're using - see
+[this section of the readme](../../README.md#jest-version-setting) for details
+on how that is obtained automatically and how you can explicitly provide a
+version if needed.
+
+## Rule details
+
+This rule warns about calls to deprecated functions, and provides details on
+what to replace them with, based on the version of Jest that is installed.
+
+This rule can also autofix a number of these deprecations for you.
+
+### `jest.resetModuleRegistry`
+
+This function was renamed to `resetModules` in Jest 15 and removed in Jest 27.
+
+### `jest.addMatchers`
+
+This function was replaced with `expect.extend` in Jest 17 and removed in
+Jest 27.
+
+### `require.requireActual` & `require.requireMock`
+
+These functions were replaced in Jest 21 and removed in Jest 26.
+
+Originally, the `requireActual` & `requireMock` the `requireActual`&
+`requireMock` functions were placed onto the `require` function.
+
+These functions were later moved onto the `jest` object in order to be easier
+for type checkers to handle, and their use via `require` deprecated. Finally,
+the release of Jest 26 saw them removed from the `require` function altogether.
+
+### `jest.runTimersToTime`
+
+This function was renamed to `advanceTimersByTime` in Jest 22 and removed in
+Jest 27.
+
+### `jest.genMockFromModule`
+
+This function was renamed to `createMockFromModule` in Jest 26, and removed in
+Jest 30.

package/docs/rules/no-disabled-tests.md

@@ -0,0 +1,72 @@
+# jest/no-disabled-tests
+
+📝 Disallow disabled tests.
+
+⚠️ This rule _warns_ in the ✅ `recommended`
+[config](https://github.com/jest-community/eslint-plugin-jest/blob/main/README.md#shareable-configurations).
+
+<!-- end auto-generated rule header -->
+
+Jest has a feature that allows you to temporarily mark tests as disabled. This
+feature is often helpful while debugging or to create placeholders for future
+tests. Before committing changes we may want to check that all tests are
+running.
+
+This rule raises a warning about disabled tests.
+
+## Rule details
+
+There are a number of ways to disable tests in Jest:
+
+- by appending `.skip` to the test-suite or test-case
+- by prepending the test function name with `x`
+- by declaring a test with a name but no function body
+- by making a call to `pending()` anywhere within the test
+
+The following patterns are considered warnings:
+
+```js
+describe.skip('foo', () => {});
+it.skip('foo', () => {});
+test.skip('foo', () => {});
+
+describe['skip']('bar', () => {});
+it['skip']('bar', () => {});
+test['skip']('bar', () => {});
+
+xdescribe('foo', () => {});
+xit('foo', () => {});
+xtest('foo', () => {});
+
+it('bar');
+test('bar');
+
+it('foo', () => {
+  pending();
+});
+```
+
+These patterns would not be considered warnings:
+
+```js
+describe('foo', () => {});
+it('foo', () => {});
+test('foo', () => {});
+
+describe.only('bar', () => {});
+it.only('bar', () => {});
+test.only('bar', () => {});
+```
+
+### Limitations
+
+The plugin looks at the literal function names within test code, so will not
+catch more complex examples of disabled tests, such as:
+
+```js
+const testSkip = test.skip;
+testSkip('skipped test', () => {});
+
+const myTest = test;
+myTest('does not have function body');
+```

package/docs/rules/no-done-callback.md

@@ -0,0 +1,100 @@
+# jest/no-done-callback
+
+📝 Disallow using a callback in asynchronous tests and hooks.
+
+💼 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 manually fixable by
+[editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
+
+<!-- end auto-generated rule header -->
+
+When calling asynchronous code in hooks and tests, `jest` needs to know when the
+asynchronous work is complete to progress the current run.
+
+Originally the most common pattern to achieve this was to use callbacks:
+
+```js
+test('the data is peanut butter', done => {
+  function callback(data) {
+    try {
+      expect(data).toBe('peanut butter');
+      done();
+    } catch (error) {
+      done(error);
+    }
+  }
+
+  fetchData(callback);
+});
+```
+
+This can be very error-prone however, as it requires careful understanding of
+how assertions work in tests or otherwise tests won't behave as expected.
+
+For example, if the `try/catch` was left out of the above code, the test would
+time out rather than fail. Even with the `try/catch`, forgetting to pass the
+caught error to `done` will result in `jest` believing the test has passed.
+
+A more straightforward way to handle asynchronous code is to use Promises:
+
+```js
+test('the data is peanut butter', () => {
+  return fetchData().then(data => {
+    expect(data).toBe('peanut butter');
+  });
+});
+```
+
+When a test or hook returns a promise, `jest` waits for that promise to resolve,
+as well as automatically failing should the promise reject.
+
+If your environment supports `async/await`, this becomes even simpler:
+
+```js
+test('the data is peanut butter', async () => {
+  const data = await fetchData();
+  expect(data).toBe('peanut butter');
+});
+```
+
+## Rule details
+
+This rule checks the function parameter of hooks & tests for use of the `done`
+argument, suggesting you return a promise instead.
+
+The following patterns are considered warnings:
+
+```js
+beforeEach(done => {
+  // ...
+});
+
+test('myFunction()', done => {
+  // ...
+});
+
+test('myFunction()', function (done) {
+  // ...
+});
+```
+
+The following patterns are not considered warnings:
+
+```js
+beforeEach(async () => {
+  await setupUsTheBomb();
+});
+
+test('myFunction()', () => {
+  expect(myFunction()).toBeTruthy();
+});
+
+test('myFunction()', () => {
+  return new Promise(done => {
+    expect(myFunction()).toBeTruthy();
+    done();
+  });
+});
+```

package/docs/rules/no-duplicate-hooks.md

@@ -0,0 +1,79 @@
+# jest/no-duplicate-hooks
+
+📝 Disallow duplicate setup and teardown hooks.
+
+<!-- end auto-generated rule header -->
+
+A `describe` block should not contain duplicate hooks.
+
+## Rule details
+
+Examples of **incorrect** code for this rule
+
+```js
+/* eslint jest/no-duplicate-hooks: "error" */
+
+describe('foo', () => {
+  beforeEach(() => {
+    // some setup
+  });
+  beforeEach(() => {
+    // some setup
+  });
+  test('foo_test', () => {
+    // some test
+  });
+});
+
+// Nested describe scenario
+describe('foo', () => {
+  beforeEach(() => {
+    // some setup
+  });
+  test('foo_test', () => {
+    // some test
+  });
+  describe('bar', () => {
+    test('bar_test', () => {
+      afterAll(() => {
+        // some teardown
+      });
+      afterAll(() => {
+        // some teardown
+      });
+    });
+  });
+});
+```
+
+Examples of **correct** code for this rule
+
+```js
+/* eslint jest/no-duplicate-hooks: "error" */
+
+describe('foo', () => {
+  beforeEach(() => {
+    // some setup
+  });
+  test('foo_test', () => {
+    // some test
+  });
+});
+
+// Nested describe scenario
+describe('foo', () => {
+  beforeEach(() => {
+    // some setup
+  });
+  test('foo_test', () => {
+    // some test
+  });
+  describe('bar', () => {
+    test('bar_test', () => {
+      beforeEach(() => {
+        // some setup
+      });
+    });
+  });
+});
+```

package/docs/rules/no-error-equal.md

@@ -0,0 +1,37 @@
+# jest/no-error-equal
+
+📝 Disallow using equality matchers on error types.
+
+💭 This rule requires
+[type information](https://typescript-eslint.io/linting/typed-linting).
+
+<!-- end auto-generated rule header -->
+
+When comparing errors, `toEqual` and `toStrictEqual` will only compare the
+`message` properties, meaning tests can pass even if the errors are of different
+types.
+
+Instead, it is better to use `toThrow` which does check the error type along
+with its message.
+
+## Rule details
+
+This rule warns when `toEqual` and `toStrictEqual` is used with an `Error` type.
+
+The following patterns are considered warnings:
+
+```ts
+expect(new AggregateError([], expect.any(String))).toEqual(
+  new Error(expect.any(String)),
+);
+
+expect(new Error('hello world')).toStrictEqual('hello sunshine');
+```
+
+The following patterns are not considered warnings:
+
+```ts
+expect(() => throw new AggregateError([], expect.any(String))).toThrow(new Error(expect.any(String)));
+
+expect(() => throw new Error('hello world')).toThrow('hello sunshine');
+```