Add contexts to mocks

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[jest-mock]` Add `contexts` member to mocks ([#12601](https://github.com/facebook/jest/pull/12601))
 - `[babel-jest]` Export `createTransformer` function ([#12399](https://github.com/facebook/jest/pull/12399))
 - `[expect]` Expose `AsymmetricMatchers`, `MatcherFunction` and `MatcherFunctionWithState` interfaces ([#12363](https://github.com/facebook/jest/pull/12363), [#12376](https://github.com/facebook/jest/pull/12376))
 - `[jest-circus, jest-jasmine2]` Allowed classes and functions as `describe` and `it`/`test` names ([#12484](https://github.com/facebook/jest/pull/12484))

packages/jest-cli/src/cli/args.ts

@@ -154,7 +154,7 @@ export const options = {
   },
   clearMocks: {
     description:
-      'Automatically clear mock calls, instances and results before every test. ' +
+      'Automatically clear mock calls, instances, contexts and results before every test. ' +
       'Equivalent to calling jest.clearAllMocks() before each test.',
     type: 'boolean',
   },

packages/jest-cli/src/init/__tests__/__snapshots__/init.test.js.snap

@@ -108,7 +108,7 @@ Array [
   },
   Object {
     "initial": false,
-    "message": "Automatically clear mock calls, instances and results before every test?",
+    "message": "Automatically clear mock calls, instances, contexts and results before every test?",
     "name": "clearMocks",
     "type": "confirm",
   },
@@ -131,7 +131,7 @@ module.exports = {
   // The directory where Jest should store its cached dependency information
   // cacheDirectory: "/tmp/jest",
 
-  // Automatically clear mock calls, instances and results before every test
+  // Automatically clear mock calls, instances, contexts and results before every test
   // clearMocks: false,
 
   // Indicates whether the coverage information should be collected while executing the test

packages/jest-cli/src/init/questions.ts

@@ -43,7 +43,7 @@ const defaultQuestions: Array<PromptObject> = [
   {
     initial: false,
     message:
-      'Automatically clear mock calls, instances and results before every test?',
+      'Automatically clear mock calls, instances, contexts and results before every test?',
     name: 'clearMocks',
     type: 'confirm',
   },

packages/jest-config/src/Descriptions.ts

@@ -13,7 +13,7 @@ const descriptions: {[key in keyof Config.InitialOptions]: string} = {
   cacheDirectory:
     'The directory where Jest should store its cached dependency information',
   clearMocks:
-    'Automatically clear mock calls, instances and results before every test',
+    'Automatically clear mock calls, instances, contexts and results before every test',
   collectCoverage:
     'Indicates whether the coverage information should be collected while executing the test',
   collectCoverageFrom:

packages/jest-environment/src/index.ts

@@ -71,7 +71,7 @@ export interface Jest {
    */
   autoMockOn(): Jest;
   /**
-   * Clears the `mock.calls`, `mock.instances` and `mock.results` properties of
+   * Clears the `mock.calls`, `mock.instances`, `mock.contexts` and `mock.results` properties of
    * all mocks. Equivalent to calling `.mockClear()` on every mocked function.
    */
   clearAllMocks(): Jest;

packages/jest-mock/__typetests__/mock-functions.test.ts

@@ -118,7 +118,9 @@ expectType<
   }>
 >(MockObject.mock.instances);
 
-const returnValue = mockFn.mock.results[0];
+const returnValue =
+
+mockFn.mock.contexts[0];
 
 expectType<'incomplete' | 'return' | 'throw'>(returnValue.type);
 expectType<unknown>(returnValue.value);

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

@@ -424,20 +424,53 @@ describe('moduleMocker', () => {
         expect(fn.mock.instances[1]).toBe(instance2);
       });
 
+      it('tracks context objects passed to mock calls', () => {
+        const fn = moduleMocker.fn();
+        expect(fn.mock.instances).toEqual([]);
+
+        const ctx0 = {};
+        fn.apply(ctx0, []);
+        expect(fn.mock.contexts[0]).toBe(ctx0);
+
+        const ctx1 = {};
+        fn.call(ctx1);
+        expect(fn.mock.contexts[1]).toBe(ctx1);
+
+        const ctx2 = {};
+        const bound2 = fn.bind(ctx2);
+        bound2();
+        expect(fn.mock.contexts[2]).toBe(ctx2);
+
+        // null context
+        fn.apply(null, []);
+        expect(fn.mock.contexts[3]).toBe(null);
+        fn.call(null);
+        expect(fn.mock.contexts[4]).toBe(null);
+        fn.bind(null)();
+        expect(fn.mock.contexts[5]).toBe(null);
+
+        // Unspecified context is `undefined` in strict mode (like in this test) and `window` otherwise.
+        fn();
+        expect(fn.mock.contexts[6]).toBe(undefined);
+      });
+
       it('supports clearing mock calls', () => {
         const fn = moduleMocker.fn();
         expect(fn.mock.calls).toEqual([]);
 
         fn(1, 2, 3);
         expect(fn.mock.calls).toEqual([[1, 2, 3]]);
+        expect(fn.mock.contexts).toEqual([undefined]);
 
         fn.mockReturnValue('abcd');
 
         fn.mockClear();
         expect(fn.mock.calls).toEqual([]);
+        expect(fn.mock.contexts).toEqual([]);
 
         fn('a', 'b', 'c');
         expect(fn.mock.calls).toEqual([['a', 'b', 'c']]);
+        expect(fn.mock.contexts).toEqual([undefined]);
 
         expect(fn()).toEqual('abcd');
       });

packages/jest-mock/src/index.ts

@@ -201,6 +201,10 @@ type MockFunctionState<T extends FunctionLike = UnknownFunction> = {
    * List of all the object instances that have been instantiated from the mock.
    */
   instances: Array<ReturnType<T>>;
+  /**
+   * List of all the function contexts that have been applied to calls to the mock.
+   */
+  contexts: Array<unknown>;
   /**
    * List of the call order indexes of the mock. Jest is indexing the order of
    * invocations of all mocks in a test file. The index is starting with `1`.
@@ -570,6 +574,7 @@ export class ModuleMocker {
     return {
       calls: [],
       instances: [],
+      contexts: [],
       invocationCallOrder: [],
       results: [],
     };
@@ -636,6 +641,7 @@ export class ModuleMocker {
         const mockState = mocker._ensureMockState(f);
         const mockConfig = mocker._ensureMockConfig(f);
         mockState.instances.push(this);
+        mockState.contexts.push(this);
         mockState.calls.push(args);
         // Create and record an "incomplete" mock result immediately upon
         // calling rather than waiting for the mock to return. This avoids

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

@@ -560,7 +560,7 @@ test('plays audio', () => {
 
 ### `jest.clearAllMocks()`
 
-Clears the `mock.calls`, `mock.instances` and `mock.results` properties of all mocks. Equivalent to calling [`.mockClear()`](MockFunctionAPI.md#mockfnmockclear) on every mocked function.
+Clears the `mock.calls`, `mock.instances`, `mock.contexts` and `mock.results` properties of all mocks. Equivalent to calling [`.mockClear()`](MockFunctionAPI.md#mockfnmockclear) on every mocked function.
 
 Returns the `jest` object for chaining.
 

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

@@ -79,9 +79,34 @@ mockFn.mock.instances[0] === a; // true
 mockFn.mock.instances[1] === b; // true
 ```
 
