Added support for naming mocked functions

docs/en/JestObjectAPI.md

@@ -15,7 +15,7 @@ The `jest` object is automatically in scope within every test file. The methods
   - [`jest.clearAllTimers()`](#jestclearalltimers)
   - [`jest.disableAutomock()`](#jestdisableautomock)
   - [`jest.enableAutomock()`](#jestenableautomock)
-  - [`jest.fn(implementation)`](#jestfnimplementation)
+  - [`jest.fn(implementation, name)`](#jestfnimplementation)
   - [`jest.isMockFunction(fn)`](#jestismockfunctionfn)
   - [`jest.genMockFromModule(moduleName)`](#jestgenmockfrommodulemodulename)
   - [`jest.mock(moduleName, factory, options)`](#jestmockmodulename-factory-options)
@@ -65,8 +65,8 @@ Returns the `jest` object for chaining.
 
 *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.*
 
-### `jest.fn(implementation)`
-Returns a new, unused [mock function](/jest/docs/mock-function-api.html). Optionally takes a mock implementation.
+### `jest.fn(implementation, name)`
+Returns a new, unused [mock function](/jest/docs/mock-function-api.html). Optionally takes a mock implementation and/or a mock name.
 
 ```js
   const mockFn = jest.fn();
@@ -77,6 +77,17 @@ Returns a new, unused [mock function](/jest/docs/mock-function-api.html). Option
   const returnsTrue = jest.fn(() => true);
   console.log(returnsTrue()); // true;
 ```
+With mock name:
+```js
+  const mockFn = jest.fn('doesNothing');
+  mockFn();
+  expect(mockFn).toHaveBeenCalled();
+
+  // With a mock implementation:
+  const returnsTrue = jest.fn(() => true, 'returnsTrue');
+  console.log(returnsTrue()); // true;
+```
+
 
 ### `jest.isMockFunction(fn)`
 Determines if the given function is a mocked function.

docs/en/MockFunctionAPI.md

@@ -138,13 +138,32 @@ console.log(myMockFn(), myMockFn(), myMockFn(), myMockFn());
 > 'first call', 'second call', 'default', 'default'
 ```
 
-### `mockFn.mockReturnThis()`
-Just a simple sugar function for:
+### `mockFn.mockName(value)`
+Accepts a string to use in test result output in place of "jest.fn()" to indicate which mock function is being referenced.
+
+*Note: `jest.fn(implementation, name)` is a shorthand for `jest.fn().mockImplementation(implementation).mockName(name)`. Also, if you only provide a string to jest.fn(), it will be used as the mock name value.*
+
+For example:
 
 ```js
-jest.fn(function() {
-  return this;
-});
+const mockFn = jest.fn().mockName('mockedFunction');
+// mockFn();
+expect(mockFn).toHaveBeenCalled();
+```
+
+Will result in this error:
+```
+    expect(mockedFunction).toHaveBeenCalled()
+
+    Expected mock function to have been called.
+```
+
+Shorthand examples:
+
+```js
+const mockFn = jest.fn('mockedFunction');
+
+const mockFn2 = jest.fn(scalar => 42 + scalar, 'add42');
 ```
 
 ### `mockFn.mockReturnValue(value)`

docs/en/MockFunctions.md

@@ -217,6 +217,27 @@ const otherObj = {
 };
 ```
 
+## Mock Names
+
+You can optionally provide a name for your mock functions, which will be displayed instead of "jest.fn()" in test error output. Use this if you want to be able to quickly identify the mock function reporting an error in your test output.
+
+```javascript
+const myMockFn = jest.fn()
+  .mockReturnValue('default')
+  .mockImplementation(scalar => 42 + scalar)
+  .mockName('add42');
+
+const myMockFn2 = jest.fn(scalar => 42 + scalar, 'add42');
+```
+
+You can also pass a mock name without providing a mock implementation:
+
+```javascript
+const myMockFn = jest.fn('myMockFunction');
+// myMockFn();
+expect(myMockFn).toHaveBeenCalled();
+```
+
 ## Custom Matchers
 
 Finally, in order to make it simpler to assert how mock functions have been

integration_tests/__tests__/mock_names.test.js

@@ -0,0 +1,70 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+'use strict';
+
+const runJest = require('../runJest');
+const {extractSummary} = require('../utils');
+
+test('suite without mock name, mock called', () => {
+  const {stderr, status} = runJest('mock-names/without-mock-name');
+
+  expect(status).toBe(0);
+  expect(stderr).toMatch(/PASS/);
+});
+
+test('suite without mock name, mock not called', () => {
+  const {stderr, status} = runJest('mock-names/without-mock-name-not-called');
+
+  expect(status).toBe(1);
+  expect(stderr).toMatch(/expect\(jest\.fn\(\)\)\.toHaveBeenCalled/);
+});
+
+test('suite with mock name, mock called', () => {
+  const {stderr, status} = runJest('mock-names/with-mock-name');
+
+  expect(status).toBe(0);
+  expect(stderr).toMatch(/PASS/);
+});
+
+test('suite with mock name, mock not called', () => {
+  const {stderr, status} = runJest('mock-names/with-mock-name-not-called');
+
+  expect(status).toBe(1);
+  expect(stderr).toMatch(/expect\(myMockedFunction\)\.toHaveBeenCalled/);
+});
+
+test('suite with mock name, long form, mock called', () => {
+  const {stderr, status} = runJest('mock-names/with-mock-name-long');
+
+  expect(status).toBe(0);
+  expect(stderr).toMatch(/PASS/);
+});
+
+test('suite with mock name, long form, mock not called', () => {
+  const {stderr, status} = runJest('mock-names/with-mock-name-long-not-called');
+
+  expect(status).toBe(1);
+  expect(stderr).toMatch(/expect\(myMockedFunctionLong\)\.toHaveBeenCalled/);
+});
+
+test('suite with mock name, short form, mock called', () => {
+  const {stderr, status} = runJest('mock-names/with-mock-name-short');
+
+  expect(status).toBe(0);
+  expect(stderr).toMatch(/PASS/);
+});
+
+test('suite with mock name, short form, mock not called', () => {
+  const {stderr, status} = runJest(
+    'mock-names/with-mock-name-short-not-called',
+  );
+
+  expect(status).toBe(1);
+  expect(stderr).toMatch(/expect\(myMockedFunctionShort\)\.toHaveBeenCalled/);
+});

integration_tests/mock-names/with-empty-mock-name-not-called/__tests__/index.js

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+jest.mock('../');
+const importedFn = require('../');
+// empty mock name should result in default 'jest.fn()' output
+const mockFn = jest.fn(importedFn, '');
+
+test('first test', () => {
+  // mockFn explicitly not called to test error snapshot
+  expect(mockFn).toHaveBeenCalled();
+  expect(mockFn.mock.calls.length).toBe(1);
+});

integration_tests/mock-names/with-empty-mock-name-not-called/index.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+module.exports = () => {};

integration_tests/mock-names/with-empty-mock-name-not-called/package.json

@@ -0,0 +1,6 @@
+{
+  "jest": {
+    "testEnvironment": "node",
+    "clearMocks": true
+  }
+}

integration_tests/mock-names/with-empty-mock-name/__tests__/index.js

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+jest.mock('../');
+const importedFn = require('../');
+// empty mock name should result in default 'jest.fn()' output
+const mockFn = jest.fn(importedFn, '');
+
+test('first test', () => {
+  mockFn();
+  expect(mockFn).toHaveBeenCalled();
+  expect(mockFn.mock.calls.length).toBe(1);
+});

integration_tests/mock-names/with-empty-mock-name/index.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+module.exports = () => {};

integration_tests/mock-names/with-empty-mock-name/package.json

@@ -0,0 +1,6 @@
+{
+  "jest": {
+    "testEnvironment": "node",
+    "clearMocks": true
+  }
+}

integration_tests/mock-names/with-mock-name-long-not-called/__tests__/index.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+jest.mock('../');
+const importedFn = require('../');
+const mockFn = jest.fn(importedFn).mockName('myMockedFunctionLong');
+
+test('first test', () => {
+  // mockFn explicitly not called to test error snapshot
+  expect(mockFn).toHaveBeenCalled();
+  expect(mockFn.mock.calls.length).toBe(1);
+});

integration_tests/mock-names/with-mock-name-long-not-called/index.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+module.exports = () => {};

integration_tests/mock-names/with-mock-name-long-not-called/package.json

@@ -0,0 +1,6 @@
+{
+  "jest": {
+    "testEnvironment": "node",
+    "clearMocks": true
+  }
+}

integration_tests/mock-names/with-mock-name-long/__tests__/index.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+jest.mock('../');
+const importedFn = require('../');
+const mockFn = jest.fn(importedFn).mockName('myMockedFunctionLong');
+
+test('first test', () => {
+  mockFn();
+  expect(mockFn).toHaveBeenCalled();
+  expect(mockFn.mock.calls.length).toBe(1);
+});

integration_tests/mock-names/with-mock-name-long/index.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+module.exports = () => {};

integration_tests/mock-names/with-mock-name-long/package.json

@@ -0,0 +1,6 @@
+{
+  "jest": {
+    "testEnvironment": "node",
+    "clearMocks": true
+  }
+}

integration_tests/mock-names/with-mock-name-not-called/__tests__/index.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+jest.mock('../');
+const importedFn = require('../');
+const mockFn = jest.fn(importedFn, 'myMockedFunction');
+
+test('first test', () => {
+  // mockFn explicitly not called to test error snapshot
+  expect(mockFn).toHaveBeenCalled();
+  expect(mockFn.mock.calls.length).toBe(1);
+});

integration_tests/mock-names/with-mock-name-not-called/index.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+module.exports = () => {};

integration_tests/mock-names/with-mock-name-not-called/package.json

@@ -0,0 +1,6 @@
+{
+  "jest": {
+    "testEnvironment": "node",
+    "clearMocks": true
+  }
+}

integration_tests/mock-names/with-mock-name-short-not-called/__tests__/index.js

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+jest.mock('../');
+const mockFn = jest.fn('myMockedFunctionShort');
+
+test('first test', () => {
+  // mockFn explicitly not called to test error snapshot
+  expect(mockFn).toHaveBeenCalled();
+  expect(mockFn.mock.calls.length).toBe(1);
+});

integration_tests/mock-names/with-mock-name-short-not-called/index.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2014-present, Facebook, Inc. All rights reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow
+ */
+
+module.exports = () => {};

integration_tests/mock-names/with-mock-name-short-not-called/package.json

@@ -0,0 +1,6 @@
+{
+  "jest": {
+    "testEnvironment": "node",
+    "clearMocks": true
+  }
+}