From 746ea44b5434cd64a233696768a21432ac4ac070 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Sun, 10 Mar 2019 11:14:05 -0700 Subject: [PATCH 01/13] add tests and documentation related to auto mocking --- docs/JestObjectAPI.md | 86 +++++++++++++++++++ .../jest-mock/src/__tests__/index.test.ts | 46 ++++++++++ 2 files changed, 132 insertions(+) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index 4b4fea15dfed..d8f5a0f8d03a 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -119,6 +119,92 @@ test('implementation created by jest.genMockFromModule', () => { }); ``` +This is how `genMockFromModule` will mock the follwing data types: + +#### `Function` + +A new function 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 will be mocked. + +#### `Object` + +Objects are deeply cloned. Their interfaces 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 stirng is mocked. + +#### `Number` + +A new copy of the original number is mocked. + +Example: + + +```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 { + 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. + expect(example.class.constructor.name).toEqual('Bar'); + expect(example.class.foo.name).toEqual('foo'); + // 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: diff --git a/packages/jest-mock/src/__tests__/index.test.ts b/packages/jest-mock/src/__tests__/index.test.ts index bd0d57f50746..64c47464be83 100644 --- a/packages/jest-mock/src/__tests__/index.test.ts +++ b/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', () => { From 91b9427ef6e34ce5a10d8044c00964e114d7b621 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Mon, 11 Mar 2019 08:09:49 -0700 Subject: [PATCH 02/13] add mock function language and link to the mock function docs --- docs/JestObjectAPI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index d8f5a0f8d03a..cc6a4647654b 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -123,7 +123,7 @@ This is how `genMockFromModule` will mock the follwing data types: #### `Function` -A new function will be created. The new function will have no formal parameters and when called will return `undefined`. This functionality also applies to `async functions`. +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` From 708cf2cfde926c46aaf12e65310ddc2acf1f1093 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Mon, 11 Mar 2019 08:11:00 -0700 Subject: [PATCH 03/13] fix string typo --- docs/JestObjectAPI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index cc6a4647654b..de62a505bef6 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -139,7 +139,7 @@ The original array is ignored and a new empty array is created. #### `String` -A new copy of the original stirng is mocked. +A new copy of the original string is mocked. #### `Number` From 1acd8766fc9db721dc8e2bfd2ee87353fb8ef0a9 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Mon, 11 Mar 2019 08:11:55 -0700 Subject: [PATCH 04/13] adjust language for string description --- docs/JestObjectAPI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index de62a505bef6..45ea0bffb618 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -131,7 +131,7 @@ A new class will be created. The interface of the original class is maintained h #### `Object` -Objects are deeply cloned. Their interfaces are maintained and their values are mocked. +Objects are deeply cloned. Their keys are maintained and their values are mocked. #### `Array` From 3ce58b715f57b2a53eadabf2f9aae4e1dd1142e7 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Mon, 11 Mar 2019 08:20:43 -0700 Subject: [PATCH 05/13] line spacing and array property example --- docs/JestObjectAPI.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index 45ea0bffb618..088b5cb662d6 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -127,7 +127,7 @@ A new [mock function](https://jestjs.io/docs/en/mock-functions.html) will be cre #### `Class` -A new class will be created. The interface of the original class is maintained however all of the class member functions will be mocked. +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` @@ -159,6 +159,9 @@ module.exports = { return result; }, class: new class Bar { + constructor() { + this.array = [1, 2, 3]; + } foo() {} }, object: { @@ -182,12 +185,16 @@ 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. + + // 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', @@ -196,10 +203,13 @@ test('should run example code', () => { 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'); }); From 3b92d72e238947af66c1c7194238b285cf43f1ba Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Mon, 11 Mar 2019 08:31:29 -0700 Subject: [PATCH 06/13] update versioned docs and changelog --- CHANGELOG.md | 1 + .../version-22.x/JestObjectAPI.md | 96 +++++++++++++++++++ .../version-23.x/JestObjectAPI.md | 96 +++++++++++++++++++ .../version-24.0/JestObjectAPI.md | 96 +++++++++++++++++++ 4 files changed, 289 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c66deca4bee1..4c9a3883e14c 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/website/versioned_docs/version-22.x/JestObjectAPI.md b/website/versioned_docs/version-22.x/JestObjectAPI.md index 4fda2af835ba..4625d18154c2 100644 --- a/website/versioned_docs/version-22.x/JestObjectAPI.md +++ b/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: + + +```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: diff --git a/website/versioned_docs/version-23.x/JestObjectAPI.md b/website/versioned_docs/version-23.x/JestObjectAPI.md index e14aaaa58717..e09a2a758149 100644 --- a/website/versioned_docs/version-23.x/JestObjectAPI.md +++ b/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: + + +```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: diff --git a/website/versioned_docs/version-24.0/JestObjectAPI.md b/website/versioned_docs/version-24.0/JestObjectAPI.md index 3ab253e66d6a..5820a21b53e2 100644 --- a/website/versioned_docs/version-24.0/JestObjectAPI.md +++ b/website/versioned_docs/version-24.0/JestObjectAPI.md @@ -120,6 +120,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: + + +```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: From 48855e704598a45b193991db3da4ee4be26079f0 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Mon, 11 Mar 2019 13:38:36 -0700 Subject: [PATCH 07/13] fix following typo --- docs/JestObjectAPI.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index 088b5cb662d6..e6f4d71b377d 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -119,7 +119,7 @@ test('implementation created by jest.genMockFromModule', () => { }); ``` -This is how `genMockFromModule` will mock the follwing data types: +This is how `genMockFromModule` will mock the following data types: #### `Function` From 062b28c40988f255394156ad1a65f479affd6519 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Mon, 11 Mar 2019 19:09:50 -0700 Subject: [PATCH 08/13] update language to consistently use present tense / update versioned docs --- docs/JestObjectAPI.md | 45 +++++++++--------- .../version-22.x/JestObjectAPI.md | 47 +++++++++---------- .../version-23.x/JestObjectAPI.md | 47 +++++++++---------- .../version-24.0/JestObjectAPI.md | 47 +++++++++---------- 4 files changed, 87 insertions(+), 99 deletions(-) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index e6f4d71b377d..28ecddc20a4a 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -123,39 +123,34 @@ This is how `genMockFromModule` will mock the following 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`. +Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has 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. +Creates new class. The interface of the original class is maintained, 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. +Creates a new deeply cloned object. The object keys are maintained and their values are mocked. #### `Array` -The original array is ignored and a new empty array is created. +Creates a new empty array, ignoring the original. -#### `String` +#### `Primitives` -A new copy of the original string is mocked. - -#### `Number` - -A new copy of the original number is mocked. +Creates a new copy of the original primitive. Example: - -```js +``` // example.js module.exports = { - function: function foo(a, b) { - return a + b; + function: function square(a, b) { + return a * b; }, - asyncFunction: async function asyncFoo(a, b) { - const result = await a + b; + asyncFunction: async function asyncSquare(a, b) { + const result = await a * b; return result; }, class: new class Bar { @@ -174,6 +169,8 @@ module.exports = { array: [1, 2, 3], number: 123, string: 'baz', + boolean: true, + symbol: Symbol.for('a.b.c'), }; ``` @@ -182,20 +179,20 @@ module.exports = { const example = jest.genMockFromModule('./example'); test('should run example code', () => { - // a new mocked function with no formal arguments. + // creates 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. + // async functions get the same treatment as 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. + // creates a new class with the same interface, member functions and properties are mocked. 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. + // creates a deeply cloned version of the original object. expect(example.object).toEqual({ baz: 'foo', bar: { @@ -204,14 +201,14 @@ test('should run example code', () => { }, }); - // the original array is ignored and a new emtpy array is mocked. + // creates a new empty array, ignoring the original array. expect(example.array.length).toEqual(0); - // a new copy of the original number. + // creates a new copy of the original primitive. expect(example.number).toEqual(123); - - // a new copy of the original string. expect(example.string).toEqual('baz'); + expect(example.boolean).toEqual(true); + expect(example.symbol).toEqual(Symbol.for('a.b.c')); }); ``` diff --git a/website/versioned_docs/version-22.x/JestObjectAPI.md b/website/versioned_docs/version-22.x/JestObjectAPI.md index 4625d18154c2..eb4b793037d6 100644 --- a/website/versioned_docs/version-22.x/JestObjectAPI.md +++ b/website/versioned_docs/version-22.x/JestObjectAPI.md @@ -173,43 +173,38 @@ test('implementation created by jest.genMockFromModule', () => { }); ``` -This is how `genMockFromModule` will mock the follwing data types: +This is how `genMockFromModule` will mock the following 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`. +Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has 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. +Creates new class. The interface of the original class is maintained, 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. +Creates a new deeply cloned object. The object keys are maintained and their values are mocked. #### `Array` -The original array is ignored and a new empty array is created. +Creates a new empty array, ignoring the original. -#### `String` +#### `Primitives` -A new copy of the original string is mocked. - -#### `Number` - -A new copy of the original number is mocked. +Creates a new copy of the original primitive. Example: - -```js +``` // example.js module.exports = { - function: function foo(a, b) { - return a + b; + function: function square(a, b) { + return a * b; }, - asyncFunction: async function asyncFoo(a, b) { - const result = await a + b; + asyncFunction: async function asyncSquare(a, b) { + const result = await a * b; return result; }, class: new class Bar { @@ -228,6 +223,8 @@ module.exports = { array: [1, 2, 3], number: 123, string: 'baz', + boolean: true, + symbol: Symbol.for('a.b.c'), }; ``` @@ -236,20 +233,20 @@ module.exports = { const example = jest.genMockFromModule('./example'); test('should run example code', () => { - // a new mocked function with no formal arguments. + // creates 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. + // async functions get the same treatment as 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. + // creates a new class with the same interface, member functions and properties are mocked. 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. + // creates a deeply cloned version of the original object. expect(example.object).toEqual({ baz: 'foo', bar: { @@ -258,14 +255,14 @@ test('should run example code', () => { }, }); - // the original array is ignored and a new emtpy array is mocked. + // creates a new empty array, ignoring the original array. expect(example.array.length).toEqual(0); - // a new copy of the original number. + // creates a new copy of the original primitive. expect(example.number).toEqual(123); - - // a new copy of the original string. expect(example.string).toEqual('baz'); + expect(example.boolean).toEqual(true); + expect(example.symbol).toEqual(Symbol.for('a.b.c')); }); ``` diff --git a/website/versioned_docs/version-23.x/JestObjectAPI.md b/website/versioned_docs/version-23.x/JestObjectAPI.md index e09a2a758149..b38ff4ba7ae5 100644 --- a/website/versioned_docs/version-23.x/JestObjectAPI.md +++ b/website/versioned_docs/version-23.x/JestObjectAPI.md @@ -174,43 +174,38 @@ test('implementation created by jest.genMockFromModule', () => { }); ``` -This is how `genMockFromModule` will mock the follwing data types: +This is how `genMockFromModule` will mock the following 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`. +Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has 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. +Creates new class. The interface of the original class is maintained, 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. +Creates a new deeply cloned object. The object keys are maintained and their values are mocked. #### `Array` -The original array is ignored and a new empty array is created. +Creates a new empty array, ignoring the original. -#### `String` +#### `Primitives` -A new copy of the original string is mocked. - -#### `Number` - -A new copy of the original number is mocked. +Creates a new copy of the original primitive. Example: - -```js +``` // example.js module.exports = { - function: function foo(a, b) { - return a + b; + function: function square(a, b) { + return a * b; }, - asyncFunction: async function asyncFoo(a, b) { - const result = await a + b; + asyncFunction: async function asyncSquare(a, b) { + const result = await a * b; return result; }, class: new class Bar { @@ -229,6 +224,8 @@ module.exports = { array: [1, 2, 3], number: 123, string: 'baz', + boolean: true, + symbol: Symbol.for('a.b.c'), }; ``` @@ -237,20 +234,20 @@ module.exports = { const example = jest.genMockFromModule('./example'); test('should run example code', () => { - // a new mocked function with no formal arguments. + // creates 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. + // async functions get the same treatment as 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. + // creates a new class with the same interface, member functions and properties are mocked. 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. + // creates a deeply cloned version of the original object. expect(example.object).toEqual({ baz: 'foo', bar: { @@ -259,14 +256,14 @@ test('should run example code', () => { }, }); - // the original array is ignored and a new emtpy array is mocked. + // creates a new empty array, ignoring the original array. expect(example.array.length).toEqual(0); - // a new copy of the original number. + // creates a new copy of the original primitive. expect(example.number).toEqual(123); - - // a new copy of the original string. expect(example.string).toEqual('baz'); + expect(example.boolean).toEqual(true); + expect(example.symbol).toEqual(Symbol.for('a.b.c')); }); ``` diff --git a/website/versioned_docs/version-24.0/JestObjectAPI.md b/website/versioned_docs/version-24.0/JestObjectAPI.md index 5820a21b53e2..d3d2f9673249 100644 --- a/website/versioned_docs/version-24.0/JestObjectAPI.md +++ b/website/versioned_docs/version-24.0/JestObjectAPI.md @@ -120,43 +120,38 @@ test('implementation created by jest.genMockFromModule', () => { }); ``` -This is how `genMockFromModule` will mock the follwing data types: +This is how `genMockFromModule` will mock the following 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`. +Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has 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. +Creates new class. The interface of the original class is maintained, 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. +Creates a new deeply cloned object. The object keys are maintained and their values are mocked. #### `Array` -The original array is ignored and a new empty array is created. +Creates a new empty array, ignoring the original. -#### `String` +#### `Primitives` -A new copy of the original string is mocked. - -#### `Number` - -A new copy of the original number is mocked. +Creates a new copy of the original primitive. Example: - -```js +``` // example.js module.exports = { - function: function foo(a, b) { - return a + b; + function: function square(a, b) { + return a * b; }, - asyncFunction: async function asyncFoo(a, b) { - const result = await a + b; + asyncFunction: async function asyncSquare(a, b) { + const result = await a * b; return result; }, class: new class Bar { @@ -175,6 +170,8 @@ module.exports = { array: [1, 2, 3], number: 123, string: 'baz', + boolean: true, + symbol: Symbol.for('a.b.c'), }; ``` @@ -183,20 +180,20 @@ module.exports = { const example = jest.genMockFromModule('./example'); test('should run example code', () => { - // a new mocked function with no formal arguments. + // creates 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. + // async functions get the same treatment as 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. + // creates a new class with the same interface, member functions and properties are mocked. 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. + // creates a deeply cloned version of the original object. expect(example.object).toEqual({ baz: 'foo', bar: { @@ -205,14 +202,14 @@ test('should run example code', () => { }, }); - // the original array is ignored and a new emtpy array is mocked. + // creates a new empty array, ignoring the original array. expect(example.array.length).toEqual(0); - // a new copy of the original number. + // creates a new copy of the original primitive. expect(example.number).toEqual(123); - - // a new copy of the original string. expect(example.string).toEqual('baz'); + expect(example.boolean).toEqual(true); + expect(example.symbol).toEqual(Symbol.for('a.b.c')); }); ``` From 1e8085680b44fe4a4614b3ad6e70070328872dd4 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Mon, 11 Mar 2019 19:30:33 -0700 Subject: [PATCH 09/13] update function names in test to match example code --- docs/JestObjectAPI.md | 4 ++-- website/versioned_docs/version-22.x/JestObjectAPI.md | 4 ++-- website/versioned_docs/version-23.x/JestObjectAPI.md | 4 ++-- website/versioned_docs/version-24.0/JestObjectAPI.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index 28ecddc20a4a..cc9511a1800a 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -180,11 +180,11 @@ const example = jest.genMockFromModule('./example'); test('should run example code', () => { // creates a new mocked function with no formal arguments. - expect(example.function.name).toEqual('foo'); + expect(example.function.name).toEqual('square'); expect(example.function.length).toEqual(0); // async functions get the same treatment as standard synchronous functions. - expect(example.asyncFunction.name).toEqual('asyncFoo'); + expect(example.asyncFunction.name).toEqual('asyncSquare'); expect(example.asyncFunction.length).toEqual(0); // creates a new class with the same interface, member functions and properties are mocked. diff --git a/website/versioned_docs/version-22.x/JestObjectAPI.md b/website/versioned_docs/version-22.x/JestObjectAPI.md index eb4b793037d6..b0a289a1ca8d 100644 --- a/website/versioned_docs/version-22.x/JestObjectAPI.md +++ b/website/versioned_docs/version-22.x/JestObjectAPI.md @@ -234,11 +234,11 @@ const example = jest.genMockFromModule('./example'); test('should run example code', () => { // creates a new mocked function with no formal arguments. - expect(example.function.name).toEqual('foo'); + expect(example.function.name).toEqual('square'); expect(example.function.length).toEqual(0); // async functions get the same treatment as standard synchronous functions. - expect(example.asyncFunction.name).toEqual('asyncFoo'); + expect(example.asyncFunction.name).toEqual('asyncSquare'); expect(example.asyncFunction.length).toEqual(0); // creates a new class with the same interface, member functions and properties are mocked. diff --git a/website/versioned_docs/version-23.x/JestObjectAPI.md b/website/versioned_docs/version-23.x/JestObjectAPI.md index b38ff4ba7ae5..de421e94cf90 100644 --- a/website/versioned_docs/version-23.x/JestObjectAPI.md +++ b/website/versioned_docs/version-23.x/JestObjectAPI.md @@ -235,11 +235,11 @@ const example = jest.genMockFromModule('./example'); test('should run example code', () => { // creates a new mocked function with no formal arguments. - expect(example.function.name).toEqual('foo'); + expect(example.function.name).toEqual('square'); expect(example.function.length).toEqual(0); // async functions get the same treatment as standard synchronous functions. - expect(example.asyncFunction.name).toEqual('asyncFoo'); + expect(example.asyncFunction.name).toEqual('asyncSquare'); expect(example.asyncFunction.length).toEqual(0); // creates a new class with the same interface, member functions and properties are mocked. diff --git a/website/versioned_docs/version-24.0/JestObjectAPI.md b/website/versioned_docs/version-24.0/JestObjectAPI.md index d3d2f9673249..71e0068523bf 100644 --- a/website/versioned_docs/version-24.0/JestObjectAPI.md +++ b/website/versioned_docs/version-24.0/JestObjectAPI.md @@ -181,11 +181,11 @@ const example = jest.genMockFromModule('./example'); test('should run example code', () => { // creates a new mocked function with no formal arguments. - expect(example.function.name).toEqual('foo'); + expect(example.function.name).toEqual('square'); expect(example.function.length).toEqual(0); // async functions get the same treatment as standard synchronous functions. - expect(example.asyncFunction.name).toEqual('asyncFoo'); + expect(example.asyncFunction.name).toEqual('asyncSquare'); expect(example.asyncFunction.length).toEqual(0); // creates a new class with the same interface, member functions and properties are mocked. From b24fb10d964a55427da03e98777a9de4ac9ddef5 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Tue, 12 Mar 2019 07:42:07 -0700 Subject: [PATCH 10/13] update wording of primitive description --- docs/JestObjectAPI.md | 4 ++-- website/versioned_docs/version-22.x/JestObjectAPI.md | 4 ++-- website/versioned_docs/version-23.x/JestObjectAPI.md | 4 ++-- website/versioned_docs/version-24.0/JestObjectAPI.md | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index cc9511a1800a..2f67b985cfd1 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -123,7 +123,7 @@ This is how `genMockFromModule` will mock the following data types: #### `Function` -Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has no formal parameters and when called will return `undefined`. This functionality also applies to `async functions`. +Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has no formal parameters and when called will return `undefined`. This functionality also applies to `async` functions. #### `Class` @@ -139,7 +139,7 @@ Creates a new empty array, ignoring the original. #### `Primitives` -Creates a new copy of the original primitive. +Creates a new property with the same primitive value as the original property. Example: diff --git a/website/versioned_docs/version-22.x/JestObjectAPI.md b/website/versioned_docs/version-22.x/JestObjectAPI.md index b0a289a1ca8d..2c34de101af1 100644 --- a/website/versioned_docs/version-22.x/JestObjectAPI.md +++ b/website/versioned_docs/version-22.x/JestObjectAPI.md @@ -177,7 +177,7 @@ This is how `genMockFromModule` will mock the following data types: #### `Function` -Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has no formal parameters and when called will return `undefined`. This functionality also applies to `async functions`. +Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has no formal parameters and when called will return `undefined`. This functionality also applies to `async` functions. #### `Class` @@ -193,7 +193,7 @@ Creates a new empty array, ignoring the original. #### `Primitives` -Creates a new copy of the original primitive. +Creates a new property with the same primitive value as the original property. Example: diff --git a/website/versioned_docs/version-23.x/JestObjectAPI.md b/website/versioned_docs/version-23.x/JestObjectAPI.md index de421e94cf90..d06d7f023430 100644 --- a/website/versioned_docs/version-23.x/JestObjectAPI.md +++ b/website/versioned_docs/version-23.x/JestObjectAPI.md @@ -178,7 +178,7 @@ This is how `genMockFromModule` will mock the following data types: #### `Function` -Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has no formal parameters and when called will return `undefined`. This functionality also applies to `async functions`. +Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has no formal parameters and when called will return `undefined`. This functionality also applies to `async` functions. #### `Class` @@ -194,7 +194,7 @@ Creates a new empty array, ignoring the original. #### `Primitives` -Creates a new copy of the original primitive. +Creates a new property with the same primitive value as the original property. Example: diff --git a/website/versioned_docs/version-24.0/JestObjectAPI.md b/website/versioned_docs/version-24.0/JestObjectAPI.md index 71e0068523bf..389afb3f6f25 100644 --- a/website/versioned_docs/version-24.0/JestObjectAPI.md +++ b/website/versioned_docs/version-24.0/JestObjectAPI.md @@ -124,7 +124,7 @@ This is how `genMockFromModule` will mock the following data types: #### `Function` -Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has no formal parameters and when called will return `undefined`. This functionality also applies to `async functions`. +Creates a new [mock function](https://jestjs.io/docs/en/mock-functions.html). The new function has no formal parameters and when called will return `undefined`. This functionality also applies to `async` functions. #### `Class` @@ -140,7 +140,7 @@ Creates a new empty array, ignoring the original. #### `Primitives` -Creates a new copy of the original primitive. +Creates a new property with the same primitive value as the original property. Example: From 9df0f20185c4dfcbd842730a545f6e5bfd4e4d99 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Fri, 15 Mar 2019 14:20:51 -0700 Subject: [PATCH 11/13] update wording of primitive description in code comment --- docs/JestObjectAPI.md | 2 +- website/versioned_docs/version-22.x/JestObjectAPI.md | 2 +- website/versioned_docs/version-23.x/JestObjectAPI.md | 2 +- website/versioned_docs/version-24.0/JestObjectAPI.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/JestObjectAPI.md b/docs/JestObjectAPI.md index 2f67b985cfd1..1a6cb5afe945 100644 --- a/docs/JestObjectAPI.md +++ b/docs/JestObjectAPI.md @@ -204,7 +204,7 @@ test('should run example code', () => { // creates a new empty array, ignoring the original array. expect(example.array.length).toEqual(0); - // creates a new copy of the original primitive. + // creates a new property with the same primitive value as the original property. expect(example.number).toEqual(123); expect(example.string).toEqual('baz'); expect(example.boolean).toEqual(true); diff --git a/website/versioned_docs/version-22.x/JestObjectAPI.md b/website/versioned_docs/version-22.x/JestObjectAPI.md index 2c34de101af1..9d57aab4562d 100644 --- a/website/versioned_docs/version-22.x/JestObjectAPI.md +++ b/website/versioned_docs/version-22.x/JestObjectAPI.md @@ -258,7 +258,7 @@ test('should run example code', () => { // creates a new empty array, ignoring the original array. expect(example.array.length).toEqual(0); - // creates a new copy of the original primitive. + // creates a new property with the same primitive value as the original property. expect(example.number).toEqual(123); expect(example.string).toEqual('baz'); expect(example.boolean).toEqual(true); diff --git a/website/versioned_docs/version-23.x/JestObjectAPI.md b/website/versioned_docs/version-23.x/JestObjectAPI.md index d06d7f023430..a32bac460849 100644 --- a/website/versioned_docs/version-23.x/JestObjectAPI.md +++ b/website/versioned_docs/version-23.x/JestObjectAPI.md @@ -259,7 +259,7 @@ test('should run example code', () => { // creates a new empty array, ignoring the original array. expect(example.array.length).toEqual(0); - // creates a new copy of the original primitive. + // creates a new property with the same primitive value as the original property. expect(example.number).toEqual(123); expect(example.string).toEqual('baz'); expect(example.boolean).toEqual(true); diff --git a/website/versioned_docs/version-24.0/JestObjectAPI.md b/website/versioned_docs/version-24.0/JestObjectAPI.md index 389afb3f6f25..ca754af8600e 100644 --- a/website/versioned_docs/version-24.0/JestObjectAPI.md +++ b/website/versioned_docs/version-24.0/JestObjectAPI.md @@ -205,7 +205,7 @@ test('should run example code', () => { // creates a new empty array, ignoring the original array. expect(example.array.length).toEqual(0); - // creates a new copy of the original primitive. + // creates a new property with the same primitive value as the original property. expect(example.number).toEqual(123); expect(example.string).toEqual('baz'); expect(example.boolean).toEqual(true); From df8c6b8dd9f3d23f0f8578da16b1aa30f60f23ce Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Sun, 17 Mar 2019 16:56:23 -0700 Subject: [PATCH 12/13] move auto-mocking changelog line under master heading --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8a246357545e..f4515b0a8c30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ### Features +- `[*]` Add documentation and tests related to auto-mocking ([#8086](https://github.com/facebook/jest/pull/8099)) + ### Fixes - `[pretty-format]` Print `BigInt` as a readable number instead of `{}` [#8138](https://github.com/facebook/jest/pull/8138) @@ -40,7 +42,6 @@ ### 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)) ## 24.3.1 From b3c807f8e25ed5c47cf97a02e35b5862f51f38f2 Mon Sep 17 00:00:00 2001 From: Mack Solomon Date: Sun, 17 Mar 2019 16:58:18 -0700 Subject: [PATCH 13/13] move auto-mocking changelog line under master heading --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f4515b0a8c30..d1718e470eb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,9 @@ ## master -### Features - - `[*]` Add documentation and tests related to auto-mocking ([#8086](https://github.com/facebook/jest/pull/8099)) +### Features + ### Fixes - `[pretty-format]` Print `BigInt` as a readable number instead of `{}` [#8138](https://github.com/facebook/jest/pull/8138)