eslint-plugin-jest 29.15.5 → 29.16.0

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

@@ -41,3 +41,65 @@ expect('hello world').toBe('hello sunshine');
 
 expect(new Promise(r => r(0))).rejects.toThrow('oh noes!');
 ```
+
+## Options
+
+```json
+{
+  "jest/valid-expect-with-promise": [
+    "error",
+    {
+      "checkThenables": false
+    }
+  ]
+}
+```
+
+### `checkThenables`
+
+Default: `false`
+
+A
+["Thenable"](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise#thenables)
+value is an object which has a `then` method, such as a `Promise`. Other
+Thenables include TypeScript's built-in `PromiseLike` interface and any custom
+object that happens to have a `.then()`.
+
+The `checkThenables` option triggers `valid-expect-with-promise` to also
+consider all values that satisfy the Thenable shape (a `.then()` method that
+takes two callback parameters), not just Promises. This can be useful if your
+code works with older `Promise` polyfills instead of the native `Promise` class,
+or in environments where the global `Promise` is not declared by TypeScript's
+default libraries (such as with `noLib`).
+
+Examples of **incorrect** code when `checkThenables` is `true`:
+
+```ts
+declare function createPromiseLike(): PromiseLike<string>;
+
+expect(createPromiseLike()).toBe('hello sunshine');
+
+interface MyThenable {
+  then(onFulfilled: () => void, onRejected: () => void): MyThenable;
+}
+
+declare function createMyThenable(): MyThenable;
+
+expect(createMyThenable()).toBe('hello sunshine');
+```
+
+Examples of **correct** code when `checkThenables` is `true`:
+
+```ts
+declare function createPromiseLike(): PromiseLike<string>;
+
+await expect(createPromiseLike()).resolves.toBe('hello sunshine');
+
+interface MyThenable {
+  then(onFulfilled: () => void, onRejected: () => void): MyThenable;
+}
+
+declare function createMyThenable(): MyThenable;
+
+await expect(createMyThenable()).resolves.toBe('hello sunshine');
+```

package/lib/rules/utils/ts.js

@@ -4,8 +4,16 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.isBuiltinSymbolLike = isBuiltinSymbolLike;
+exports.isThenableType = isThenableType;
 let SymbolFlags;
 let TypeFlags;
+function loadTypeScriptFlags() {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  ({
+    TypeFlags,
+    SymbolFlags
+  } = require('typescript'));
+}
 function isSymbolFromDefaultLibrary(program, symbol) {
   /* istanbul ignore next */
   const declarations = symbol.getDeclarations() ?? [];
@@ -22,11 +30,7 @@ function isSymbolFromDefaultLibrary(program, symbol) {
   return false;
 }
 function isBuiltinSymbolLike(program, type, symbolName) {
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  ({
-    TypeFlags,
-    SymbolFlags
-  } = require('typescript'));
+  loadTypeScriptFlags();
   return isBuiltinSymbolLikeRecurser(program, type, subType => {
     const symbol = subType.getSymbol();
     if (!symbol) {
@@ -39,6 +43,33 @@ function isBuiltinSymbolLike(program, type, symbolName) {
     return null;
   });
 }
+
+/**
+ * Checks if the given type is thenable: it has a `then` method that accepts
+ * both a fulfillment and a rejection callback, mirroring the check performed
+ * by typescript-eslint's `no-floating-promises` rule.
+ */
+function isThenableType(program, node, type) {
+  loadTypeScriptFlags();
+  const checker = program.getTypeChecker();
+  return isBuiltinSymbolLikeRecurser(program, type, subType => {
+    const then = subType.getProperty('then');
+    if (!then) {
+      return false;
+    }
+    return unionParts(checker.getTypeOfSymbolAtLocation(then, node)).some(thenType => thenType.getCallSignatures().some(signature => {
+      const [onFulfilled, onRejected] = signature.getParameters();
+      return onFulfilled !== undefined && onRejected !== undefined && isFunctionParam(checker, node, onFulfilled) && isFunctionParam(checker, node, onRejected);
+    }));
+  });
+}
+function isFunctionParam(checker, node, param) {
+  const paramType = checker.getApparentType(checker.getTypeOfSymbolAtLocation(param, node));
+  return unionParts(paramType).some(subType => subType.getCallSignatures().length > 0);
+}
+function unionParts(type) {
+  return type.isUnion() ? type.types : [type];
+}
 function isBuiltinSymbolLikeRecurser(program, type, predicate) {
   if (type.isIntersection()) {
     return type.types.some(t => isBuiltinSymbolLikeRecurser(program, t, predicate));

package/lib/rules/valid-expect-with-promise.js

@@ -18,10 +18,22 @@ var _default = exports.default = (0, _utils2.createRule)({
       unneededRejectResolve: 'Subject is not a promise so {{ modifier }} is not needed'
     },
     type: 'suggestion',
-    schema: []
+    schema: [{
+      type: 'object',
+      properties: {
+        checkThenables: {
+          type: 'boolean'
+        }
+      },
+      additionalProperties: false
+    }]
   },
-  defaultOptions: [],
-  create(context) {
+  defaultOptions: [{
+    checkThenables: false
+  }],
+  create(context, [{
+    checkThenables
+  }]) {
     const services = _utils.ESLintUtils.getParserServices(context);
     return {
       CallExpression(node) {
@@ -30,7 +42,12 @@ var _default = exports.default = (0, _utils2.createRule)({
           return;
         }
         const [argument] = jestFnCall.head.node.parent.arguments;
-        const isPromiseLike = (0, _utils2.isBuiltinSymbolLike)(services.program, services.getTypeAtLocation(argument), 'Promise');
+        const argumentType = services.getTypeAtLocation(argument);
+
+        // `isBuiltinSymbolLike` only recognises the `Promise` declared in
+        // TypeScript's default libraries, so optionally check for any thenable
+        // (e.g. custom promise types in `noLib` environments, or polyfills)
+        const isPromiseLike = (0, _utils2.isBuiltinSymbolLike)(services.program, argumentType, 'Promise') || checkThenables === true && (0, _utils2.isThenableType)(services.program, services.esTreeNodeToTSNodeMap.get(argument), argumentType);
         const promiseModifier = jestFnCall.modifiers.find(nod => (0, _utils2.getAccessorValue)(nod) !== 'not');
         if (isPromiseLike && !promiseModifier) {
           context.report({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-jest",
-  "version": "29.15.5",
+  "version": "29.16.0",
   "description": "ESLint rules for Jest",
   "keywords": [
     "eslint",
@@ -138,7 +138,7 @@
       "optional": true
     }
   },
-  "packageManager": "yarn@4.17.0",
+  "packageManager": "yarn@4.17.1",
   "engines": {
     "node": "^20.12.0 || ^22.0.0 || >=24.0.0"
   }