Add documentation related to auto-mocking

CHANGELOG.md

@@ -13,6 +13,7 @@
 
 ### Chore & Maintenance
 
+- `[*]` Add documentation and tests related to auto-mocking ([#8086](https://github.com/facebook/jest/pull/8099))
 - `[*]` Make sure to include `d.ts` files in the tarball when building ([#8086](https://github.com/facebook/jest/pull/8086))
 
 ### Performance

docs/JestObjectAPI.md

@@ -119,6 +119,102 @@ test('implementation created by jest.genMockFromModule', () => {
 });
 ```
 
+This is how `genMockFromModule` will mock the follwing data types:
+
+#### `Function`
+
+A new [mock function](https://jestjs.io/docs/en/mock-functions.html) will be created. The new function will have no formal parameters and when called will return `undefined`. This functionality also applies to `async functions`.
+
+#### `Class`
+
+A new class will be created. The interface of the original class is maintained however all of the class member functions and properties will be mocked.
+
+#### `Object`
+
+Objects are deeply cloned. Their keys are maintained and their values are mocked.
+
+#### `Array`
+
+The original array is ignored and a new empty array is created.
+
+#### `String`
+
+A new copy of the original string is mocked.
+
+#### `Number`
+
+A new copy of the original number is mocked.
+
+Example:
+
+<!-- prettier-ignore -->
+```js
+// example.js
+module.exports = {
+  function: function foo(a, b) {
+    return a + b;
+  },
+  asyncFunction: async function asyncFoo(a, b) {
+    const result = await a + b;
+    return result;
+  },
+  class: new class Bar {
+    constructor() {
+      this.array = [1, 2, 3];
+    }
+    foo() {}
+  },
+  object: {
+    baz: 'foo',
+    bar: {
+      fiz: 1,
+      buzz: [1, 2, 3],
+    },
+  },
+  array: [1, 2, 3],
+  number: 123,
+  string: 'baz',
+};
+```
+
+```js
+// __tests__/example.test.js
+const example = jest.genMockFromModule('./example');
+
+test('should run example code', () => {
+  // a new mocked function with no formal arguments.
+  expect(example.function.name).toEqual('foo');
+  expect(example.function.length).toEqual(0);
+
+  // async functions are treated just like standard synchronous functions.
+  expect(example.asyncFunction.name).toEqual('asyncFoo');
+  expect(example.asyncFunction.length).toEqual(0);
+
+  // a new mocked class that maintains the original interface and mocks member functions and properties.
+  expect(example.class.constructor.name).toEqual('Bar');
+  expect(example.class.foo.name).toEqual('foo');
+  expect(example.class.array.length).toEqual(0);
+
+  // a deeply cloned object that maintains the original interface and mocks it's values.
+  expect(example.object).toEqual({
+    baz: 'foo',
+    bar: {
+      fiz: 1,
+      buzz: [],
+    },
+  });
+
+  // the original array is ignored and a new emtpy array is mocked.
+  expect(example.array.length).toEqual(0);
+
+  // a new copy of the original number.
+  expect(example.number).toEqual(123);
+
+  // a new copy of the original string.
+  expect(example.string).toEqual('baz');
+});
+```
+
 ### `jest.mock(moduleName, factory, options)`
 
 Mocks a module with an auto-mocked version when it is being required. `factory` and `options` are optional. For example:

packages/jest-mock/src/__tests__/index.test.ts

@@ -34,6 +34,7 @@ describe('moduleMocker', () => {
       expect(moduleMocker.getMetadata('banana').value).toEqual('banana');
       expect(moduleMocker.getMetadata(27).value).toEqual(27);
       expect(moduleMocker.getMetadata(false).value).toEqual(false);
+      expect(moduleMocker.getMetadata(Infinity).value).toEqual(Infinity);
     });
 
     it('does not retrieve metadata for arrays', () => {
@@ -57,6 +58,51 @@ describe('moduleMocker', () => {
       expect(metadata.members).toBeUndefined();
       expect(metadata.type).toEqual('null');
     });
+
+    it('retrieves metadata for ES6 classes', () => {
+      class ClassFooMock {
+        bar() {}
+      }
+      const fooInstance = new ClassFooMock();
+      const metadata = moduleMocker.getMetadata(fooInstance);
+      expect(metadata.type).toEqual('object');
+      expect(metadata.members.constructor.name).toEqual('ClassFooMock');
+    });
+
+    it('retrieves synchronous function metadata', () => {
+      function functionFooMock() {}
+      const metadata = moduleMocker.getMetadata(functionFooMock);
+      expect(metadata.type).toEqual('function');
+      expect(metadata.name).toEqual('functionFooMock');
+    });
+
+    it('retrieves asynchronous function metadata', () => {
+      async function asyncFunctionFooMock() {}
+      const metadata = moduleMocker.getMetadata(asyncFunctionFooMock);
+      expect(metadata.type).toEqual('function');
+      expect(metadata.name).toEqual('asyncFunctionFooMock');
+    });
+
+    it("retrieves metadata for object literals and it's members", () => {
+      const metadata = moduleMocker.getMetadata({
+        bar: 'two',
+        foo: 1,
+      });
+      expect(metadata.type).toEqual('object');
+      expect(metadata.members.bar.value).toEqual('two');
+      expect(metadata.members.bar.type).toEqual('constant');
+      expect(metadata.members.foo.value).toEqual(1);
+      expect(metadata.members.foo.type).toEqual('constant');
+    });
+
+    it('retrieves Date object metadata', () => {
+      const metadata = moduleMocker.getMetadata(Date);
+      expect(metadata.type).toEqual('function');
+      expect(metadata.name).toEqual('Date');
+      expect(metadata.members.now.name).toEqual('now');
+      expect(metadata.members.parse.name).toEqual('parse');
+      expect(metadata.members.UTC.name).toEqual('UTC');
+    });
   });
 
   describe('generateFromMetadata', () => {

website/versioned_docs/version-22.x/JestObjectAPI.md

@@ -173,6 +173,102 @@ test('implementation created by jest.genMockFromModule', () => {
 });
 ```
 
+This is how `genMockFromModule` will mock the follwing data types:
+
+#### `Function`
+
+A new [mock function](https://jestjs.io/docs/en/mock-functions.html) will be created. The new function will have no formal parameters and when called will return `undefined`. This functionality also applies to `async functions`.
+
+#### `Class`
+
+A new class will be created. The interface of the original class is maintained however all of the class member functions and properties will be mocked.
+
+#### `Object`
+
+Objects are deeply cloned. Their keys are maintained and their values are mocked.
+
+#### `Array`
+
+The original array is ignored and a new empty array is created.
+
+#### `String`
+
+A new copy of the original string is mocked.
+
+#### `Number`
+
+A new copy of the original number is mocked.
+
+Example:
+
+<!-- prettier-ignore -->
+```js
+// example.js
+module.exports = {
+  function: function foo(a, b) {
+    return a + b;
+  },
+  asyncFunction: async function asyncFoo(a, b) {
+    const result = await a + b;
+    return result;
+  },
+  class: new class Bar {
+    constructor() {
+      this.array = [1, 2, 3];
+    }
+    foo() {}
+  },
+  object: {
+    baz: 'foo',
+    bar: {
+      fiz: 1,
+      buzz: [1, 2, 3],
+    },
+  },
+  array: [1, 2, 3],
+  number: 123,
+  string: 'baz',
+};
+```
+
+```js
+// __tests__/example.test.js
+const example = jest.genMockFromModule('./example');
+
+test('should run example code', () => {
+  // a new mocked function with no formal arguments.
+  expect(example.function.name).toEqual('foo');
+  expect(example.function.length).toEqual(0);
+
+  // async functions are treated just like standard synchronous functions.
+  expect(example.asyncFunction.name).toEqual('asyncFoo');
+  expect(example.asyncFunction.length).toEqual(0);
+
+  // a new mocked class that maintains the original interface and mocks member functions and properties.
+  expect(example.class.constructor.name).toEqual('Bar');
+  expect(example.class.foo.name).toEqual('foo');
+  expect(example.class.array.length).toEqual(0);
+
+  // a deeply cloned object that maintains the original interface and mocks it's values.
+  expect(example.object).toEqual({
+    baz: 'foo',
+    bar: {
+      fiz: 1,
+      buzz: [],
+    },
+  });
+
+  // the original array is ignored and a new emtpy array is mocked.
+  expect(example.array.length).toEqual(0);
+
+  // a new copy of the original number.
+  expect(example.number).toEqual(123);
+
+  // a new copy of the original string.
+  expect(example.string).toEqual('baz');
+});
+```
+
 ### `jest.mock(moduleName, factory, options)`
 
 Mocks a module with an auto-mocked version when it is being required. `factory` and `options` are optional. For example:

website/versioned_docs/version-23.x/JestObjectAPI.md

@@ -174,6 +174,102 @@ test('implementation created by jest.genMockFromModule', () => {
 });
 ```
 
+This is how `genMockFromModule` will mock the follwing data types:
+
+#### `Function`
+
+A new [mock function](https://jestjs.io/docs/en/mock-functions.html) will be created. The new function will have no formal parameters and when called will return `undefined`. This functionality also applies to `async functions`.
+
+#### `Class`
+
+A new class will be created. The interface of the original class is maintained however all of the class member functions and properties will be mocked.
+
+#### `Object`
+
+Objects are deeply cloned. Their keys are maintained and their values are mocked.
+
+#### `Array`
+
+The original array is ignored and a new empty array is created.
+
+#### `String`
+
+A new copy of the original string is mocked.
+
+#### `Number`
+
+A new copy of the original number is mocked.
+
+Example:
+
+<!-- prettier-ignore -->
+```js
+// example.js
+module.exports = {
+  function: function foo(a, b) {
+    return a + b;
+  },
+  asyncFunction: async function asyncFoo(a, b) {
+    const result = await a + b;
+    return result;
+  },
+  class: new class Bar {
+    constructor() {
+      this.array = [1, 2, 3];
+    }
+    foo() {}
+  },
+  object: {
+    baz: 'foo',
+    bar: {
+      fiz: 1,
+      buzz: [1, 2, 3],
+    },
+  },
+  array: [1, 2, 3],
+  number: 123,
+  string: 'baz',
+};
+```
+
+```js
+// __tests__/example.test.js
+const example = jest.genMockFromModule('./example');
+
+test('should run example code', () => {
+  // a new mocked function with no formal arguments.
+  expect(example.function.name).toEqual('foo');
+  expect(example.function.length).toEqual(0);
+
+  // async functions are treated just like standard synchronous functions.
+  expect(example.asyncFunction.name).toEqual('asyncFoo');
+  expect(example.asyncFunction.length).toEqual(0);
+
+  // a new mocked class that maintains the original interface and mocks member functions and properties.
+  expect(example.class.constructor.name).toEqual('Bar');
+  expect(example.class.foo.name).toEqual('foo');
+  expect(example.class.array.length).toEqual(0);
+
+  // a deeply cloned object that maintains the original interface and mocks it's values.
+  expect(example.object).toEqual({
+    baz: 'foo',
+    bar: {
+      fiz: 1,
+      buzz: [],
+    },
+  });
+
+  // the original array is ignored and a new emtpy array is mocked.
+  expect(example.array.length).toEqual(0);
+
+  // a new copy of the original number.
+  expect(example.number).toEqual(123);
+
+  // a new copy of the original string.
+  expect(example.string).toEqual('baz');
+});
+```
+
 ### `jest.mock(moduleName, factory, options)`
 
 Mocks a module with an auto-mocked version when it is being required. `factory` and `options` are optional. For example: