fix(expect): expose AsymmetricMatchers and RawMatcherFn interfaces

packages/expect/__typetests__/expect.test.ts

@@ -5,12 +5,77 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {expectError} from 'tsd-lite';
-import type * as expect from 'expect';
+import {expectError, expectType} from 'tsd-lite';
+import type {EqualsFunction, Tester} from '@jest/expect-utils';
+import {type Matchers, expect} from 'expect';
+import type * as jestMatcherUtils from 'jest-matcher-utils';
 
-type M = expect.Matchers<void, unknown>;
-type N = expect.Matchers<void>;
+type M = Matchers<void, unknown>;
+type N = Matchers<void>;
 
 expectError(() => {
-  type E = expect.Matchers;
+  type E = Matchers;
 });
+
+// extend
+
+type MatcherUtils = typeof jestMatcherUtils & {
+  iterableEquality: Tester;
+  subsetEquality: Tester;
+};
+
+expectType<void>(
+  expect.extend({
+    toBeWithinRange(actual: number, floor: number, ceiling: number) {
+      expectType<number>(this.assertionCalls);
+      expectType<string | undefined>(this.currentTestName);
+      expectType<(() => void) | undefined>(this.dontThrow);
+      expectType<Error | undefined>(this.error);
+      expectType<EqualsFunction>(this.equals);
+      expectType<boolean | undefined>(this.expand);
+      expectType<number | null | undefined>(this.expectedAssertionsNumber);
+      expectType<Error | undefined>(this.expectedAssertionsNumberError);
+      expectType<boolean | undefined>(this.isExpectingAssertions);
+      expectType<Error | undefined>(this.isExpectingAssertionsError);
+      expectType<boolean>(this.isNot);
+      expectType<string>(this.promise);
+      expectType<Array<Error>>(this.suppressedErrors);
+      expectType<string | undefined>(this.testPath);
+      expectType<MatcherUtils>(this.utils);
+
+      const pass = actual >= floor && actual <= ceiling;
+      if (pass) {
+        return {
+          message: () =>
+            `expected ${actual} not to be within range ${floor} - ${ceiling}`,
+          pass: true,
+        };
+      } else {
+        return {
+          message: () =>
+            `expected ${actual} to be within range ${floor} - ${ceiling}`,
+          pass: false,
+        };
+      }
+    },
+  }),
+);
+
+declare module 'expect' {
+  interface AsymmetricMatchers {
+    toBeWithinRange(floor: number, ceiling: number): void;
+  }
+  interface Matchers<R> {
+    toBeWithinRange(floor: number, ceiling: number): void;
+  }
+}
+
+expectType<void>(expect(100).toBeWithinRange(90, 110));
+expectType<void>(expect(101).not.toBeWithinRange(0, 100));
+
+expectType<void>(
+  expect({apples: 6, bananas: 3}).toEqual({
+    apples: expect.toBeWithinRange(1, 10),
+    bananas: expect.not.toBeWithinRange(11, 20),
+  }),
+);

packages/expect/src/index.ts

@@ -49,7 +49,7 @@ import type {
   ThrowingMatcherFn,
 } from './types';
 
-export type {Expect, MatcherState, Matchers} from './types';
+export type {AsymmetricMatchers, Expect, MatcherState, Matchers} from './types';
 
 export class JestAssertionError extends Error {
   matcherResult?: Omit<SyncExpectationResult, 'message'> & {message: string};

packages/jest-types/__typetests__/expect.test.ts

@@ -6,7 +6,9 @@
  */
 
 import {expectError, expectType} from 'tsd-lite';
+import type {EqualsFunction, Tester} from '@jest/expect-utils';
 import {expect} from '@jest/globals';
+import type * as jestMatcherUtils from 'jest-matcher-utils';
 
 // asymmetric matchers
 
@@ -349,27 +351,63 @@ expectError(expect(jest.fn()).toThrowErrorMatchingInlineSnapshot(true));
 
 // extend
 
+type MatcherUtils = typeof jestMatcherUtils & {
+  iterableEquality: Tester;
+  subsetEquality: Tester;
+};
+
 expectType<void>(
   expect.extend({
-    toBeDivisibleBy(actual: number, expected: number) {
+    toBeWithinRange(actual: number, floor: number, ceiling: number) {
+      expectType<number>(this.assertionCalls);
+      expectType<string | undefined>(this.currentTestName);
+      expectType<(() => void) | undefined>(this.dontThrow);
+      expectType<Error | undefined>(this.error);
+      expectType<EqualsFunction>(this.equals);
+      expectType<boolean | undefined>(this.expand);
+      expectType<number | null | undefined>(this.expectedAssertionsNumber);
+      expectType<Error | undefined>(this.expectedAssertionsNumberError);
+      expectType<boolean | undefined>(this.isExpectingAssertions);
+      expectType<Error | undefined>(this.isExpectingAssertionsError);
       expectType<boolean>(this.isNot);
-
-      const pass = actual % expected === 0;
-      const message = pass
-        ? () =>
-            `expected ${this.utils.printReceived(
-              actual,
-            )} not to be divisible by ${expected}`
-        : () =>
-            `expected ${this.utils.printReceived(
-              actual,
-            )} to be divisible by ${expected}`;
-
-      return {message, pass};
+      expectType<string>(this.promise);
+      expectType<Array<Error>>(this.suppressedErrors);
+      expectType<string | undefined>(this.testPath);
+      expectType<MatcherUtils>(this.utils);
+
+      const pass = actual >= floor && actual <= ceiling;
+      if (pass) {
+        return {
+          message: () =>
+            `expected ${actual} not to be within range ${floor} - ${ceiling}`,
+          pass: true,
+        };
+      } else {
+        return {
+          message: () =>
+            `expected ${actual} to be within range ${floor} - ${ceiling}`,
+          pass: false,
+        };
+      }
     },
   }),
 );
 
-// TODO
-// expect(4).toBeDivisibleBy(2);
-// expect.toBeDivisibleBy(2);
+declare module 'expect' {
+  interface AsymmetricMatchers {
+    toBeWithinRange(floor: number, ceiling: number): void;
+  }
+  interface Matchers<R> {
+    toBeWithinRange(floor: number, ceiling: number): R;
+  }
+}
+
+expectType<void>(expect(100).toBeWithinRange(90, 110));
+expectType<void>(expect(101).not.toBeWithinRange(0, 100));
+
+expectType<void>(
+  expect({apples: 6, bananas: 3}).toEqual({
+    apples: expect.toBeWithinRange(1, 10),
+    bananas: expect.not.toBeWithinRange(11, 20),
+  }),
+);