eslint-plugin-jest 25.3.4 → 25.7.0

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+# [25.7.0](https://github.com/jest-community/eslint-plugin-jest/compare/v25.6.0...v25.7.0) (2022-01-15)
+
+
+### Features
+
+* create `prefer-equality-matcher` rule ([#1016](https://github.com/jest-community/eslint-plugin-jest/issues/1016)) ([341353b](https://github.com/jest-community/eslint-plugin-jest/commit/341353bc7d57685cc5e0b31501d6ca336a0dbaf0))
+* **valid-expect:** support `asyncMatchers` option and default to `jest-extended` matchers ([#1018](https://github.com/jest-community/eslint-plugin-jest/issues/1018)) ([c82205a](https://github.com/jest-community/eslint-plugin-jest/commit/c82205a73a4e8de315a2ad4d413b146e27c14a34))
+
+# [25.6.0](https://github.com/jest-community/eslint-plugin-jest/compare/v25.5.0...v25.6.0) (2022-01-15)
+
+
+### Features
+
+* create `prefer-comparison-matcher` rule ([#1015](https://github.com/jest-community/eslint-plugin-jest/issues/1015)) ([eb11876](https://github.com/jest-community/eslint-plugin-jest/commit/eb118761a422b3589311113cd827a6be437f5bb5))
+
+# [25.5.0](https://github.com/jest-community/eslint-plugin-jest/compare/v25.4.0...v25.5.0) (2022-01-15)
+
+
+### Features
+
+* **prefer-expect-assertions:** support requiring only if `expect` is used in a callback ([#1028](https://github.com/jest-community/eslint-plugin-jest/issues/1028)) ([8d5fd33](https://github.com/jest-community/eslint-plugin-jest/commit/8d5fd33eed633f0c0bbdcb9e86bd2d8d7de79c4b))
+
+# [25.4.0](https://github.com/jest-community/eslint-plugin-jest/compare/v25.3.4...v25.4.0) (2022-01-15)
+
+
+### Features
+
+* **prefer-expect-assertions:** support requiring only if `expect` is used in a loop ([#1013](https://github.com/jest-community/eslint-plugin-jest/issues/1013)) ([e6f4f8a](https://github.com/jest-community/eslint-plugin-jest/commit/e6f4f8aaf7664bcf9d9d5549c3c43b1b09f49461))
+
 ## [25.3.4](https://github.com/jest-community/eslint-plugin-jest/compare/v25.3.3...v25.3.4) (2022-01-01)
 
 

package/README.md

@@ -177,6 +177,8 @@ installations requiring long-term consistency.
 | [no-test-prefixes](docs/rules/no-test-prefixes.md)                           | Use `.only` and `.skip` over `f` and `x`                            | ![recommended][] | ![fixable][] |
 | [no-test-return-statement](docs/rules/no-test-return-statement.md)           | Disallow explicitly returning from tests                            |                  |              |
 | [prefer-called-with](docs/rules/prefer-called-with.md)                       | Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`        |                  |              |
+| [prefer-comparison-matcher](docs/rules/prefer-comparison-matcher.md)         | Suggest using the built-in comparison matchers                      |                  | ![fixable][] |
+| [prefer-equality-matcher](docs/rules/prefer-equality-matcher.md)             | Suggest using the built-in equality matchers                        |                  | ![suggest][] |
 | [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md)           | Suggest using `expect.assertions()` OR `expect.hasAssertions()`     |                  | ![suggest][] |
 | [prefer-expect-resolves](docs/rules/prefer-expect-resolves.md)               | Prefer `await expect(...).resolves` over `expect(await ...)` syntax |                  | ![fixable][] |
 | [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md)                     | Suggest having hooks before any test cases                          |                  |              |

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

@@ -0,0 +1,55 @@
+# Suggest using the built-in comparison matchers (`prefer-comparison-matcher`)
+
+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-equality-matcher.md

@@ -0,0 +1,29 @@
+# Suggest using the built-in equality matchers (`prefer-equality-matcher`)
+
+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).toStrictEqual(thatObj);
+```

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

@@ -58,6 +58,16 @@ test('my test', () => {
 
 ## 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.
@@ -97,3 +107,119 @@ test('my test', async () => {
   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",
+      { "onlyFunctionsWithAsyncKeyword": 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(3);
+
+    client.get(`/users/${id}`, response => {
+      expect(response.status).toBe(200);
+    });
+  });
+});
+```

package/docs/rules/valid-expect.md

@@ -38,6 +38,11 @@ This rule is enabled by default.
       type: 'boolean',
       default: false,
     },
+    asyncMatchers: {
+      type: 'array',
+      items: { type: 'string' },
+      default: ['toResolve', 'toReject'],
+    },
     minArgs: {
       type: 'number',
       minimum: 1,
@@ -78,6 +83,14 @@ test('test1', async () => {
 test('test2', () => expect(Promise.resolve(2)).resolves.toBe(2));
 ```
 
+### `asyncMatchers`
+
+Allows specifying which matchers return promises, and so should be considered
+async when checking if an `expect` should be returned or awaited.
+
+By default, this has a list of all the async matchers provided by
+`jest-extended` (namely, `toResolve` and `toReject`).
+
 ### `minArgs` & `maxArgs`
 
 Enforces the minimum and maximum number of arguments that `expect` can take, and

package/lib/rules/prefer-comparison-matcher.js

@@ -0,0 +1,139 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _experimentalUtils = require("@typescript-eslint/experimental-utils");
+
+var _utils = require("./utils");
+
+const isBooleanLiteral = node => node.type === _experimentalUtils.AST_NODE_TYPES.Literal && typeof node.value === 'boolean';
+
+/**
+ * Checks if the given `ParsedExpectMatcher` is a call to one of the equality matchers,
+ * with a boolean literal as the sole argument.
+ *
+ * @example javascript
+ * toBe(true);
+ * toEqual(false);
+ *
+ * @param {ParsedExpectMatcher} matcher
+ *
+ * @return {matcher is ParsedBooleanEqualityMatcher}
+ */
+const isBooleanEqualityMatcher = matcher => (0, _utils.isParsedEqualityMatcherCall)(matcher) && isBooleanLiteral((0, _utils.followTypeAssertionChain)(matcher.arguments[0]));
+
+const isString = node => {
+  return (0, _utils.isStringNode)(node) || node.type === _experimentalUtils.AST_NODE_TYPES.TemplateLiteral;
+};
+
+const isComparingToString = expression => {
+  return isString(expression.left) || isString(expression.right);
+};
+
+const invertOperator = operator => {
+  switch (operator) {
+    case '>':
+      return '<=';
+
+    case '<':
+      return '>=';
+
+    case '>=':
+      return '<';
+
+    case '<=':
+      return '>';
+  }
+
+  return null;
+};
+
+const determineMatcher = (operator, negated) => {
+  const op = negated ? invertOperator(operator) : operator;
+
+  switch (op) {
+    case '>':
+      return 'toBeGreaterThan';
+
+    case '<':
+      return 'toBeLessThan';
+
+    case '>=':
+      return 'toBeGreaterThanOrEqual';
+
+    case '<=':
+      return 'toBeLessThanOrEqual';
+  }
+
+  return null;
+};
+
+var _default = (0, _utils.createRule)({
+  name: __filename,
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Suggest using the built-in comparison matchers',
+      recommended: false
+    },
+    messages: {
+      useToBeComparison: 'Prefer using `{{ preferredMatcher }}` instead'
+    },
+    fixable: 'code',
+    type: 'suggestion',
+    schema: []
+  },
+  defaultOptions: [],
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!(0, _utils.isExpectCall)(node)) {
+          return;
+        }
+
+        const {
+          expect: {
+            arguments: [comparison],
+            range: [, expectCallEnd]
+          },
+          matcher,
+          modifier
+        } = (0, _utils.parseExpectCall)(node);
+
+        if (!matcher || (comparison === null || comparison === void 0 ? void 0 : comparison.type) !== _experimentalUtils.AST_NODE_TYPES.BinaryExpression || isComparingToString(comparison) || !isBooleanEqualityMatcher(matcher)) {
+          return;
+        }
+
+        const preferredMatcher = determineMatcher(comparison.operator, (0, _utils.followTypeAssertionChain)(matcher.arguments[0]).value === !!modifier);
+
+        if (!preferredMatcher) {
+          return;
+        }
+
+        context.report({
+          fix(fixer) {
+            const sourceCode = context.getSourceCode();
+            return [// replace the comparison argument with the left-hand side of the comparison
+            fixer.replaceText(comparison, sourceCode.getText(comparison.left)), // replace the current matcher & modifier with the preferred matcher
+            fixer.replaceTextRange([expectCallEnd, matcher.node.range[1]], `.${preferredMatcher}`), // replace the matcher argument with the right-hand side of the comparison
+            fixer.replaceText(matcher.arguments[0], sourceCode.getText(comparison.right))];
+          },
+
+          messageId: 'useToBeComparison',
+          data: {
+            preferredMatcher
+          },
+          node: (modifier || matcher).node.property
+        });
+      }
+
+    };
+  }
+
+});
+
+exports.default = _default;

package/lib/rules/prefer-equality-matcher.js

@@ -0,0 +1,98 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _experimentalUtils = require("@typescript-eslint/experimental-utils");
+
+var _utils = require("./utils");
+
+const isBooleanLiteral = node => node.type === _experimentalUtils.AST_NODE_TYPES.Literal && typeof node.value === 'boolean';
+
+/**
+ * Checks if the given `ParsedExpectMatcher` is a call to one of the equality matchers,
+ * with a boolean literal as the sole argument.
+ *
+ * @example javascript
+ * toBe(true);
+ * toEqual(false);
+ *
+ * @param {ParsedExpectMatcher} matcher
+ *
+ * @return {matcher is ParsedBooleanEqualityMatcher}
+ */
+const isBooleanEqualityMatcher = matcher => (0, _utils.isParsedEqualityMatcherCall)(matcher) && isBooleanLiteral((0, _utils.followTypeAssertionChain)(matcher.arguments[0]));
+
+var _default = (0, _utils.createRule)({
+  name: __filename,
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Suggest using the built-in equality matchers',
+      recommended: false,
+      suggestion: true
+    },
+    messages: {
+      useEqualityMatcher: 'Prefer using one of the equality matchers instead',
+      suggestEqualityMatcher: 'Use `{{ equalityMatcher }}`'
+    },
+    hasSuggestions: true,
+    type: 'suggestion',
+    schema: []
+  },
+  defaultOptions: [],
+
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (!(0, _utils.isExpectCall)(node)) {
+          return;
+        }
+
+        const {
+          expect: {
+            arguments: [comparison],
+            range: [, expectCallEnd]
+          },
+          matcher,
+          modifier
+        } = (0, _utils.parseExpectCall)(node);
+
+        if (!matcher || (comparison === null || comparison === void 0 ? void 0 : comparison.type) !== _experimentalUtils.AST_NODE_TYPES.BinaryExpression || comparison.operator !== '===' && comparison.operator !== '!==' || !isBooleanEqualityMatcher(matcher)) {
+          return;
+        }
+
+        const matcherValue = (0, _utils.followTypeAssertionChain)(matcher.arguments[0]).value; // we need to negate the expectation if the current expected
+        // value is itself negated by the "not" modifier
+
+        const addNotModifier = (comparison.operator === '!==' ? !matcherValue : matcherValue) === !!modifier;
+
+        const buildFixer = equalityMatcher => fixer => {
+          const sourceCode = context.getSourceCode();
+          return [// replace the comparison argument with the left-hand side of the comparison
+          fixer.replaceText(comparison, sourceCode.getText(comparison.left)), // replace the current matcher & modifier with the preferred matcher
+          fixer.replaceTextRange([expectCallEnd, matcher.node.range[1]], addNotModifier ? `.${_utils.ModifierName.not}.${equalityMatcher}` : `.${equalityMatcher}`), // replace the matcher argument with the right-hand side of the comparison
+          fixer.replaceText(matcher.arguments[0], sourceCode.getText(comparison.right))];
+        };
+
+        context.report({
+          messageId: 'useEqualityMatcher',
+          suggest: ['toBe', 'toEqual', 'toStrictEqual'].map(equalityMatcher => ({
+            messageId: 'suggestEqualityMatcher',
+            data: {
+              equalityMatcher
+            },
+            fix: buildFixer(equalityMatcher)
+          })),
+          node: (modifier || matcher).node.property
+        });
+      }
+
+    };
+  }
+
+});
+
+exports.default = _default;

