chore: remove .toReturn() matcher

packages/expect/src/__tests__/__snapshots__/spyMatchers.test.ts.snap

@@ -2034,112 +2034,6 @@ Expected: not <g>undefined</>
 Number of returns: <r>1</>
 `;
 
-exports[`toReturn .not fails with any argument passed 1`] = `
-<d>expect(</><r>received</><d>).</>not<d>.</>toReturn<d>()</>
-
-<b>Matcher error</>: this matcher must not have an expected argument
-
-Expected has type: number
-Expected has value: <g>555</>
-`;
-
-exports[`toReturn .not passes when a call throws undefined 1`] = `
-<d>expect(</><r>jest.fn()</><d>).</>toReturn<d>()</>
-
-Expected number of returns: >= <g>1</>
-Received number of returns: <r>0</>
-Received number of calls: <r>1</>
-`;
-
-exports[`toReturn .not passes when all calls throw 1`] = `
-<d>expect(</><r>jest.fn()</><d>).</>toReturn<d>()</>
-
-Expected number of returns: >= <g>1</>
-Received number of returns: <r>0</>
-Received number of calls: <r>2</>
-`;
-
-exports[`toReturn .not passes when not returned 1`] = `
-<d>expect(</><r>jest.fn()</><d>).</>toReturn<d>()</>
-
-Expected number of returns: >= <g>1</>
-Received number of returns: <r>0</>
-`;
-
-exports[`toReturn .not works only on jest.fn 1`] = `
-<d>expect(</><r>received</><d>).</>not<d>.</>toReturn<d>()</>
-
-<b>Matcher error</>: <r>received</> value must be a mock function
-
-Received has type: function
-Received has value: <r>[Function fn]</>
-`;
-
-exports[`toReturn fails with any argument passed 1`] = `
-<d>expect(</><r>received</><d>).</>toReturn<d>()</>
-
-<b>Matcher error</>: this matcher must not have an expected argument
-
-Expected has type: number
-Expected has value: <g>555</>
-`;
-
-exports[`toReturn includes the custom mock name in the error message 1`] = `
-<d>expect(</><r>named-mock</><d>).</>not<d>.</>toReturn<d>()</>
-
-Expected number of returns: <g>0</>
-Received number of returns: <r>1</>
-
-1: <r>42</>
-`;
-
-exports[`toReturn incomplete recursive calls are handled properly 1`] = `
-<d>expect(</><r>jest.fn()</><d>).</>toReturn<d>()</>
-
-Expected number of returns: >= <g>1</>
-Received number of returns: <r>0</>
-Received number of calls: <r>4</>
-`;
-
-exports[`toReturn passes when at least one call does not throw 1`] = `
-<d>expect(</><r>jest.fn()</><d>).</>not<d>.</>toReturn<d>()</>
-
-Expected number of returns: <g>0</>
-Received number of returns: <r>2</>
-
-1: <r>42</>
-3: <r>42</>
-
-Received number of calls: <r>3</>
-`;
-
-exports[`toReturn passes when returned 1`] = `
-<d>expect(</><r>jest.fn()</><d>).</>not<d>.</>toReturn<d>()</>
-
-Expected number of returns: <g>0</>
-Received number of returns: <r>1</>
-
-1: <r>42</>
-`;
-
-exports[`toReturn passes when undefined is returned 1`] = `
-<d>expect(</><r>jest.fn()</><d>).</>not<d>.</>toReturn<d>()</>
-
-Expected number of returns: <g>0</>
-Received number of returns: <r>1</>
-
-1: <r>undefined</>
-`;
-
-exports[`toReturn throw matcher error if received is spy 1`] = `
-<d>expect(</><r>received</><d>).</>toReturn<d>()</>
-
-<b>Matcher error</>: <r>received</> value must be a mock function
-
-Received has type: function
-Received has value: <r>[Function spy]</>
-`;
-
 exports[`toReturnTimes .not only accepts a number argument 1`] = `
 <d>expect(</><r>received</><d>).</>not<d>.</>toReturnTimes<d>(</><g>expected</><d>)</>
 

