fix(@jest/types): allow the *ReturnedWith matchers to be called with no argument

CHANGELOG.md

@@ -10,6 +10,7 @@
 
 - `[babel-plugin-jest-hoist]` Ignore `TSTypeQuery` when checking for hoisted references ([#13367](https://github.com/facebook/jest/pull/13367))
 - `[@jest/types]` Infer type of `each` table correctly when the table is a tuple or array ([#13381](https://github.com/facebook/jest/pull/13381))
+- `[@jest/types]` Rework typings to allow the `*ReturnedWith` matchers to be called with no argument ([#13385](https://github.com/facebook/jest/pull/13385))
 
 ### Chore & Maintenance
 

packages/expect/src/types.ts

@@ -139,15 +139,15 @@ export interface Matchers<R extends void | Promise<void>> {
   /**
    * Ensure that the last call to a mock function has returned a specified value.
    */
-  lastReturnedWith(expected: unknown): R;
+  lastReturnedWith(expected?: unknown): R;
   /**
    * Ensure that a mock function is called with specific arguments on an Nth call.
    */
   nthCalledWith(nth: number, ...expected: Array<unknown>): R;
   /**
    * Ensure that the nth call to a mock function has returned a specified value.
    */
-  nthReturnedWith(nth: number, expected: unknown): R;
+  nthReturnedWith(nth: number, expected?: unknown): R;
   /**
    * Checks that a value is what you expect. It calls `Object.is` to compare values.
    * Don't use `toBe` with floating-point numbers.
@@ -262,7 +262,7 @@ export interface Matchers<R extends void | Promise<void>> {
    * If the last call to the mock function threw an error, then this matcher will fail
    * no matter what value you provided as the expected return value.
    */
-  toHaveLastReturnedWith(expected: unknown): R;
+  toHaveLastReturnedWith(expected?: unknown): R;
   /**
    * Used to check that an object has a `.length` property
    * and it is set to a certain numeric value.
@@ -273,7 +273,7 @@ export interface Matchers<R extends void | Promise<void>> {
    * If the nth call to the mock function threw an error, then this matcher will fail
    * no matter what value you provided as the expected return value.
    */
-  toHaveNthReturnedWith(nth: number, expected: unknown): R;
+  toHaveNthReturnedWith(nth: number, expected?: unknown): R;
   /**
    * Use to check if property at provided reference keyPath exists for an object.
    * For checking deeply nested properties in an object you may use dot notation or an array containing
@@ -303,7 +303,7 @@ export interface Matchers<R extends void | Promise<void>> {
   /**
    * Use to ensure that a mock function returned a specific value.
    */
-  toHaveReturnedWith(expected: unknown): R;
+  toHaveReturnedWith(expected?: unknown): R;
   /**
    * Check that a string matches a regular expression.
    */
@@ -325,7 +325,7 @@ export interface Matchers<R extends void | Promise<void>> {
   /**
    * Ensure that a mock function has returned a specified value at least once.
    */
-  toReturnWith(expected: unknown): R;
+  toReturnWith(expected?: unknown): R;
   /**
    * Use to test that objects have the same types as well as structure.
    */

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

@@ -287,56 +287,56 @@ expectType<void>(expect(jest.fn()).toHaveReturnedTimes(3));
 expectError(expect(jest.fn()).toHaveReturnedTimes(true));
 expectError(expect(jest.fn()).toHaveReturnedTimes());
 
+expectType<void>(expect(jest.fn()).toReturnWith());
 expectType<void>(expect(jest.fn()).toReturnWith('value'));
 expectType<void>(
   expect(jest.fn<() => string>()).toReturnWith(
     expect.stringContaining('value'),
   ),
 );
-expectError(expect(jest.fn()).toReturnWith());
 
+expectType<void>(expect(jest.fn()).toHaveReturnedWith());
 expectType<void>(expect(jest.fn()).toHaveReturnedWith(123));
 expectType<void>(
   expect(jest.fn<() => string>()).toHaveReturnedWith(
     expect.stringContaining('value'),
   ),
 );
-expectError(expect(jest.fn()).toHaveReturnedWith());
 
+expectType<void>(expect(jest.fn()).lastReturnedWith());
 expectType<void>(expect(jest.fn()).lastReturnedWith('value'));
 expectType<void>(
   expect(jest.fn<() => string>()).lastReturnedWith(
     expect.stringContaining('value'),
   ),
 );
-expectError(expect(jest.fn()).lastReturnedWith());
 
+expectType<void>(expect(jest.fn()).toHaveLastReturnedWith());
 expectType<void>(expect(jest.fn()).toHaveLastReturnedWith(123));
 expectType<void>(
   expect(jest.fn<() => string>()).toHaveLastReturnedWith(
     expect.stringContaining('value'),
   ),
 );
-expectError(expect(jest.fn()).toHaveLastReturnedWith());
 
+expectType<void>(expect(jest.fn()).nthReturnedWith(1));
 expectType<void>(expect(jest.fn()).nthReturnedWith(1, 'value'));
 expectType<void>(
   expect(jest.fn<() => string>()).nthReturnedWith(
     2,
     expect.stringContaining('value'),
   ),
 );
-expectError(expect(123).nthReturnedWith(3));
 expectError(expect(jest.fn()).nthReturnedWith());
 
+expectType<void>(expect(jest.fn()).nthReturnedWith(1));
 expectType<void>(expect(jest.fn()).nthReturnedWith(1, 'value'));
 expectType<void>(
   expect(jest.fn<() => string>()).nthReturnedWith(
     2,
     expect.stringContaining('value'),
   ),
 );
-expectError(expect(123).toHaveNthReturnedWith(3));
 expectError(expect(jest.fn()).toHaveNthReturnedWith());
 
 // snapshot matchers