Document class mocks (#5383)

* WIP on documenting ES6 class mocks

* WIP on Es6ClassMocks.md

* WIP on Es6ClassMocks.md

* Completed first draft of Es6ClassMocks.md

* Second draft of Es6ClassMocks.md

* Another draft of Es6ClassMocks.md. Still need to cut some content out - it's huge.

* WIP: Updating with new info on automatic mocks.

* WIP on Es6ClassMocks.md

* Final draft of Es6ClassMocks.md

* Keep code examples to 80 columns

* Updated changelog

* Removed incorrect statement about manual mocks

* Fixed linter errors

CHANGELOG.md

@@ -15,6 +15,8 @@
   ([#5376](https://github.com/facebook/jest/pull/5376))
 * `[expect]` Make `rejects` and `resolves` synchronously validate its argument.
   ([#5364](https://github.com/facebook/jest/pull/5364))
+* `[docs]` Add tutorial page for ES6 class mocks.
+  ([#5383]https://github.com/facebook/jest/pull/5383))
 
 ## jest 22.1.4
 

docs/Es6ClassMocks.md

@@ -0,0 +1,316 @@
+---
+id: es6-class-mocks
+title: ES6 Class Mocks
+---
+Jest can be used to mock ES6 classes that are imported into files you want to test.
+
+ES6 classes are constructor functions with some syntactic sugar. Therefore, any mock for an ES6 class must be a function or an actual ES6 class (which is, again, another function). So you can mock them using [mock functions](MockFunctions.md).
+
+## An ES6 Class Example
+We'll use a contrived example of a class that plays sound files, `SoundPlayer`, and a consumer class which uses that class, `SoundPlayerConsumer`. We'll mock `SoundPlayer` in our tests for `SoundPlayerConsumer`.
+
+```javascript
+// sound-player.js
+export default class SoundPlayer {
+  constructor() {
+    this.foo = 'bar';
+  }
+
+  playSoundFile(fileName) {
+    console.log('Playing sound file ' + fileName);
+  }
+}
+```
+
+```javascript
+// sound-player-consumer.js
+import SoundPlayer from './sound-player';
+
+export default class SoundPlayerConsumer {
+  constructor() {
+    this.soundPlayer = new SoundPlayer();
+  }
+
+  playSomethingCool() {
+    const coolSoundFileName = 'song.mp3';
+    this.soundPlayer.playSoundFile(coolSoundFileName);
+  }
+}
+```
+
+## The 4 ways to create an ES6 class mock
+
+### Automatic mock
+Calling `jest.mock('./sound-player')` returns a useful "automatic mock" you can use to spy on calls to the class constructor and all of its methods. It replaces the ES6 class with a mock constructor, and replaces all of its methods with [mock functions](MockFunctions.md) that always return `undefined`. Method calls are saved in `theAutomaticMock.mock.instances[index].methodName.mock.calls`.
+
+If you don't need to replace the implementation of the class, this is the easiest option to set up. For example:
+
+```javascript
+import SoundPlayer from './sound-player';
+import SoundPlayerConsumer from './sound-player-consumer';
+jest.mock('./sound-player'); // SoundPlayer is now a mock constructor
+
+beforeEach(() => {
+  // Clear all instances and calls to constructor and all methods:
+  SoundPlayer.mockClear();
+});
+
+it('We can check if the consumer called the class constructor', () => {
+  const soundPlayerConsumer = new SoundPlayerConsumer();
+  expect(SoundPlayer).toHaveBeenCalledTimes(1);
+});
+
+
+it('We can check if the consumer called a method on the class instance', () => {
+  // Show that mockClear() is working:
+  expect(SoundPlayer).not.toHaveBeenCalled();
+
+  const soundPlayerConsumer = new SoundPlayerConsumer();
+  // Constructor should have been called again:
+  expect(SoundPlayer).toHaveBeenCalledTimes(1);
+
+  const coolSoundFileName = 'song.mp3';
+  soundPlayerConsumer.playSomethingCool();
+
+  // mock.instances is available with automatic mocks:
+  const mockSoundPlayerInstance = SoundPlayer.mock.instances[0];
+  const mockPlaySoundFile = mockSoundPlayerInstance.playSoundFile;
+  expect(mockPlaySoundFile.mock.calls[0][0]).toEqual(coolSoundFileName);
+  // Equivalent to above check:
+  expect(mockPlaySoundFile).toHaveBeenCalledWith(coolSoundFileName);
+  expect(mockPlaySoundFile).toHaveBeenCalledTimes(1);
+});
+```
+
+### Manual mock
+Create a [manual mock](ManualMocks.md) by saving a mock implementation in the `__mocks__` folder. This allows you to specify the implementation, and it can be used across test files.
+
+```javascript
+// __mocks__/sound-player.js
+
+// Import this named export into your test file:
+export const mockPlaySoundFile = jest.fn();
+const mock = jest.fn().mockImplementation(() => {
+  return { playSoundFile: mockPlaySoundFile };
+});
+
+export default mock;
+```
+
+Import the mock and the mock method shared by all instances:
+```javascript
+// sound-player-consumer.test.js
+import SoundPlayer, { mockPlaySoundFile } from './sound-player';
+jest.mock('./sound-player'); // SoundPlayer is now a mock constructor
+
+beforeEach(() => {
+  // Clear all instances and calls to constructor and all methods:
+  SoundPlayer.mockClear();
+  mockPlaySoundFile.mockClear();
+});
+
+it('We can check if the consumer called the class constructor', () => {
+  const soundPlayerConsumer = new SoundPlayerConsumer();
+  expect(SoundPlayer).toHaveBeenCalledTimes(1);
+});
+
+
+it('We can check if the consumer called a method on the class instance', () => {
+  const soundPlayerConsumer = new SoundPlayerConsumer();
+  const coolSoundFileName = 'song.mp3';
+  soundPlayerConsumer.playSomethingCool();
+  expect(mockPlaySoundFile).toHaveBeenCalledWith(coolSoundFileName);
+});
+```
+
+### Calling  [`jest.mock()`](JestObjectAPI.md#jestmockmodulename-factory-options) with the module factory parameter
+`jest.mock(path, moduleFactory)` takes a **module factory** argument. A module factory is a function that returns the mock.
+
+In order to mock a constructor function, the module factory must return a constructor function. In other words, the module factory must be a function that returns a function - a higher-order function (HOF).
+
+```javascript
+import SoundPlayer from './sound-player';
+const mockPlaySoundFile = jest.fn();
+jest.mock('./sound-player', () => {
+  return jest.fn().mockImplementation(() => {
+    return { playSoundFile: mockPlaySoundFile };
+  });
+});
+```
+
+A limitation with the factory parameter is that, since calls to `jest.mock()` are hoisted to the top of the file, it's not possible to first define a variable and then use it in the factory. An exception is made for variables that start with the word 'mock'. It's up to you to guarantee that they will be initialized on time!
+
+### Replacing the mock using [`mockImplementation()`](MockFunctionAPI.md#mockfnmockimplementationfn) or [`mockImplementationOnce()`](MockFunctionAPI.md#mockfnmockimplementationoncefn)
+You can replace all of the above mocks in order to change the implementation, for a single test or all tests, by calling `mockImplementation()` on the existing mock.
+
+Calls to jest.mock are hoisted to the top of the code. You can specify a mock later, e.g. in `beforeAll()`, by calling `mockImplementation()` (or `mockImplementationOnce()`) on the existing mock instead of using the factory parameter. This also allows you to change the mock between tests, if needed:
+
+```javascript
+import SoundPlayer from './sound-player';
+jest.mock('./sound-player');
+
+describe('When SoundPlayer throws an error', () => {
+  beforeAll(() => {
+    SoundPlayer.mockImplementation(() => {
+      return { playSoundFile: () => { throw new Error('Test error')} };
+    });
+  });
+
+  it('Should throw an error when calling playSomethingCool', () => {
+    const soundPlayerConsumer = new SoundPlayerConsumer();
+    expect(() => soundPlayerConsumer.playSomethingCool()).toThrow();
+  });
+});
+```
+
+## In depth: Understanding mock constructor functions
+Building your constructor function mock using `jest.fn().mockImplementation()` makes mocks appear more complicated than they really are. This section shows how you can create your own simple mocks to illustrate how mocking works.
+
+### Manual mock that is another ES6 class
+If you define an ES6 class using the same filename as the mocked class in the `__mocks__` folder, it will serve as the mock. This class will be used in place of the real class. This allows you to inject a test implementation for the class, but does not provide a way to spy on calls.
+
+For the contrived example, the mock might look like this:
+
+```javascript
+// __mocks/sound-player.js
+export default class SoundPlayer {
+  constructor() {
+    console.log('Mock SoundPlayer: constructor was called');
+  }
+
+  playSoundFile() {
+    console.log('Mock SoundPlayer: playSoundFile was called');
+  }
+}
+```
+
+### Simple mock using module factory parameter
+The module factory function passed to `jest.mock(path, moduleFactory)` can be a HOF that returns a function*. This will allow calling `new` on the mock. Again, this allows you to inject different behavior for testing, but does not provide a way to spy on calls.
+
+#### * Module factory function must return a function
+In order to mock a constructor function, the module factory must return a constructor function. In other words, the module factory must be a function that returns a function - a higher-order function (HOF).
+
+```javascript
+jest.mock('./sound-player', () => {
+  return function() {
+    return { playSoundFile: () => {} };
+  };
+});
+```
+
+***Note: Arrow functions won't work***
+
+Note that the mock can't be an arrow function because calling `new` on an arrow function is not allowed in Javascript. So this won't work:
+
+```javascript
+jest.mock('./sound-player', () => {
+  return () => { // Does not work; arrow functions can't be called with new
+    return { playSoundFile: () => {} };
+  };
+});
+```
+
+This will throw ***TypeError: _soundPlayer2.default is not a constructor***, unless the code is transpiled to ES5, e.g. by babel-preset-env. (ES5 doesn't have arrow functions nor classes, so both will be transpiled to plain functions.)
+
+## Keeping track of usage (spying on the mock)
+Injecting a test implementation is helpful, but you will probably also want to test whether the class constructor and methods are called with the correct parameters.
+
+### Spying on the constructor
+
+In order to track calls to the constructor, replace the function returned by the HOF with a Jest mock function. Create it with [`jest.fn()`](JestObjectAPI.md#jestfnimplementation), and then specify its implementation with `mockImplementation()`.
+
+```javascript
+import SoundPlayer from './sound-player';
+jest.mock('./sound-player', () => {
+   // Works and lets you check for constructor calls:
+  return jest.fn().mockImplementation(() => {
+    return { playSoundFile: () => {} };
+  });
+});
+```
+
+This will let us inspect usage of our mocked class, using `SoundPlayer.mock.calls`:
+`expect(SoundPlayer).toHaveBeenCalled();`
+or near-equivalent:
+`expect(SoundPlayer.mock.calls.length).toEqual(1);`
+
+### Spying on methods of our class
+Our mocked class will need to provide any member functions (`playSoundFile` in the example) that will be called during our tests, or else we'll get an error for calling a function that doesn't exist. But we'll probably want to also spy on calls to those methods, to ensure that they were called with the expected parameters.
+
+A new object will be created each time the mock constructor function is called during tests. To spy on method calls in all of these objects, we populate `playSoundFile` with another mock function, and store a reference to that same mock function in our test file, so it's available during tests.
+
+```javascript
+import SoundPlayer from './sound-player';
+const mockPlaySoundFile = jest.fn();
+jest.mock('./sound-player', () => {
+  return jest.fn().mockImplementation(() => {
+    return { playSoundFile: mockPlaySoundFile };
+     // Now we can track calls to playSoundFile
+  });
+});
+```
+
+The manual mock equivalent of this would be:
+```javascript
+// __mocks__/sound-player.js
+
+// Import this named export into your test file
+export const mockPlaySoundFile = jest.fn();
+const mock = jest.fn().mockImplementation(() => {
+  return { playSoundFile: mockPlaySoundFile }
+});
+
+export default mock;
+```
+
+Usage is similar to the module factory function, except that you can omit the second argument from `jest.mock()`, and you must import the mocked method into your test file, since it is no longer defined there. Use the original module path for this; don't include `__mocks__`.
+
+### Cleaning up between tests
+To clear the record of calls to the mock constructor function and its methods, we call [`mockClear()`](MockFunctionAPI.md#mockfnmockclear) in the `beforeEach()` function:
+
+```javascript
+beforeEach(() => {
+  SoundPlayer.mockClear();
+  mockPlaySoundFile.mockClear();
+});
+```
+
+## Complete example
+Here's a complete test file which uses the module factory parameter to `jest.mock`:
+
+```javascript
+// sound-player-consumer.test.js
+import SoundPlayerConsumer from './sound-player-consumer';
+import SoundPlayer from './sound-player';
+
+const mockPlaySoundFile = jest.fn();
+jest.mock('./sound-player', () => {
+  return jest.fn().mockImplementation(() => {
+    return { playSoundFile: mockPlaySoundFile };
+  });
+});
+
+beforeEach(() => {
+  SoundPlayer.mockClear();
+  mockPlaySoundFile.mockClear();
+});
+
+it('The consumer should be able to call new() on SoundPlayer', () => {
+  const soundPlayerConsumer = new SoundPlayerConsumer();
+  // Ensure constructor created the object:
+  expect(soundPlayerConsumer).toBeTruthy();
+});
+
+it('We can check if the consumer called the class constructor', () => {
+  const soundPlayerConsumer = new SoundPlayerConsumer();
+  expect(SoundPlayer).toHaveBeenCalledTimes(1);
+});
+
+it('We can check if the consumer called a method on the class instance', () => {
+  const soundPlayerConsumer = new SoundPlayerConsumer();
+  const coolSoundFileName = 'song.mp3';
+  soundPlayerConsumer.playSomethingCool();
+  expect(mockPlaySoundFile.mock.calls[0][0]).toEqual(coolSoundFileName);
+});
+
+```

website/i18n/en.json

@@ -6,6 +6,7 @@
     "tagline": "🃏 Delightful JavaScript Testing",
     "cli": "Jest CLI Options",
     "configuration": "Configuring Jest",
+    "es6-class-mocks": "ES6 Class Mocks",
     "expect": "Expect",
     "getting-started": "Getting Started",
     "api": "Globals",

website/sidebars.json

@@ -14,6 +14,7 @@
       "tutorial-async",
       "timer-mocks",
       "manual-mocks",
+      "es6-class-mocks",
       "webpack",
       "puppeteer",
       "migration-guide",