packages/expect/src/__tests__/spyMatchers.test.ts

@@ -519,153 +519,159 @@ describe('toHaveBeenCalledTimes', () => {
  });
 });
 
-['toReturn', 'toHaveReturned'].forEach(returned => {
- describe(`${returned}`, () => {
- test('.not works only on jest.fn', () => {
- const fn = function fn() {};
+describe('toHaveReturned', () => {
+ test('.not works only on jest.fn', () => {
+ const fn = function fn() {};
 
-  expect(() =>
-  jestExpect(fn).not[returned](),
-  ).toThrowErrorMatchingSnapshot();
-  });
+ expect(() =>
+ jestExpect(fn).not.toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
-  test('throw matcher error if received is spy', () => {
-  const spy = createSpy(jest.fn());
+ test('throw matcher error if received is spy', () => {
+ const spy = createSpy(jest.fn());
 
- expect(() => jestExpect(spy)[returned]()).toThrowErrorMatchingSnapshot();
- });
+ expect(() =>
+ jestExpect(spy).toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
-  test('passes when returned', () => {
-  const fn = jest.fn(() => 42);
-  fn();
-  jestExpect(fn)[returned]();
-  expect(() =>
-  jestExpect(fn).not[returned](),
-  ).toThrowErrorMatchingSnapshot();
-  });
+ test('passes when returned', () => {
+ const fn = jest.fn(() => 42);
+ fn();
+ jestExpect(fn).toHaveReturned();
+ expect(() =>
+ jestExpect(fn).not.toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
-  test('passes when undefined is returned', () => {
-  const fn = jest.fn(() => undefined);
-  fn();
-  jestExpect(fn)[returned]();
-  expect(() =>
-  jestExpect(fn).not[returned](),
-  ).toThrowErrorMatchingSnapshot();
-  });
+ test('passes when undefined is returned', () => {
+ const fn = jest.fn(() => undefined);
+ fn();
+ jestExpect(fn).toHaveReturned();
+ expect(() =>
+ jestExpect(fn).not.toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
-  test('passes when at least one call does not throw', () => {
-  const fn = jest.fn(causeError => {
-  if (causeError) {
-  throw new Error('Error!');
-  }
+ test('passes when at least one call does not throw', () => {
+ const fn = jest.fn(causeError => {
+ if (causeError) {
+ throw new Error('Error!');
+ }
 
-  return 42;
-  });
+ return 42;
+ });
 
-  fn(false);
+ fn(false);
 
-  try {
-  fn(true);
-  } catch {
-  // ignore error
-  }
+ try {
+ fn(true);
+ } catch {
+ // ignore error
+ }
 
-  fn(false);
+ fn(false);
 
-  jestExpect(fn)[returned]();
-  expect(() =>
-  jestExpect(fn).not[returned](),
-  ).toThrowErrorMatchingSnapshot();
-  });
+ jestExpect(fn).toHaveReturned();
+ expect(() =>
+ jestExpect(fn).not.toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
-  test('.not passes when not returned', () => {
-  const fn = jest.fn();
+ test('.not passes when not returned', () => {
+ const fn = jest.fn();
 
- jestExpect(fn).not[returned]();
- expect(() => jestExpect(fn)[returned]()).toThrowErrorMatchingSnapshot();
+ jestExpect(fn).not.toHaveReturned();
+ expect(() =>
+ jestExpect(fn).toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ });
+
+ test('.not passes when all calls throw', () => {
+ const fn = jest.fn(() => {
+ throw new Error('Error!');
  });
 
- test('.not passes when all calls throw', () => {
- const fn = jest.fn(() => {
- throw new Error('Error!');
- });
+ try {
+ fn();
+ } catch {
+ // ignore error
+ }
 
-  try {
-  fn();
-  } catch {
-  // ignore error
-  }
+ try {
+ fn();
+ } catch {
+ // ignore error
+ }
 
-  try {
-  fn();
- } catch {
-  // ignore error
-  }
+ jestExpect(fn).not.toHaveReturned();
+ expect(() =>
+ jestExpect(fn).toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
- jestExpect(fn).not[returned]();
- expect(() => jestExpect(fn)[returned]()).toThrowErrorMatchingSnapshot();
+ test('.not passes when a call throws undefined', () => {
+ const fn = jest.fn(() => {
+ // eslint-disable-next-line no-throw-literal
+ throw undefined;
  });
 
- test('.not passes when a call throws undefined', () => {
- const fn = jest.fn(() => {
-  // eslint-disable-next-line no-throw-literal
-  throw undefined;
-  });
+ try {
+ fn();
+ } catch {
+ // ignore error
+ }
 
-  try {
-  fn();
- } catch {
-  // ignore error
-  }
+ jestExpect(fn).not.toHaveReturned();
+ expect(() =>
+ jestExpect(fn).toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
- jestExpect(fn).not[returned]();
- expect(() => jestExpect(fn)[returned]()).toThrowErrorMatchingSnapshot();
- });
+ test('fails with any argument passed', () => {
+ const fn = jest.fn();
 
- test('fails with any argument passed', () => {
- const fn = jest.fn();
+ fn();
+ expect(() =>
+ jestExpect(fn).toHaveReturned(555),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
- fn();
- expect(() =>
- jestExpect(fn)[returned](555),
- ).toThrowErrorMatchingSnapshot();
- });
+ test('.not fails with any argument passed', () => {
+ const fn = jest.fn();
 
- test('.not fails with any argument passed', () => {
- const fn = jest.fn();
+ expect(() =>
+ jestExpect(fn).not.toHaveReturned(555),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
- expect(() =>
- jestExpect(fn).not[returned](555),
- ).toThrowErrorMatchingSnapshot();
- });
+ test('includes the custom mock name in the error message', () => {
+ const fn = jest.fn(() => 42).mockName('named-mock');
+ fn();
+ jestExpect(fn).toHaveReturned();
+ expect(() =>
+ jestExpect(fn).not.toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ });
 
- test('includes the custom mock name in the error message', () => {
- const fn = jest.fn(() => 42).mockName('named-mock');
- fn();
- jestExpect(fn)[returned]();
- expect(() =>
- jestExpect(fn).not[returned](),
- ).toThrowErrorMatchingSnapshot();
+ test('incomplete recursive calls are handled properly', () => {
+ // sums up all integers from 0 -> value, using recursion
+ const fn: jest.Mock = jest.fn(value => {
+ if (value === 0) {
+ // Before returning from the base case of recursion, none of the
+ // calls have returned yet.
+ jestExpect(fn).not.toHaveReturned();
+ expect(() =>
+ jestExpect(fn).toHaveReturned(),
+ ).toThrowErrorMatchingSnapshot();
+ return 0;
+ } else {
+ return value + fn(value - 1);
+ }
  });
 
- test('incomplete recursive calls are handled properly', () => {
- // sums up all integers from 0 -> value, using recursion
- const fn: jest.Mock = jest.fn(value => {
- if (value === 0) {
- // Before returning from the base case of recursion, none of the
- // calls have returned yet.
- jestExpect(fn).not[returned]();
- expect(() =>
- jestExpect(fn)[returned](),
- ).toThrowErrorMatchingSnapshot();
- return 0;
- } else {
- return value + fn(value - 1);
- }
- });
-
- fn(3);
- });
+ fn(3);
  });
 });
 

packages/expect/src/spyMatchers.ts

@@ -1152,7 +1152,6 @@ const spyMatchers: MatchersObject = {
  toHaveReturned: createToReturnMatcher('toHaveReturned'),
  toHaveReturnedTimes: createToReturnTimesMatcher('toHaveReturnedTimes'),
  toHaveReturnedWith: createToReturnWithMatcher('toHaveReturnedWith'),
- toReturn: createToReturnMatcher('toReturn'),
  toReturnTimes: createToReturnTimesMatcher('toReturnTimes'),
  toReturnWith: createToReturnWithMatcher('toReturnWith'),
 };