Update documentation on automocking (#5630)

CHANGELOG.md

@@ -54,6 +54,11 @@
 * `[docs]` Add a documentation note for project `displayName` configuration
  ([#5600](https://github.com/facebook/jest/pull/5600))
 
+# Chore & Maintenance
+
+* `[docs]` Update automatic mocks documentation
+ ([#5630](https://github.com/facebook/jest/pull/5630))
+
 ## jest 22.3.0
 
 ### Fixes

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',
+};