+
+### `mockFn.mock.contexts`
+
+An array that contains the contexts for all calls of the mock function.
+
+A context is the `this` value that a function receives when called.
+The context can be set using 
+`Function.prototype.bind`, `Function.prototype.call` or `Function.prototype.apply`.
+
+For example:
+
+```js
+const mockFn = jest.fn();
+
+const boundMockFn = mockFn.bind(thisContext0);
+boundMockFn('a', 'b');
+mockFn.call(thisContext1, 'a', 'b');
+mockFn.apply(thisContext2, ['a', 'b']);
+
+mockFn.mock.contexts[0] === thisContext0; // true
+mockFn.mock.contexts[1] === thisContext1; // true
+mockFn.mock.contexts[2] === thisContext2; // true
+```
+
+
 ### `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.
+Clears all information stored in the [`mockFn.mock.calls`](#mockfnmockcalls), [`mockFn.mock.instances`](#mockfnmockinstances) [`mockFn.mock.contexts`](#mockfnmockcontexts) and [`mockFn.mock.results`](#mockfnmockresults) arrays. Often this is useful when you want to clean up a mocks usage data between two assertions.
 
 Beware that `mockClear` will replace `mockFn.mock`, not just these three properties! You should, therefore, avoid assigning `mockFn.mock` to other variables, temporary or not, to make sure you don't access stale data.
 

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

@@ -69,6 +69,9 @@ expect(someMockFunction.mock.calls[0][1]).toBe('second arg');
 // The return value of the first call to the function was 'return value'
 expect(someMockFunction.mock.results[0].value).toBe('return value');
 
+// The function was called with a certain `this` context: the `element` object.
+expect(someMockFunction.mock.contexts[0]).toBe(element);
+
 // This function was instantiated exactly twice
 expect(someMockFunction.mock.instances.length).toBe(2);
 

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

@@ -140,7 +140,7 @@ Deletes the Jest cache directory and then exits without running tests. Will dele
 
 ### `--clearMocks`
 
-Automatically clear mock calls, instances and results before every test. Equivalent to calling [`jest.clearAllMocks()`](JestObjectAPI.md#jestclearallmocks) before each test. This does not remove any mock implementation that may have been provided.
+Automatically clear mock calls, instances, contexts, and results before every test. Equivalent to calling [`jest.clearAllMocks()`](JestObjectAPI.md#jestclearallmocks) before each test. This does not remove any mock implementation that may have been provided.
 
 ### `--collectCoverageFrom=<glob>`
 

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

@@ -146,7 +146,7 @@ Jest attempts to scan your dependency tree once (up-front) and cache it in order
 
 Default: `false`
 
-Automatically clear mock calls, instances and results before every test. Equivalent to calling [`jest.clearAllMocks()`](JestObjectAPI.md#jestclearallmocks) before each test. This does not remove any mock implementation that may have been provided.
+Automatically clear mock calls, instances, contexts and results before every test. Equivalent to calling [`jest.clearAllMocks()`](JestObjectAPI.md#jestclearallmocks) before each test. This does not remove any mock implementation that may have been provided.
 
 ### `collectCoverage` \[boolean]
 

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

@@ -564,7 +564,7 @@ test('plays audio', () => {
 
 ### `jest.clearAllMocks()`
 
-Clears the `mock.calls`, `mock.instances` and `mock.results` properties of all mocks. Equivalent to calling [`.mockClear()`](MockFunctionAPI.md#mockfnmockclear) on every mocked function.
+Clears the `mock.calls`, `mock.instances`, `mock.contexts` and `mock.results` properties of all mocks. Equivalent to calling [`.mockClear()`](MockFunctionAPI.md#mockfnmockclear) on every mocked function.
 
 Returns the `jest` object for chaining.