fix: deprecate toBe* spy assertions in favor of toHaveBeen* (and toThrowError)

docs/api/expect.md

@@ -1041,7 +1041,7 @@ test('spy function', () => {
 })
 ```
 
-## toHaveBeenCalledBefore <Version>3.0.0</Version> {#tohavebeencalledbefore}
+## toHaveBeenCalledBefore
 
 - **Type**: `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
 
@@ -1060,7 +1060,7 @@ test('calls mock1 before mock2', () => {
 })
 ```
 
-## toHaveBeenCalledAfter <Version>3.0.0</Version> {#tohavebeencalledafter}
+## toHaveBeenCalledAfter
 
 - **Type**: `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => Awaitable<void>`
 
@@ -1079,7 +1079,7 @@ test('calls mock1 after mock2', () => {
 })
 ```
 
-## toHaveBeenCalledExactlyOnceWith <Version>3.0.0</Version> {#tohavebeencalledexactlyoncewith}
+## toHaveBeenCalledExactlyOnceWit
 
 - **Type**: `(...args: any[]) => Awaitable<void>`
 
@@ -1368,7 +1368,7 @@ test('spy function returns bananas on second call', async () => {
 })
 ```
 
-## called
+## called <Version>4.1.0</Version> {#called}
 
 - **Type:** `Assertion` (property, not a method)
 
@@ -1391,7 +1391,7 @@ test('spy was called', () => {
 })
 ```
 
-## callCount
+## callCount <Version>4.1.0</Version> {#callcount}
 
 - **Type:** `(count: number) => void`
 
@@ -1411,7 +1411,7 @@ test('spy call count', () => {
 })
 ```
 
-## calledWith
+## calledWith <Version>4.1.0</Version> {#calledwith}
 
 - **Type:** `(...args: any[]) => void`
 
@@ -1431,7 +1431,7 @@ test('spy called with arguments', () => {
 })
 ```
 
-## calledOnce
+## calledOnce <Version>4.1.0</Version> {#calledonce}
 
 - **Type:** `Assertion` (property, not a method)
 
@@ -1453,7 +1453,7 @@ test('spy called once', () => {
 })
 ```
 
-## calledOnceWith
+## calledOnceWith <Version>4.1.0</Version> {#calledoncewith}
 
 - **Type:** `(...args: any[]) => void`
 
@@ -1471,7 +1471,7 @@ test('spy called once with arguments', () => {
 })
 ```
 
-## calledTwice
+## calledTwice <Version>4.1.0</Version> {#calledtwice}
 
 - **Type:** `Assertion` (property, not a method)
 
@@ -1494,7 +1494,7 @@ test('spy called twice', () => {
 })
 ```
 
-## calledThrice
+## calledThrice <Version>4.1.0</Version> {#calledthrice}
 
 - **Type:** `Assertion` (property, not a method)
 
@@ -1518,7 +1518,7 @@ test('spy called thrice', () => {
 })
 ```
 
-## lastCalledWith
+## lastCalledWith <Version>4.1.0</Version> {#lastcalledwith}
 
 - **Type:** `(...args: any[]) => void`
 
@@ -1537,7 +1537,7 @@ test('spy last called with', () => {
 })
 ```
 
-## nthCalledWith
+## nthCalledWith <Version>4.1.0</Version> {#nthcalledwith}
 
 - **Type:** `(n: number, ...args: any[]) => void`
 
@@ -1557,7 +1557,7 @@ test('spy nth called with', () => {
 })
 ```
 
-## returned
+## returned <Version>4.1.0</Version> {#returned}
 
 - **Type:** `Assertion` (property, not a method)
 
@@ -1579,7 +1579,7 @@ test('spy returned', () => {
 })
 ```
 
-## returnedWith
+## returnedWith <Version>4.1.0</Version> {#returnedwith}
 
 - **Type:** `(value: any) => void`
 
@@ -1601,7 +1601,7 @@ test('spy returned with value', () => {
 })
 ```
 
-## returnedTimes
+## returnedTimes <Version>4.1.0</Version> {#returnedtimes}
 
 - **Type:** `(count: number) => void`
 
@@ -1621,7 +1621,7 @@ test('spy returned times', () => {
 })
 ```
 
-## lastReturnedWith
+## lastReturnedWith <Version>4.1.0</Version> {#lastreturnedwith}
 
 - **Type:** `(value: any) => void`
 
@@ -1642,7 +1642,7 @@ test('spy last returned with', () => {
 })
 ```
 
-## nthReturnedWith
+## nthReturnedWith <Version>4.1.0</Version> {#nthreturnedwith}
 
 - **Type:** `(n: number, value: any) => void`
 
@@ -1665,7 +1665,7 @@ test('spy nth returned with', () => {
 })
 ```
 
-## calledBefore
+## calledBefore <Version>4.1.0</Version> {#calledbefore}
 
 - **Type:** `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => void`
 
@@ -1685,7 +1685,7 @@ test('spy called before another', () => {
 })
 ```
 
