Remove aliased matchers

CHANGELOG.md

@@ -10,6 +10,9 @@
 
 ### Chore & Maintenance
 
+- `[expect]` [**BREAKING**] Remove `.toBeCalled()`, `.toBeCalledTimes()`, `.toBeCalledWith()`, `.lastCalledWith()`, `.nthCalledWith()`, `.toReturn()`, `.toReturnTimes()`, `.toReturnWith()`, `.lastReturnedWith()`, `.nthReturnedWith()` and `.toThrowError()` matchers ([#13192](https://github.com/facebook/jest/pull/13192))
+- `[docs]` Remove `.toBeCalled()`, `.toBeCalledTimes()`, `.toBeCalledWith()`, `.lastCalledWith()`, `.nthCalledWith()`, `.toReturn()`, `.toReturnTimes()`, `.toReturnWith()`, `.lastReturnedWith()`, `.nthReturnedWith()` and `.toThrowError()` matchers from docs ([#13192](https://github.com/facebook/jest/pull/13192))
+
 ### Performance
 
 ## 29.0.1

docs/ExpectAPI.md

@@ -352,7 +352,7 @@ it('transitions as expected', () => {
 test('map calls its argument with a non-null argument', () => {
   const mock = jest.fn();
   [1].map(x => mock(x));
-  expect(mock).toBeCalledWith(expect.anything());
+  expect(mock).toHaveBeenCalledWith(expect.anything());
 });
 ```
 
@@ -369,7 +369,7 @@ function getCat(fn) {
 test('randocall calls its callback with a class instance', () => {
   const mock = jest.fn();
   getCat(mock);
-  expect(mock).toBeCalledWith(expect.any(Cat));
+  expect(mock).toHaveBeenCalledWith(expect.any(Cat));
 });
 
 function randocall(fn) {
@@ -379,7 +379,7 @@ function randocall(fn) {
 test('randocall calls its callback with a number', () => {
   const mock = jest.fn();
   randocall(mock);
-  expect(mock).toBeCalledWith(expect.any(Number));
+  expect(mock).toHaveBeenCalledWith(expect.any(Number));
 });
 ```
 
@@ -558,7 +558,7 @@ For example, let's say that we expect an `onPress` function to be called with an
 test('onPress gets called with the right thing', () => {
   const onPress = jest.fn();
   simulatePresses(onPress);
-  expect(onPress).toBeCalledWith(
+  expect(onPress).toHaveBeenCalledWith(
     expect.objectContaining({
       x: expect.any(Number),
       y: expect.any(Number),
@@ -713,8 +713,6 @@ Although the `.toBe` matcher **checks** referential identity, it **reports** a d
 
 ### `.toHaveBeenCalled()`
 
-Also under the alias: `.toBeCalled()`
-
 Use `.toHaveBeenCalledWith` to ensure that a mock function was called with specific arguments. The arguments are checked with the same algorithm that `.toEqual` uses.
 
 For example, let's say you have a `drinkAll(drink, flavour)` function that takes a `drink` function and applies it to all available beverages. You might want to check that `drink` gets called for `'lemon'`, but not for `'octopus'`, because `'octopus'` flavour is really weird and why would anything be octopus-flavoured? You can do that with this test suite:
@@ -743,8 +741,6 @@ describe('drinkAll', () => {
 
 ### `.toHaveBeenCalledTimes(number)`
 
-Also under the alias: `.toBeCalledTimes(number)`
-
 Use `.toHaveBeenCalledTimes` to ensure that a mock function got called exact number of times.
 
 For example, let's say you have a `drinkEach(drink, Array<flavor>)` function that takes a `drink` function and applies it to array of passed beverages. You might want to check that drink function was called exact number of times. You can do that with this test suite:
@@ -759,8 +755,6 @@ test('drinkEach drinks each drink', () => {
 
 ### `.toHaveBeenCalledWith(arg1, arg2, ...)`
 
-Also under the alias: `.toBeCalledWith()`
-
 Use `.toHaveBeenCalledWith` to ensure that a mock function was called with specific arguments. The arguments are checked with the same algorithm that `.toEqual` uses.
 
 For example, let's say that you can register a beverage with a `register` function, and `applyToAll(f)` should apply the function `f` to all registered beverages. To make sure this works, you could write:
@@ -777,8 +771,6 @@ test('registration applies correctly to orange La Croix', () => {
 
 ### `.toHaveBeenLastCalledWith(arg1, arg2, ...)`
 
-Also under the alias: `.lastCalledWith(arg1, arg2, ...)`
-
 If you have a mock function, you can use `.toHaveBeenLastCalledWith` to test what arguments it was last called with. For example, let's say you have a `applyToAllFlavors(f)` function that applies `f` to a bunch of flavors, and you want to ensure that when you call it, the last flavor it operates on is `'mango'`. You can write:
 
 ```js
@@ -791,8 +783,6 @@ test('applying to all flavors does mango last', () => {
 
 ### `.toHaveBeenNthCalledWith(nthCall, arg1, arg2, ....)`
 
-Also under the alias: `.nthCalledWith(nthCall, arg1, arg2, ...)`
-
 If you have a mock function, you can use `.toHaveBeenNthCalledWith` to test what arguments it was nth called with. For example, let's say you have a `drinkEach(drink, Array<flavor>)` function that applies `f` to a bunch of flavors, and you want to ensure that when you call it, the first flavor it operates on is `'lemon'` and the second one is `'octopus'`. You can write:
 
 ```js
@@ -812,8 +802,6 @@ The nth argument must be positive integer starting from 1.
 
 ### `.toHaveReturned()`
 
-Also under the alias: `.toReturn()`
-
 If you have a mock function, you can use `.toHaveReturned` to test that the mock function successfully returned (i.e., did not throw an error) at least one time. For example, let's say you have a mock `drink` that returns `true`. You can write:
 
 ```js
@@ -828,8 +816,6 @@ test('drinks returns', () => {
 
 ### `.toHaveReturnedTimes(number)`
 
-Also under the alias: `.toReturnTimes(number)`
-
 Use `.toHaveReturnedTimes` to ensure that a mock function returned successfully (i.e., did not throw an error) an exact number of times. Any calls to the mock function that throw an error are not counted toward the number of times the function returned.
 
 For example, let's say you have a mock `drink` that returns `true`. You can write:
@@ -847,8 +833,6 @@ test('drink returns twice', () => {
 
 ### `.toHaveReturnedWith(value)`
 
-Also under the alias: `.toReturnWith(value)`
-
 Use `.toHaveReturnedWith` to ensure that a mock function returned a specific value.
 
 For example, let's say you have a mock `drink` that returns the name of the beverage that was consumed. You can write:
@@ -866,8 +850,6 @@ test('drink returns La Croix', () => {
 
 ### `.toHaveLastReturnedWith(value)`
 
-Also under the alias: `.lastReturnedWith(value)`
-
 Use `.toHaveLastReturnedWith` to test the specific value that a mock function last returned. 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.
 
 For example, let's say you have a mock `drink` that returns the name of the beverage that was consumed. You can write:
@@ -887,8 +869,6 @@ test('drink returns La Croix (Orange) last', () => {
 
 ### `.toHaveNthReturnedWith(nthCall, value)`
 
-Also under the alias: `.nthReturnedWith(nthCall, value)`
-
 Use `.toHaveNthReturnedWith` to test the specific value that a mock function returned for the nth call. 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.
 
 For example, let's say you have a mock `drink` that returns the name of the beverage that was consumed. You can write:
@@ -1344,8 +1324,6 @@ describe('the La Croix cans on my desk', () => {
 
 ### `.toThrow(error?)`
 
-Also under the alias: `.toThrowError(error?)`
-
 Use `.toThrow` to test that a function throws when it is called. For example, if we want to test that `drinkFlavor('octopus')` throws, because octopus flavor is too disgusting to drink, we could write:
 
 ```js
@@ -1389,15 +1367,15 @@ test('throws on octopus', () => {
   }
 
   // Test that the error message says "yuck" somewhere: these are equivalent
-  expect(drinkOctopus).toThrowError(/yuck/);
-  expect(drinkOctopus).toThrowError('yuck');
+  expect(drinkOctopus).toThrow(/yuck/);
+  expect(drinkOctopus).toThrow('yuck');
 
   // Test the exact error message
-  expect(drinkOctopus).toThrowError(/^yuck, octopus flavor$/);
-  expect(drinkOctopus).toThrowError(new Error('yuck, octopus flavor'));
+  expect(drinkOctopus).toThrow(/^yuck, octopus flavor$/);
+  expect(drinkOctopus).toThrow(new Error('yuck, octopus flavor'));
 
   // Test that we get a DisgustingFlavorError
-  expect(drinkOctopus).toThrowError(DisgustingFlavorError);
+  expect(drinkOctopus).toThrow(DisgustingFlavorError);
 });
 ```
 

docs/GlobalAPI.md

@@ -208,11 +208,11 @@ const binaryStringToNumber = binString => {
 describe('binaryStringToNumber', () => {
   describe('given an invalid binary string', () => {
     test('composed of non-numbers throws CustomError', () => {
-      expect(() => binaryStringToNumber('abc')).toThrowError(CustomError);
+      expect(() => binaryStringToNumber('abc')).toThrow(CustomError);
     });
 
     test('with extra whitespace throws CustomError', () => {
-      expect(() => binaryStringToNumber('  100')).toThrowError(CustomError);
+      expect(() => binaryStringToNumber('  100')).toThrow(CustomError);
     });
   });
 

docs/MockFunctionAPI.md

@@ -516,8 +516,8 @@ test('calculate calls add', () => {
   // requiring `add`.
   calculate(mockAdd, 1, 2);
 
-  expect(mockAdd).toBeCalledTimes(1);
-  expect(mockAdd).toBeCalledWith(1, 2);
+  expect(mockAdd).toHaveBeenCalledTimes(1);
+  expect(mockAdd).toHaveBeenCalledWith(1, 2);
 });
 ```
 

docs/TimerMocks.md

@@ -53,13 +53,13 @@ test('calls the callback after 1 second', () => {
   timerGame(callback);
 
   // At this point in time, the callback should not have been called yet
-  expect(callback).not.toBeCalled();
+  expect(callback).not.toHaveBeenCalled();
 
   // Fast-forward until all timers have been executed
   jest.runAllTimers();
 
   // Now our callback should have been called!
-  expect(callback).toBeCalled();
+  expect(callback).toHaveBeenCalled();
   expect(callback).toHaveBeenCalledTimes(1);
 });
 ```
@@ -109,7 +109,7 @@ describe('infiniteTimerGame', () => {
     jest.runOnlyPendingTimers();
 
     // At this point, our 1-second timer should have fired its callback
-    expect(callback).toBeCalled();
+    expect(callback).toHaveBeenCalled();
 
     // And it should have created a new timer to start the game over in
     // 10 seconds
@@ -154,13 +154,13 @@ it('calls the callback after 1 second via advanceTimersByTime', () => {
   timerGame(callback);
 
   // At this point in time, the callback should not have been called yet
-  expect(callback).not.toBeCalled();
+  expect(callback).not.toHaveBeenCalled();
 
   // Fast-forward until all timers have been executed
   jest.advanceTimersByTime(1000);
 
   // Now our callback should have been called!
-  expect(callback).toBeCalled();
+  expect(callback).toHaveBeenCalled();
   expect(callback).toHaveBeenCalledTimes(1);
 });
 ```

docs/TutorialjQuery.md

@@ -54,7 +54,7 @@ test('displays a user after a click', () => {
 
   // Assert that the fetchCurrentUser function was called, and that the
   // #username span's inner text was updated as we'd expect it to.
-  expect(fetchCurrentUser).toBeCalled();
+  expect(fetchCurrentUser).toHaveBeenCalled();
   expect($('#username').text()).toEqual('Johnny Cash - Logged In');
 });
 ```

e2e/__tests__/failureDetailsProperty.test.ts

@@ -160,19 +160,19 @@ test('that the failureDetails property is set', () => {
           Object {
             "actual": "",
             "error": Object {
-              "message": "expect(received).rejects.toThrowError()
+              "message": "expect(received).rejects.toThrow()
 
       Received promise resolved instead of rejected
       Resolved to value: 1",
             },
             "expected": "",
             "matcherName": "",
-            "message": "Error: expect(received).rejects.toThrowError()
+            "message": "Error: expect(received).rejects.toThrow()
 
       Received promise resolved instead of rejected
       Resolved to value: 1",
             "passed": false,
-            "stack": "Error: expect(received).rejects.toThrowError()
+            "stack": "Error: expect(received).rejects.toThrow()
 
       Received promise resolved instead of rejected
       Resolved to value: 1
@@ -245,7 +245,7 @@ test('that the failureDetails property is set', () => {
         ],
         Array [
           Object {
-            "message": "expect(received).rejects.toThrowError()
+            "message": "expect(received).rejects.toThrow()
 
       Received promise resolved instead of rejected
       Resolved to value: 1",

e2e/__tests__/isolateModules.test.ts

@@ -45,7 +45,7 @@ test('works with mocks', () => {
           require("./read");
         });
 
-        expect(configGetMock).toBeCalledTimes(1);
+        expect(configGetMock).toHaveBeenCalledTimes(1);
       })
     `,
   });

e2e/failureDetails-property/__tests__/tests.test.js

@@ -33,5 +33,5 @@ it('throws!', () => {
 });
 
 test('promise rejection', async () => {
-  await expect(Promise.resolve(1)).rejects.toThrowError();
+  await expect(Promise.resolve(1)).rejects.toThrow();
 });

e2e/module-name-mapper-mock/__tests__/storage/track/Track.test.js

@@ -10,5 +10,5 @@ jest.mock('@@storage/track/Track');
 
 test('relative import', () => {
   const track = new Track();
-  expect(track.someRandomFunction).not.toBeCalled();
+  expect(track.someRandomFunction).not.toHaveBeenCalled();
 });

e2e/module-name-mapper-mock/__tests__/storage/track/TrackExpected.test.js

@@ -10,5 +10,5 @@ jest.mock('@@storage/track/Track');
 
 test('through moduleNameMapper', () => {
   const track = new Track();
-  expect(track.someRandomFunction).not.toBeCalled();
+  expect(track.someRandomFunction).not.toHaveBeenCalled();
 });

e2e/resolve-with-paths/__tests__/resolveWithPaths.test.js

@@ -30,7 +30,7 @@ test('finds a native node module when paths are given', () => {
 });
 
 test('throws an error if the module cannot be found from given paths', () => {
-  expect(() => require.resolve('./mod.js', {paths: ['..']})).toThrowError(
+  expect(() => require.resolve('./mod.js', {paths: ['..']})).toThrow(
     "Cannot resolve module './mod.js' from paths ['..'] from ",
   );
 });

examples/jquery/__tests__/display_user.test.js

@@ -34,6 +34,6 @@ it('displays a user after a click', () => {
 
   // Assert that the fetchCurrentUser function was called, and that the
   // #username span's inner text was updated as we'd expect it to.
-  expect(fetchCurrentUser).toBeCalled();
+  expect(fetchCurrentUser).toHaveBeenCalled();
   expect($('#username').text()).toEqual('Johnny Cash - Logged In');
 });

examples/jquery/__tests__/fetch_current_user.test.js

@@ -14,7 +14,7 @@ it('calls into $.ajax with the correct params', () => {
 
   // Now make sure that $.ajax was properly called during the previous
   // 2 lines
-  expect($.ajax).toBeCalledWith({
+  expect($.ajax).toHaveBeenCalledWith({
     success: expect.any(Function),
     type: 'GET',
     url: 'http://example.com/currentUser',

examples/timer/__tests__/infinite_timer_game.test.js

@@ -13,18 +13,18 @@ it('schedules a 10-second timer after 1 second', () => {
 
   // At this point in time, there should have been a single call to
   // setTimeout to schedule the end of the game in 1 second.
-  expect(setTimeout).toBeCalledTimes(1);
+  expect(setTimeout).toHaveBeenCalledTimes(1);
   expect(setTimeout).toHaveBeenNthCalledWith(1, expect.any(Function), 1000);
 
   // Fast forward and exhaust only currently pending timers
   // (but not any new timers that get created during that process)
   jest.runOnlyPendingTimers();
 
   // At this point, our 1-second timer should have fired its callback
-  expect(callback).toBeCalled();
+  expect(callback).toHaveBeenCalled();
 
   // And it should have created a new timer to start the game over in
   // 10 seconds
-  expect(setTimeout).toBeCalledTimes(2);
+  expect(setTimeout).toHaveBeenCalledTimes(2);
   expect(setTimeout).toHaveBeenNthCalledWith(2, expect.any(Function), 10000);
 });

examples/timer/__tests__/timer_game.test.js

@@ -12,8 +12,8 @@ describe('timerGame', () => {
     const timerGame = require('../timerGame');
     timerGame();
 
-    expect(setTimeout).toBeCalledTimes(1);
-    expect(setTimeout).toBeCalledWith(expect.any(Function), 1000);
+    expect(setTimeout).toHaveBeenCalledTimes(1);
+    expect(setTimeout).toHaveBeenCalledWith(expect.any(Function), 1000);
   });
 
   it('calls the callback after 1 second via runAllTimers', () => {
@@ -23,14 +23,14 @@ describe('timerGame', () => {
     timerGame(callback);
 
     // At this point in time, the callback should not have been called yet
-    expect(callback).not.toBeCalled();
+    expect(callback).not.toHaveBeenCalled();
 
     // Fast-forward until all timers have been executed
     jest.runAllTimers();
 
     // Now our callback should have been called!
-    expect(callback).toBeCalled();
-    expect(callback).toBeCalledTimes(1);
+    expect(callback).toHaveBeenCalled();
+    expect(callback).toHaveBeenCalledTimes(1);
   });
 
   it('calls the callback after 1 second via advanceTimersByTime', () => {
@@ -40,13 +40,13 @@ describe('timerGame', () => {
     timerGame(callback);
 
     // At this point in time, the callback should not have been called yet
-    expect(callback).not.toBeCalled();
+    expect(callback).not.toHaveBeenCalled();
 
     // Fast-forward until all timers have been executed
     jest.advanceTimersByTime(1000);
 
     // Now our callback should have been called!
-    expect(callback).toBeCalled();
-    expect(callback).toBeCalledTimes(1);
+    expect(callback).toHaveBeenCalled();
+    expect(callback).toHaveBeenCalledTimes(1);
   });
 });