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

package/docs/rules/padding-around-expect-groups.md

@@ -0,0 +1,44 @@
+# jest/padding-around-expect-groups
+
+📝 Enforce padding around `expect` groups.
+
+🔧 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 `expect`
+statements
+
+Note that it doesn't add/enforce a padding line if it's the last statement in
+its scope and it doesn't add/enforce padding between two or more adjacent
+`expect` statements.
+
+Examples of **incorrect** code for this rule:
+
+```js
+test('thing one', () => {
+  let abc = 123;
+  expect(abc).toEqual(123);
+  expect(123).toEqual(abc);
+  abc = 456;
+  expect(abc).toEqual(456);
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+test('thing one', () => {
+  let abc = 123;
+
+  expect(abc).toEqual(123);
+  expect(123).toEqual(abc);
+
+  abc = 456;
+
+  expect(abc).toEqual(456);
+});
+```

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

@@ -0,0 +1,48 @@
+# jest/padding-around-test-blocks
+
+📝 Enforce padding around `test` and `it` 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 `test`/`it`
+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;
+test('foo', () => {});
+test('bar', () => {});
+```
+
+```js
+const thing = 123;
+it('foo', () => {});
+it('bar', () => {});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const thing = 123;
+
+test('foo', () => {});
+
+test('bar', () => {});
+```
+
+```js
+const thing = 123;
+
+it('foo', () => {});
+
+it('bar', () => {});
+```

package/docs/rules/prefer-called-with.md

@@ -0,0 +1,39 @@
+# jest/prefer-called-with
+
+📝 Suggest using `toHaveBeenCalledWith()`.
+
+<!-- end auto-generated rule header -->
+
+The `toHaveBeenCalled()` matcher is used to assert that a mock function has been
+called one or more times, without checking the arguments passed. The assertion
+is stronger when arguments are also validated using the `toHaveBeenCalledWith()`
+matcher. When some arguments are difficult to check, using generic match like
+`expect.anything()` at least enforces number and position of arguments.
+
+This rule warns if the form without argument checking is used, except for `.not`
+enforcing a function has never been called.
+
+## Rule details
+
+The following patterns are warnings:
+
+```js
+expect(someFunction).toBeCalled();
+
+expect(someFunction).toHaveBeenCalled();
+```
+
+The following patterns are not warnings:
+
+```js
+expect(noArgsFunction).toHaveBeenCalledWith();
+
+expect(roughArgsFunction).toHaveBeenCalledWith(
+  expect.anything(),
+  expect.any(Date),
+);
+
+expect(anyArgsFunction).toHaveBeenCalledTimes(1);
+
+expect(uncalledFunction).not.toHaveBeenCalled();
+```

package/docs/rules/prefer-comparison-matcher.md

@@ -0,0 +1,62 @@
+# jest/prefer-comparison-matcher
+
+📝 Suggest using the built-in comparison matchers.
+
+🔧 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 has a number of built-in matchers for comparing numbers, which allow for
+more readable tests and error messages if an expectation fails.
+
+## Rule details
+
+This rule checks for comparisons in tests that could be replaced with one of the
+following built-in comparison matchers:
+
+- `toBeGreaterThan`
+- `toBeGreaterThanOrEqual`
+- `toBeLessThan`
+- `toBeLessThanOrEqual`
+
+Examples of **incorrect** code for this rule:
+
+```js
+expect(x > 5).toBe(true);
+expect(x < 7).not.toEqual(true);
+expect(x <= y).toStrictEqual(true);
+```
+
+Examples of **correct** code for this rule:
+
+```js
+expect(x).toBeGreaterThan(5);
+expect(x).not.toBeLessThanOrEqual(7);
+expect(x).toBeLessThanOrEqual(y);
+
+// special case - see below
+expect(x < 'Carl').toBe(true);
+```
+
+Note that these matchers only work with numbers and bigints, and that the rule
+assumes that any variables on either side of the comparison operator are of one
+of those types - this means if you're using the comparison operator with
+strings, the fix applied by this rule will result in an error.
+
+```js
+expect(myName).toBeGreaterThanOrEqual(theirName); // Matcher error: received value must be a number or bigint
+```
+
+The reason for this is that comparing strings with these operators is expected
+to be very rare and would mean not being able to have an automatic fixer for
+this rule.
+
+If for some reason you are using these operators to compare strings, you can
+disable this rule using an inline
+[configuration comment](https://eslint.org/docs/user-guide/configuring/rules#disabling-rules):
+
+```js
+// eslint-disable-next-line jest/prefer-comparison-matcher
+expect(myName > theirName).toBe(true);
+```

package/docs/rules/prefer-each.md

@@ -0,0 +1,58 @@
+# jest/prefer-each
+
+📝 Prefer using `.each` rather than manual loops.
+
+<!-- end auto-generated rule header -->
+
+Reports where you might be able to use `.each` instead of native loops.
+
+## Rule details
+
+This rule triggers a warning if you use test case functions like `describe`,
+`test`, and `it`, in a native loop - generally you should be able to use `.each`
+instead which gives better output and makes it easier to run specific cases.
+
+Examples of **incorrect** code for this rule:
+
+```js
+for (const number of getNumbers()) {
+  it('is greater than five', function () {
+    expect(number).toBeGreaterThan(5);
+  });
+}
+
+for (const [input, expected] of data) {
+  beforeEach(() => setupSomething(input));
+
+  test(`results in ${expected}`, () => {
+    expect(doSomething()).toBe(expected);
+  });
+}
+```
+
+Examples of **correct** code for this rule:
+
+```js
+it.each(getNumbers())(
+  'only returns numbers that are greater than seven',
+  number => {
+    expect(number).toBeGreaterThan(7);
+  },
+);
+
+describe.each(data)('when input is %s', ([input, expected]) => {
+  beforeEach(() => setupSomething(input));
+
+  test(`results in ${expected}`, () => {
+    expect(doSomething()).toBe(expected);
+  });
+});
+
+// we don't warn on loops _in_ test functions because those typically involve
+// complex setup that is better done in the test function itself
+it('returns numbers that are greater than five', () => {
+  for (const number of getNumbers()) {
+    expect(number).toBeGreaterThan(5);
+  }
+});
+```

package/docs/rules/prefer-ending-with-an-expect.md

@@ -0,0 +1,170 @@
+# jest/prefer-ending-with-an-expect
+
+📝 Prefer having the last statement in a test be an assertion.
+
+<!-- end auto-generated rule header -->
+
+Prefer ending tests with an `expect` assertion.
+
+## Rule details
+
+This rule triggers when a test body does not end with an `expect` call, which
+can indicate an unfinished test.
+
+Examples of **incorrect** code for this rule:
+
+```js
+it('lets me change the selected option', () => {
+  const container = render(MySelect, {
+    props: { options: [1, 2, 3], selected: 1 },
+  });
+
+  expect(container).toBeDefined();
+  expect(container.toHTML()).toContain('<option value="1" selected>');
+
+  container.setProp('selected', 2);
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+it('lets me change the selected option', () => {
+  const container = render(MySelect, {
+    props: { options: [1, 2, 3], selected: 1 },
+  });
+
+  expect(container).toBeDefined();
+  expect(container.toHTML()).toContain('<option value="1" selected>');
+
+  container.setProp('selected', 2);
+
+  expect(container.toHTML()).not.toContain('<option value="1" selected>');
+  expect(container.toHTML()).toContain('<option value="2" selected>');
+});
+```
+
+## Options
+
+```json
+{
+  "jest/prefer-ending-with-an-expect": [
+    "error",
+    {
+      "assertFunctionNames": ["expect"],
+      "additionalTestBlockFunctions": []
+    }
+  ]
+}
+```
+
+### `assertFunctionNames`
+
+This array option specifies the names of functions that should be considered to
+be asserting functions. Function names can use wildcards i.e `request.*.expect`,
+`request.**.expect`, `request.*.expect*`
+
+Examples of **incorrect** code for the `{ "assertFunctionNames": ["expect"] }`
+option:
+
+```js
+/* eslint jest/prefer-ending-with-an-expect: ["error", { "assertFunctionNames": ["expect"] }] */
+
+import { expectSaga } from 'redux-saga-test-plan';
+import { addSaga } from '../src/sagas';
+
+test('returns sum', () => {
+  expectSaga(addSaga, 1, 1).returns(2).run();
+});
+```
+
+Examples of **correct** code for the
+`{ "assertFunctionNames": ["expect", "expectSaga"] }` option:
+
+```js
+/* eslint jest/prefer-ending-with-an-expect: ["error", { "assertFunctionNames": ["expect", "expectSaga"] }] */
+
+import { expectSaga } from 'redux-saga-test-plan';
+import { addSaga } from '../src/sagas';
+
+test('returns sum', () => {
+  expectSaga(addSaga, 1, 1).returns(2).run();
+});
+```
+
+Since the string is compiled into a regular expression, you'll need to escape
+special characters such as `$` with a double backslash:
+
+```js
+/* eslint jest/prefer-ending-with-an-expect: ["error", { "assertFunctionNames": ["expect\\$"] }] */
+
+it('is money-like', () => {
+  expect$(1.0);
+});
+```
+
+Examples of **correct** code for working with the HTTP assertions library
+[SuperTest](https://www.npmjs.com/package/supertest) with the
+`{ "assertFunctionNames": ["expect", "request.**.expect"] }` option:
+
+```js
+/* eslint jest/prefer-ending-with-an-expect: ["error", { "assertFunctionNames": ["expect", "request.**.expect"] }] */
+const request = require('supertest');
+const express = require('express');
+
+const app = express();
+
+describe('GET /user', function () {
+  it('responds with json', function (done) {
+    doSomething();
+
+    request(app).get('/user').expect('Content-Type', /json/).expect(200, done);
+  });
+});
+```
+
+### `additionalTestBlockFunctions`
+
+This array can be used to specify the names of functions that should also be
+treated as test blocks:
+
+```json
+{
+  "rules": {
+    "jest/prefer-ending-with-an-expect": [
+      "error",
+      { "additionalTestBlockFunctions": ["each.test"] }
+    ]
+  }
+}
+```
+
+The following is _correct_ when using the above configuration:
+
+```js
+each([
+  [2, 3],
+  [1, 3],
+]).test(
+  'the selection can change from %d to %d',
+  (firstSelection, secondSelection) => {
+    const container = render(MySelect, {
+      props: { options: [1, 2, 3], selected: firstSelection },
+    });
+
+    expect(container).toBeDefined();
+    expect(container.toHTML()).toContain(
+      `<option value="${firstSelection}" selected>`,
+    );
+
+    container.setProp('selected', secondSelection);
+
+    expect(container.toHTML()).not.toContain(
+      `<option value="${firstSelection}" selected>`,
+    );
+    expect(container.toHTML()).toContain(
+      `<option value="${secondSelection}" selected>`,
+    );
+  },
+);
+```

package/docs/rules/prefer-equality-matcher.md

@@ -0,0 +1,36 @@
+# jest/prefer-equality-matcher
+
+📝 Suggest using the built-in equality matchers.
+
+💡 This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
+
+<!-- end auto-generated rule header -->
+
+Jest has built-in matchers for expecting equality, which allow for more readable
+tests and error messages if an expectation fails.
+
+## Rule details
+
+This rule checks for _strict_ equality checks (`===` & `!==`) in tests that
+could be replaced with one of the following built-in equality matchers:
+
+- `toBe`
+- `toEqual`
+- `toStrictEqual`
+
+Examples of **incorrect** code for this rule:
+
+```js
+expect(x === 5).toBe(true);
+expect(name === 'Carl').not.toEqual(true);
+expect(myObj !== thatObj).toStrictEqual(true);
+```
+
+Examples of **correct** code for this rule:
+
+```js
+expect(x).toBe(5);
+expect(name).not.toEqual('Carl');
+expect(myObj).not.toStrictEqual(thatObj);
+```

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

@@ -0,0 +1,230 @@
+# jest/prefer-expect-assertions
+
+📝 Suggest using `expect.assertions()` OR `expect.hasAssertions()`.
+
+💡 This rule is manually fixable by
+[editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
+
+<!-- end auto-generated rule header -->
+
+Ensure every test to have either `expect.assertions(<number of assertions>)` OR
+`expect.hasAssertions()` as its first expression.
+
+## Rule details
+
+This rule triggers a warning if,
+
+- `expect.assertions(<number of assertions>)` OR `expect.hasAssertions()` is not
+  present as first statement in a test, e.g.:
+
+```js
+test('my test', () => {
+  expect(someThing()).toEqual('foo');
+});
+```
+
+- `expect.assertions(<number of assertions>)` is the first statement in a test
+  where argument passed to `expect.assertions(<number of assertions>)` is not a
+  valid number, e.g.:
+
+```js
+test('my test', () => {
+  expect.assertions('1');
+  expect(someThing()).toEqual('foo');
+});
+```
+
+The following patterns are considered warnings:
+
+```js
+test('my test', () => {
+  expect.assertions('1');
+  expect(someThing()).toEqual('foo');
+});
+
+test('my test', () => {
+  expect(someThing()).toEqual('foo');
+});
+```
+
+The following patterns would not be considered warnings:
+
+```js
+test('my test', () => {
+  expect.assertions(1);
+  expect(someThing()).toEqual('foo');
+});
+
+test('my test', () => {
+  expect.hasAssertions();
+  expect(someThing()).toEqual('foo');
+});
+```
+
+## Options
+
+This rule can be configured to only check tests that match certain patterns that
+typically look like `expect` calls might be missed, such as in promises or
+loops.
+
+By default, none of these options are enabled meaning the rule checks _every_
+test for a call to either `expect.hasAssertions` or `expect.assertions`. If any
+of the options are enabled the rule checks any test that matches _at least one_
+of the patterns represented by the enabled options (think "OR" rather than
+"AND").
+
+#### `onlyFunctionsWithAsyncKeyword`
+
+When `true`, this rule will only warn for tests that use the `async` keyword.
+
+```json
+{
+  "rules": {
+    "jest/prefer-expect-assertions": [
+      "warn",
+      { "onlyFunctionsWithAsyncKeyword": true }
+    ]
+  }
+}
+```
+
+When `onlyFunctionsWithAsyncKeyword` option is set to `true`, the following
+pattern would be a warning:
+
+```js
+test('my test', async () => {
+  const result = await someAsyncFunc();
+  expect(result).toBe('foo');
+});
+```
+
+While the following patterns would not be considered warnings:
+
+```js
+test('my test', () => {
+  const result = someFunction();
+  expect(result).toBe('foo');
+});
+
+test('my test', async () => {
+  expect.assertions(1);
+  const result = await someAsyncFunc();
+  expect(result).toBe('foo');
+});
+```
+
+#### `onlyFunctionsWithExpectInLoop`
+
+When `true`, this rule will only warn for tests that have `expect` calls within
+a native loop.
+
+```json
+{
+  "rules": {
+    "jest/prefer-expect-assertions": [
+      "warn",
+      { "onlyFunctionsWithExpectInLoop": true }
+    ]
+  }
+}
+```
+
+Examples of **incorrect** code when `'onlyFunctionsWithExpectInLoop'` is `true`:
+
+```js
+describe('getNumbers', () => {
+  it('only returns numbers that are greater than zero', () => {
+    const numbers = getNumbers();
+
+    for (const number in numbers) {
+      expect(number).toBeGreaterThan(0);
+    }
+  });
+});
+```
+
+Examples of **correct** code when `'onlyFunctionsWithExpectInLoop'` is `true`:
+
+```js
+describe('getNumbers', () => {
+  it('only returns numbers that are greater than zero', () => {
+    expect.hasAssertions();
+
+    const numbers = getNumbers();
+
+    for (const number in numbers) {
+      expect(number).toBeGreaterThan(0);
+    }
+  });
+
+  it('returns more than one number', () => {
+    expect(getNumbers().length).toBeGreaterThan(1);
+  });
+});
+```
+
+#### `onlyFunctionsWithExpectInCallback`
+
+When `true`, this rule will only warn for tests that have `expect` calls within
+a callback.
+
+```json
+{
+  "rules": {
+    "jest/prefer-expect-assertions": [
+      "warn",
+      { "onlyFunctionsWithExpectInCallback": true }
+    ]
+  }
+}
+```
+
+Examples of **incorrect** code when `'onlyFunctionsWithExpectInCallback'` is
+`true`:
+
+```js
+describe('getNumbers', () => {
+  it('only returns numbers that are greater than zero', () => {
+    const numbers = getNumbers();
+
+    getNumbers().forEach(number => {
+      expect(number).toBeGreaterThan(0);
+    });
+  });
+});
+
+describe('/users', () => {
+  it.each([1, 2, 3])('returns ok', id => {
+    client.get(`/users/${id}`, response => {
+      expect(response.status).toBe(200);
+    });
+  });
+});
+```
+
+Examples of **correct** code when `'onlyFunctionsWithExpectInCallback'` is
+`true`:
+
+```js
+describe('getNumbers', () => {
+  it('only returns numbers that are greater than zero', () => {
+    expect.hasAssertions();
+
+    const numbers = getNumbers();
+
+    getNumbers().forEach(number => {
+      expect(number).toBeGreaterThan(0);
+    });
+  });
+});
+
+describe('/users', () => {
+  it.each([1, 2, 3])('returns ok', id => {
+    expect.assertions(1);
+
+    client.get(`/users/${id}`, response => {
+      expect(response.status).toBe(200);
+    });
+  });
+});
+```