-## calledAfter
+## calledAfter <Version>4.1.0</Version> {#calledafter}
 
 - **Type:** `(mock: MockInstance, failIfNoFirstInvocation?: boolean) => void`
 

packages/expect/src/types.ts

@@ -440,6 +440,7 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    *
    * @example
    * expect(mockFunc).toBeCalledTimes(2);
+   * @deprecated Use `toHaveBeenCalledTimes` instead
    */
   toBeCalledTimes: (times: number) => void
 
@@ -461,6 +462,7 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    *
    * @example
    * expect(mockFunc).toBeCalled();
+   * @deprecated Use `toHaveBeenCalled` instead
    */
   toBeCalled: () => void
 
@@ -481,6 +483,7 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    *
    * @example
    * expect(mockFunc).toBeCalledWith('arg1', 42);
+   * @deprecated Use `toHaveBeenCalledWith` instead
    */
   toBeCalledWith: <E extends any[]>(...args: E) => void
 
@@ -494,16 +497,6 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    */
   toHaveBeenNthCalledWith: <E extends any[]>(n: number, ...args: E) => void
 
-  /**
-   * Ensure that a mock function is called with specific arguments on an Nth call.
-   *
-   * Alias for `expect.toHaveBeenNthCalledWith`.
-   *
-   * @example
-   * expect(mockFunc).nthCalledWith(2, 'secondArg');
-   */
-  nthCalledWith: <E extends any[]>(nthCall: number, ...args: E) => void
-
   /**
    * If you have a mock function, you can use `.toHaveBeenLastCalledWith`
    * to test what arguments it was last called with.
@@ -515,17 +508,6 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    */
   toHaveBeenLastCalledWith: <E extends any[]>(...args: E) => void
 
-  /**
-   * If you have a mock function, you can use `.lastCalledWith`
-   * to test what arguments it was last called with.
-   *
-   * Alias for `expect.toHaveBeenLastCalledWith`.
-   *
-   * @example
-   * expect(mockFunc).lastCalledWith('lastArg');
-   */
-  lastCalledWith: <E extends any[]>(...args: E) => void
-
   /**
    * Used to test that a function throws when it is called.
    *
@@ -547,6 +529,7 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    * expect(() => functionWithError()).toThrowError('Error message');
    * expect(() => parseJSON('invalid')).toThrowError(SyntaxError);
    * expect(() => { throw 42 }).toThrowError(42);
+   * @deprecated Use `toThrow` instead
    */
   toThrowError: (expected?: any) => void
 
@@ -557,6 +540,7 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    *
    * @example
    * expect(mockFunc).toReturn();
+   * @deprecated Use `toHaveReturned` instead
    */
   toReturn: () => void
 
@@ -578,6 +562,7 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    *
    * @example
    * expect(mockFunc).toReturnTimes(3);
+   * @deprecated Use `toHaveReturnedTimes` instead
    */
   toReturnTimes: (times: number) => void
 
@@ -599,6 +584,7 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    *
    * @example
    * expect(mockFunc).toReturnWith('returnValue');
+   * @deprecated Use `toHaveReturnedWith` instead
    */
   toReturnWith: <E>(value: E) => void
 
@@ -624,18 +610,6 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    */
   toHaveLastReturnedWith: <E>(value: E) => void
 
-  /**
-   * Use 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.
-   *
-   * Alias for `expect.toHaveLastReturnedWith`.
-   *
-   * @example
-   * expect(mockFunc).lastReturnedWith('lastValue');
-   */
-  lastReturnedWith: <E>(value: E) => void
-
   /**
    * Use 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
@@ -647,18 +621,6 @@ export interface JestAssertion<T = any> extends jest.Matchers<void, T>, CustomMa
    * expect(mockFunc).toHaveNthReturnedWith(2, 'nthValue');
    */
   toHaveNthReturnedWith: <E>(nthCall: number, value: E) => void
-
-  /**
-   * Use 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.
-   *
-   * Alias for `expect.toHaveNthReturnedWith`.
-   *
-   * @example
-   * expect(mockFunc).nthReturnedWith(2, 'nthValue');
-   */
-  nthReturnedWith: <E>(nthCall: number, value: E) => void
 }
 
 type VitestAssertion<A, T> = {

test/core/test/expect.test.ts

@@ -302,6 +302,7 @@ describe('recursive custom equality tester', () => {
 
     expect(mockFn).toHaveReturnedWith([person1, person2])
     expect(mockFn).toHaveLastReturnedWith([person1, person2])
+    expect(mockFn).to.have.lastReturnedWith([person1, person2])
     expect(mockFn).toHaveNthReturnedWith(1, [person1, person2])
   })
 })