Update documentation on automocking

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ### Fixes
 
+* `[docs]` Update automatic mocks documentation
+  ([#5630](https://github.com/facebook/jest/pull/5630))
 * `[expect]` Allow matching of Errors against plain objects
   ([#5611](https://github.com/facebook/jest/pull/5611))
 * `[jest-cli]` Don't skip matchers for exact files

docs/Configuration.md

@@ -54,10 +54,40 @@ configuration power.
 
 Default: `false`
 
-This option is disabled by default. If you are introducing Jest to a large
-organization with an existing codebase but few tests, enabling this option can
-be helpful to introduce unit tests gradually. Modules can be explicitly
-auto-mocked using `jest.mock(moduleName)`.
+This option tells Jest that all imported modules in your tests should be mocked
+automatically. All modules used in your tests will have a replacement
+implementation, keeping the API surface.
+
+Example:
+
+```js
+// utils.js
+export default {
+  authorize: () => {
+    return 'token';
+  },
+  isAuthorized: secret => secret === 'wizard',
+};
+```
+
+```js
+//__tests__/automocking.test.js
+import utils from '../utils';
+
+test('if utils mocked automatically', () => {
+  // Public methods of `utils` are now mock functions
+  expect(utils.authorize.mock).toBeTruthy();
+  expect(utils.isAuthorized.mock).toBeTruthy();
+
+  // You can provide them with your own implementation
+  // or just pass the expected return value
+  utils.authorize.mockReturnValue('mocked_token');
+  utils.isAuthorized.mockReturnValue(true);
+
+  expect(utils.authorize()).toBe('mocked_token');
+  expect(utils.isAuthorized('not_wizard')).toBeTruthy();
+});
+```
 
 _Note: Core modules, like `fs`, are not mocked by default. They can be mocked
 explicitly, like `jest.mock('fs')`._

docs/JestObjectAPI.md

@@ -49,9 +49,42 @@ will be cleared and will never have the opportunity to execute in the future.
 
 Disables automatic mocking in the module loader.
 
+> See `automock` section of [configuration](Configuration.md#automock-boolean)
+> for more information
+
 After this method is called, all `require()`s will return the real versions of
 each module (rather than a mocked version).
 
+Jest configuration:
+
+```json
+"automock": true
+```
+
+Example:
+
+```js
+// utils.js
+export default {
+  authorize: () => {
+    return 'token';
+  },
+};
+```
+
+```js
+// __tests__/disableAutomocking.js
+import utils from '../utils';
+
+jest.disableAutomock();
+
+test('original implementation', () => {
+  // now we have the original implementation,
+  // even if we set the automocking in a jest configuration
+  expect(utils.authorize()).toBe('token');
+});
+```
+
 This is usually useful when you have a scenario where the number of dependencies
 you want to mock is far less than the number of dependencies that you don't. For
 example, if you're writing a test for a module that uses a large number of
@@ -75,6 +108,34 @@ Enables automatic mocking in the module loader.
 
 Returns the `jest` object for chaining.
 
+> See `automock` section of [configuration](Configuration.md#automock-boolean)
+> for more information
+
+Example:
+
+```js
+// utils.js
+export default {
+  authorize: () => {
+    return 'token';
+  },
+  isAuthorized: secret => secret === 'wizard',
+};
+```
+
+```js
+// __tests__/disableAutomocking.js
+jest.enableAutomock();
+
+import utils from '../utils';
+
+test('original implementation', () => {
+  // now we have the mocked implementation,
+  expect(utils.authorize._isMockFunction).toBeTruthy();
+  expect(utils.isAuthorized._isMockFunction).toBeTruthy();
+});
+```
+
 _Note: this method was previously called `autoMockOn`. When using `babel-jest`,
 calls to `enableAutomock` will automatically be hoisted to the top of the code
 block. Use `autoMockOn` if you want to explicitly avoid this behavior._
@@ -106,6 +167,29 @@ mocked version of the module for you.
 This is useful when you want to create a [manual mock](ManualMocks.md) that
 extends the automatic mock's behavior.
 
+Example:
+
+```js
+// utils.js
+export default {
+  authorize: () => {
+    return 'token';
+  },
+  isAuthorized: secret => secret === 'wizard',
+};
+```
+
+```js
+// __tests__/genMockFromModule.test.js
+const utils = jest.genMockFromModule('../utils').default;
+utils.isAuthorized = jest.fn(secret => secret === 'not wizard');
+
+test('implementation created by jest.genMockFromModule', () => {
+  expect(utils.authorize.mock).toBeTruthy();
+  expect(utils.isAuthorized('not wizard')).toEqual(true);
+});
+```
+
 ### `jest.mock(moduleName, factory, options)`
 
 Mocks a module with an auto-mocked version when it is being required. `factory`

examples/automatic_mocks/.babelrc

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

examples/automatic_mocks/__tests__/automock.test.js

@@ -0,0 +1,16 @@
+// Copyright 2004-present Facebook. All Rights Reserved.
+
+import utils from '../utils';
+
+test('if utils are mocked', () => {
+  expect(utils.authorize.mock).toBeTruthy();
+  expect(utils.isAuthorized.mock).toBeTruthy();
+});
+
+test('mocked implementation', () => {
+  utils.authorize.mockReturnValue('mocked_token');
+  utils.isAuthorized.mockReturnValue(true);
+
+  expect(utils.authorize()).toBe('mocked_token');
+  expect(utils.isAuthorized('not_wizard')).toBeTruthy();
+});

examples/automatic_mocks/__tests__/disableAutomocking.test.js

@@ -0,0 +1,9 @@
+// Copyright 2004-present Facebook. All Rights Reserved.
+
+import utils from '../utils';
+
+jest.disableAutomock();
+
+test('original implementation', () => {
+  expect(utils.authorize()).toBe('token');
+});

examples/automatic_mocks/__tests__/genMockFromModule.test.js

@@ -0,0 +1,16 @@
+// Copyright 2004-present Facebook. All Rights Reserved.
+
+import utils from '../utils';
+
+test('implementation created by automock', () => {
+  expect(utils.authorize('wizzard')).toBeUndefined();
+  expect(utils.isAuthorized()).toBeUndefined();
+});
+
+test('implementation created by jest.genMockFromModule', () => {
+  const utils = jest.genMockFromModule('../utils').default;
+  utils.isAuthorized = jest.fn(secret => secret === 'not wizard');
+
+  expect(utils.authorize.mock).toBeTruthy();
+  expect(utils.isAuthorized('not wizard')).toEqual(true);
+});

examples/automatic_mocks/package.json

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

examples/automatic_mocks/utils.js

@@ -0,0 +1,8 @@
+// Copyright 2004-present Facebook. All Rights Reserved.
+
+export default {
+  authorize: () => {
+    return 'token';
+  },
+  isAuthorized: secret => secret === 'wizard',
+};