Added module mock example (#4199)

* Added module mock example

* Simplified the code in the partial mock example.

* Added file illustrating how to define mock behaviour per test

Simplified some of the test code and improved descriptions per test.

examples/module_mock/.babelrc

@@ -0,0 +1,3 @@
+{
+  "presets": ["env"]
+}

examples/module_mock/__tests__/full_mock.js

@@ -0,0 +1,14 @@
+// Copyright 2004-present Facebook. All Rights Reserved.
+
+import defaultExport, {apple, strawberry} from '../fruit';
+
+/**
+ * This file illustrates a full mock of a module.
+ */
+jest.mock('../fruit');
+
+it('does a full mock', () => {
+  expect(defaultExport()).toBe(undefined);
+  expect(apple).toBe('apple');
+  expect(strawberry()).toBe(undefined);
+});

examples/module_mock/__tests__/mock_per_test.js

@@ -0,0 +1,41 @@
+// Copyright 2004-present Facebook. All Rights Reserved.
+
+/**
+ * This file illustrates how to define a custom mock per test.
+ *
+ * The file contains two test cases:
+ * - One where the fruit module is mocked.
+ * - One where the fruit module is not mocked.
+ */
+describe('define mock per test', () => {
+  beforeEach(() => {
+    jest.resetModules();
+  });
+
+  it('uses mocked module', () => {
+    jest.doMock('../fruit', () => ({
+      apple: 'mocked apple',
+      default: jest.fn(() => 'mocked fruit'),
+      strawberry: jest.fn(() => 'mocked strawberry'),
+    }));
+    const {apple, strawberry, default: defaultExport} = require('../fruit');
+
+    const defaultExportResult = defaultExport();
+    expect(defaultExportResult).toBe('mocked fruit');
+    expect(defaultExport).toHaveBeenCalled();
+
+    expect(apple).toBe('mocked apple');
+    expect(strawberry()).toBe('mocked strawberry');
+  });
+
+  it('uses actual module', () => {
+    jest.dontMock('../fruit');
+    const {apple, strawberry, default: defaultExport} = require('../fruit');
+
+    const defaultExportResult = defaultExport();
+    expect(defaultExportResult).toBe('banana');
+
+    expect(apple).toBe('apple');
+    expect(strawberry()).toBe('strawberry');
+  });
+});

examples/module_mock/__tests__/partial_mock.js

@@ -0,0 +1,28 @@
+// Copyright 2004-present Facebook. All Rights Reserved.
+
+/**
+ * This file illustrates how to do a partial mock where a subset
+ * of a module's exports have been mocked and the rest
+ * keep their actual implementation.
+ */
+import defaultExport, {apple, strawberry} from '../fruit';
+
+jest.mock('../fruit', () => {
+  const originalModule = require.requireActual('../fruit');
+  const mockedModule = jest.genMockFromModule('../fruit');
+
+  //Mock the default export and named export 'apple'.
+  return Object.assign({}, mockedModule, originalModule, {
+    apple: 'mocked apple',
+    default: jest.fn(() => 'mocked fruit'),
+  });
+});
+
+it('does a partial mock', () => {
+  const defaultExportResult = defaultExport();
+  expect(defaultExportResult).toBe('mocked fruit');
+  expect(defaultExport).toHaveBeenCalled();
+
+  expect(apple).toBe('mocked apple');
+  expect(strawberry()).toBe('strawberry');
+});

examples/module_mock/fruit.js

@@ -0,0 +1,7 @@
+// Copyright 2004-present Facebook. All Rights Reserved.
+
+export const apple = 'apple';
+
+export const strawberry = () => 'strawberry';
+
+export default () => 'banana';

examples/module_mock/package.json

@@ -0,0 +1,9 @@
+{
+  "devDependencies": {
+    "babel-preset-env": "*",
+    "jest": "*"
+  },
+  "scripts": {
+    "test": "jest"
+  }
+}