package/lib/rules/prefer-expect-assertions.js

@@ -45,18 +45,94 @@ var _default = (0, _utils.createRule)({
       properties: {
         onlyFunctionsWithAsyncKeyword: {
           type: 'boolean'
+        },
+        onlyFunctionsWithExpectInLoop: {
+          type: 'boolean'
+        },
+        onlyFunctionsWithExpectInCallback: {
+          type: 'boolean'
         }
       },
       additionalProperties: false
     }]
   },
   defaultOptions: [{
-    onlyFunctionsWithAsyncKeyword: false
+    onlyFunctionsWithAsyncKeyword: false,
+    onlyFunctionsWithExpectInLoop: false,
+    onlyFunctionsWithExpectInCallback: false
   }],
 
   create(context, [options]) {
+    let expressionDepth = 0;
+    let hasExpectInCallback = false;
+    let hasExpectInLoop = false;
+    let inTestCaseCall = false;
+    let inForLoop = false;
+
+    const shouldCheckFunction = testFunction => {
+      if (!options.onlyFunctionsWithAsyncKeyword && !options.onlyFunctionsWithExpectInLoop && !options.onlyFunctionsWithExpectInCallback) {
+        return true;
+      }
+
+      if (options.onlyFunctionsWithAsyncKeyword) {
+        if (testFunction.async) {
+          return true;
+        }
+      }
+
+      if (options.onlyFunctionsWithExpectInLoop) {
+        if (hasExpectInLoop) {
+          return true;
+        }
+      }
+
+      if (options.onlyFunctionsWithExpectInCallback) {
+        if (hasExpectInCallback) {
+          return true;
+        }
+      }
+
+      return false;
+    };
+
+    const enterExpression = () => inTestCaseCall && expressionDepth++;
+
+    const exitExpression = () => inTestCaseCall && expressionDepth--;
+
+    const enterForLoop = () => inForLoop = true;
+
+    const exitForLoop = () => inForLoop = false;
+
     return {
+      FunctionExpression: enterExpression,
+      'FunctionExpression:exit': exitExpression,
+      ArrowFunctionExpression: enterExpression,
+      'ArrowFunctionExpression:exit': exitExpression,
+      ForStatement: enterForLoop,
+      'ForStatement:exit': exitForLoop,
+      ForInStatement: enterForLoop,
+      'ForInStatement:exit': exitForLoop,
+      ForOfStatement: enterForLoop,
+      'ForOfStatement:exit': exitForLoop,
+
       CallExpression(node) {
+        if ((0, _utils.isTestCaseCall)(node)) {
+          inTestCaseCall = true;
+          return;
+        }
+
+        if ((0, _utils.isExpectCall)(node) && inTestCaseCall) {
+          if (inForLoop) {
+            hasExpectInLoop = true;
+          }
+
+          if (expressionDepth > 1) {
+            hasExpectInCallback = true;
+          }
+        }
+      },
+
+      'CallExpression:exit'(node) {
         if (!(0, _utils.isTestCaseCall)(node)) {
           return;
         }
@@ -67,10 +143,16 @@ var _default = (0, _utils.createRule)({
 
         const [, testFn] = node.arguments;
 
-        if (!(0, _utils.isFunction)(testFn) || testFn.body.type !== _experimentalUtils.AST_NODE_TYPES.BlockStatement || options.onlyFunctionsWithAsyncKeyword && !testFn.async) {
+        if (!(0, _utils.isFunction)(testFn) || testFn.body.type !== _experimentalUtils.AST_NODE_TYPES.BlockStatement) {
+          return;
+        }
+
+        if (!shouldCheckFunction(testFn)) {
           return;
         }
 
+        hasExpectInLoop = false;
+        hasExpectInCallback = false;
         const testFuncBody = testFn.body.body;
 
         if (!isFirstLineExprStmt(testFuncBody)) {

package/lib/rules/valid-expect.js

@@ -71,6 +71,8 @@ const promiseArrayExceptionKey = ({
   end
 }) => `${start.line}:${start.column}-${end.line}:${end.column}`;
 
+const defaultAsyncMatchers = ['toReject', 'toResolve'];
+
 var _default = (0, _utils.createRule)({
   name: __filename,
   meta: {
@@ -96,6 +98,12 @@ var _default = (0, _utils.createRule)({
           type: 'boolean',
           default: false
         },
+        asyncMatchers: {
+          type: 'array',
+          items: {
+            type: 'string'
+          }
+        },
         minArgs: {
           type: 'number',
           minimum: 1
@@ -110,12 +118,14 @@ var _default = (0, _utils.createRule)({
   },
   defaultOptions: [{
     alwaysAwait: false,
+    asyncMatchers: defaultAsyncMatchers,
     minArgs: 1,
     maxArgs: 1
   }],
 
   create(context, [{
     alwaysAwait,
+    asyncMatchers = defaultAsyncMatchers,
     minArgs = 1,
     maxArgs = 1
   }]) {
@@ -225,8 +235,9 @@ var _default = (0, _utils.createRule)({
         }
 
         const parentNode = matcher.node.parent;
+        const shouldBeAwaited = modifier && modifier.name !== _utils.ModifierName.not || asyncMatchers.includes(matcher.name);
 
-        if (!parentNode.parent || !modifier || modifier.name === _utils.ModifierName.not) {
+        if (!parentNode.parent || !shouldBeAwaited) {
           return;
         }
         /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "25.3.4",
+  "version": "25.7.0",
   "description": "Eslint rules for Jest",
   "keywords": [
     "eslint",