feat(jest-mock): add mockFn.mock.lastCall to retrieve last argument

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Features
 
+- `[mockFunctions]` Added mockFn.mock.lastCall to retreive last Arguement ([#12285](https://github.com/facebook/jest/pull/12285))
+
 ### Fixes
 
 - `[@jest/transform]` Update dependency package `pirates` to 4.0.4 ([#12136](https://github.com/facebook/jest/pull/12136))

docs/MockFunctionAPI.md

@@ -79,6 +79,16 @@ mockFn.mock.instances[0] === a; // true
 mockFn.mock.instances[1] === b; // true
 ```
 
+### `mockFn.mock.lastCall`
+
+An array containing the call arguments of the last call that was made to this mock function. If the function was not called, it will return `undefined`.
+
+For example: A mock function `f` that has been called twice, with the arguments `f('arg1', 'arg2')`, and then with the arguments `f('arg3', 'arg4')`, would have a `mock.lastCall` array that looks like this:
+
+```js
+['arg3', 'arg4'];
+```
+
 ### `mockFn.mockClear()`
 
 Clears all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.

docs/MockFunctions.md

@@ -75,6 +75,9 @@ expect(someMockFunction.mock.instances.length).toBe(2);
 // The object returned by the first instantiation of this function
 // had a `name` property whose value was set to 'test'
 expect(someMockFunction.mock.instances[0].name).toEqual('test');
+
+// The first argument of the last call to the function was 'test'
+expect(someMockFunction.mock.lastCall[0]).toBe('test');
 ```
 
 ## Mock Return Values

packages/jest-mock/src/__tests__/index.test.ts

@@ -1064,6 +1064,32 @@ describe('moduleMocker', () => {
     expect(fn.getMockName()).toBe('myMockFn');
   });
 
+  test('jest.fn should provide the correct lastCall', () => {
+    const mock = jest.fn();
+
+    expect(mock.mock.lastCall).toBeUndefined();
+
+    mock('first');
+    mock('second');
+    mock('last', 'call');
+
+    expect(mock).toHaveBeenLastCalledWith('last', 'call');
+    expect(mock.mock.lastCall).toEqual(['last', 'call']);
+  });
+
+  test('lastCall gets reset by mockReset', () => {
+    const mock = jest.fn();
+
+    mock('first');
+    mock('last', 'call');
+
+    expect(mock.mock.lastCall).toEqual(['last', 'call']);
+
+    mock.mockReset();
+
+    expect(mock.mock.lastCall).toBeUndefined();
+  });
+
   test('mockName gets reset by mockReset', () => {
     const fn = jest.fn();
     expect(fn.getMockName()).toBe('jest.fn()');

packages/jest-mock/src/index.ts

@@ -166,6 +166,10 @@ type MockFunctionState<T, Y extends Array<unknown>> = {
   calls: Array<Y>;
   instances: Array<T>;
   invocationCallOrder: Array<number>;
+  /**
+   * Getter for retrieving the last call arguments
+   */
+  lastCall?: Y;
   /**
    * List of results of calls to the mock function.
    */
@@ -516,6 +520,9 @@ export class ModuleMocker {
       state = this._defaultMockState();
       this._mockState.set(f, state);
     }
+
+    state.lastCall = state.calls[state.calls.length - 1];
+
     return state;
   }
 
@@ -536,6 +543,7 @@ export class ModuleMocker {
       calls: [],
       instances: [],
       invocationCallOrder: [],
+      lastCall: undefined,
       results: [],
     };
   }

website/versioned_docs/version-25.x/MockFunctionAPI.md

@@ -79,6 +79,16 @@ mockFn.mock.instances[0] === a; // true
 mockFn.mock.instances[1] === b; // true
 ```
 
+### `mockFn.mock.lastCall`
+
+An array containing the call arguments of the last call that was made to this mock function. If the function was not called, it will return `undefined`.
+
+For example: A mock function `f` that has been called twice, with the arguments `f('arg1', 'arg2')`, and then with the arguments `f('arg3', 'arg4')`, would have a `mock.lastCall` array that looks like this:
+
+```js
+['arg3', 'arg4'];
+```
+
 ### `mockFn.mockClear()`
 
 Clears all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.

website/versioned_docs/version-25.x/MockFunctions.md

@@ -75,6 +75,9 @@ expect(someMockFunction.mock.instances.length).toBe(2);
 // The object returned by the first instantiation of this function
 // had a `name` property whose value was set to 'test'
 expect(someMockFunction.mock.instances[0].name).toEqual('test');
+
+// The first argument of the last call to the function was 'test'
+expect(someMockFunction.mock.lastCall[0]).toBe('test');
 ```
 
 ## Mock Return Values

website/versioned_docs/version-26.x/MockFunctionAPI.md

@@ -79,6 +79,16 @@ mockFn.mock.instances[0] === a; // true
 mockFn.mock.instances[1] === b; // true
 ```
 
+### `mockFn.mock.lastCall`
+
+An array containing the call arguments of the last call that was made to this mock function. If the function was not called, it will return `undefined`.
+
+For example: A mock function `f` that has been called twice, with the arguments `f('arg1', 'arg2')`, and then with the arguments `f('arg3', 'arg4')`, would have a `mock.lastCall` array that looks like this:
+
+```js
+['arg3', 'arg4'];
+```
+
 ### `mockFn.mockClear()`
 
 Clears all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.

website/versioned_docs/version-26.x/MockFunctions.md

@@ -75,6 +75,9 @@ expect(someMockFunction.mock.instances.length).toBe(2);
 // The object returned by the first instantiation of this function
 // had a `name` property whose value was set to 'test'
 expect(someMockFunction.mock.instances[0].name).toEqual('test');
+
+// The first argument of the last call to the function was 'test'
+expect(someMockFunction.mock.lastCall[0]).toBe('test');
 ```
 
 ## Mock Return Values

website/versioned_docs/version-27.0/MockFunctionAPI.md

@@ -79,6 +79,16 @@ mockFn.mock.instances[0] === a; // true
 mockFn.mock.instances[1] === b; // true
 ```
 
+### `mockFn.mock.lastCall`
+
+An array containing the call arguments of the last call that was made to this mock function. If the function was not called, it will return `undefined`.
+
+For example: A mock function `f` that has been called twice, with the arguments `f('arg1', 'arg2')`, and then with the arguments `f('arg3', 'arg4')`, would have a `mock.lastCall` array that looks like this:
+
+```js
+['arg3', 'arg4'];
+```
+
 ### `mockFn.mockClear()`
 
 Clears all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.

website/versioned_docs/version-27.0/MockFunctions.md

@@ -75,6 +75,9 @@ expect(someMockFunction.mock.instances.length).toBe(2);
 // The object returned by the first instantiation of this function
 // had a `name` property whose value was set to 'test'
 expect(someMockFunction.mock.instances[0].name).toEqual('test');
+
+// The first argument of the last call to the function was 'test'
+expect(someMockFunction.mock.lastCall[0]).toBe('test');
 ```
 
 ## Mock Return Values

website/versioned_docs/version-27.1/MockFunctionAPI.md

@@ -79,6 +79,16 @@ mockFn.mock.instances[0] === a; // true
 mockFn.mock.instances[1] === b; // true
 ```
 
+### `mockFn.mock.lastCall`
+
+An array containing the call arguments of the last call that was made to this mock function. If the function was not called, it will return `undefined`.
+
+For example: A mock function `f` that has been called twice, with the arguments `f('arg1', 'arg2')`, and then with the arguments `f('arg3', 'arg4')`, would have a `mock.lastCall` array that looks like this:
+
+```js
+['arg3', 'arg4'];
+```
+
 ### `mockFn.mockClear()`
 
 Clears all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.

website/versioned_docs/version-27.1/MockFunctions.md

@@ -75,6 +75,9 @@ expect(someMockFunction.mock.instances.length).toBe(2);
 // The object returned by the first instantiation of this function
 // had a `name` property whose value was set to 'test'
 expect(someMockFunction.mock.instances[0].name).toEqual('test');
+
+// The first argument of the last call to the function was 'test'
+expect(someMockFunction.mock.lastCall[0]).toBe('test');
 ```
 
 ## Mock Return Values

website/versioned_docs/version-27.2/MockFunctionAPI.md

@@ -79,6 +79,16 @@ mockFn.mock.instances[0] === a; // true
 mockFn.mock.instances[1] === b; // true
 ```
 
+### `mockFn.mock.lastCall`
+
+An array containing the call arguments of the last call that was made to this mock function. If the function was not called, it will return `undefined`.
+
+For example: A mock function `f` that has been called twice, with the arguments `f('arg1', 'arg2')`, and then with the arguments `f('arg3', 'arg4')`, would have a `mock.lastCall` array that looks like this:
+
+```js
+['arg3', 'arg4'];
+```
+
 ### `mockFn.mockClear()`
 
 Clears all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.

website/versioned_docs/version-27.2/MockFunctions.md

@@ -75,6 +75,9 @@ expect(someMockFunction.mock.instances.length).toBe(2);
 // The object returned by the first instantiation of this function
 // had a `name` property whose value was set to 'test'
 expect(someMockFunction.mock.instances[0].name).toEqual('test');
+
+// The first argument of the last call to the function was 'test'
+expect(someMockFunction.mock.lastCall[0]).toBe('test');
 ```
 
 ## Mock Return Values

website/versioned_docs/version-27.4/MockFunctions.md

@@ -75,6 +75,9 @@ expect(someMockFunction.mock.instances.length).toBe(2);
 // The object returned by the first instantiation of this function
 // had a `name` property whose value was set to 'test'
 expect(someMockFunction.mock.instances[0].name).toEqual('test');
+
+// The first argument of the last call to the function was 'test'
+expect(someMockFunction.mock.lastCall[0]).toBe('test');
 ```
 
 ## Mock Return Values