Add documentation related to auto-mocking by mackness · Pull Request #8099 · jestjs/jest

mackness · 2019-03-10T18:25:15Z

Summary

The purpose of this PR is to add more documentation related to how Jest auto-mocks modules. It aims to clarify how Jest mocks and transforms values with jest.genMockFromModule. Resolves #6812

Test plan

Add a few tests to verify the assertions made by the documentation in packages/jest-mock/src/__tests__/index.test.ts.

codecov-io · 2019-03-10T18:51:02Z

Codecov Report

Merging #8099 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #8099   +/-   ##
=======================================
  Coverage   62.44%   62.44%           
=======================================
  Files         264      264           
  Lines       10371    10371           
  Branches     2515     2515           
=======================================
  Hits         6476     6476           
  Misses       3318     3318           
  Partials      577      577

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 76782b8...b3c807f. Read the comment docs.

SimenB · 2019-03-10T22:43:13Z

+
+#### `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`.


should mocked async functions return Promise<undefined> instead?

I just tested this and it seems like mocked async functions don't return Promise<undefined> instead they return undefined just like synchronous functions.

yep, I meant that maybe we should change this. Good that the current behavior gets documented though!

SimenB · 2019-03-10T22:43:32Z

+
+Example:
+
+<!-- prettier-ignore -->


So for some reason prettier is adding these unwanted parens after the closing class bracket

If I remove js in the opening code block in the markdown file prettier does not insert the weird parenthesis. 🤔

Oh, it's just adding the parense. new class Bar{} and new class Bar{}() behaves the same.

Should it be newed?

I opened up prettier/prettier#5964, not sure if it's a bug or not

Nice, I added another comment that may or may not be related to the same issue. For now I just removed the js attribute from the markdown code block and everything is formatted correctly and syntax hi-lighting seems to be working in the site preview

SimenB

This is awesome! I especially like the added tests to assert behavior for the different types. Thanks for those.

I left some inline q's.

Can you also update the versioned docs and the changelog?

rickhanlonii

Thanks for doing this!

rickhanlonii · 2019-03-11T09:36:23Z

+
+#### `String`
+
+A new copy of the original stirng is mocked.


Suggested change

A new copy of the original stirng is mocked.

A new copy of the original string is mocked.

Thanks for catching this!

rickhanlonii · 2019-03-11T09:36:40Z

+
+#### `Object`
+
+Objects are deeply cloned. Their interfaces are maintained and their values are mocked.


Suggested change

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.

rickhanlonii · 2019-03-11T09:38:06Z

+
+#### `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.


What about class properties, if there's a property that is an array will it be mocked with the array strategy mentioned below?

Good point, I can add this case to the example code / description.

pedrottimark · 2019-03-11T20:39:11Z

+
+#### `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`.


Does it harm the meaning to write in present tense and active voice as much as possible? For example:

Create a new mock function which has no formal parameters and returns undefined.

I think you're right about using present tense. I also don't think present tense effects the meaning or makes it unclear. Since the rest of the docs are written in present tense I think I should update this section to match. I'll work on switching everything to present tense.

pedrottimark · 2019-03-11T20:42:48Z

+
+#### `String`
+
+A new copy of the original string is mocked.


This made me stop to think (which is not necessarily bad :)

By a new copy of primitive type like string or number, is the implicit assumption as value of a property?

If yes, then is it possible to summarize the behavior, which I think confirms what testers expect as one heading for all primitive types (with a few additional tests, if needed) including boolean, symbol, null, undefined?

I think it makes sense to summarize all primitives under one heading since the mocking functionality is the same. Instead of a string and number header I can create a primitives header and maybe add the following tests to the docs: https://github.com/facebook/jest/blob/445e6cb9f5fddf87174e510a602cf8bc11a840b1/packages/jest-mock/src/__tests__/index.test.ts#L33-L36

…docs

pedrottimark

Thank you for your contribution to fill this gap and willingness to follow through on review comments.

I will leave for Simen to confirm the changes that he requested.

SimenB

This is fantastic, thanks!

SimenB · 2019-03-17T09:54:39Z


 ### Chore & Maintenance

+- `[*]` Add documentation and tests related to auto-mocking ([#8086](https://github.com/facebook/jest/pull/8099))


Can you move this up under master?

(Might have to merge in master or rebase first)

Synced with upstream master and moved the changelog line under the master heading. Thanks for the feedback and help with this @SimenB !

SimenB · 2019-03-18T08:29:17Z

Thank you!

* upstream/master: (391 commits) more precise circus asyncError types (jestjs#8150) Add typeahead watch plugin (jestjs#6449) fix: getTimerCount not taking immediates and ticks into account (jestjs#8139) website: add an additional filter predicate to backers (jestjs#7286) [🔥] Revised README (jestjs#8076) [jest-each] Fix test function type (jestjs#8145) chore: improve bug template labels for easier maintenance (jestjs#8141) Add documentation related to auto-mocking (jestjs#8099) Add support for bigint to pretty-format (jestjs#8138) Revert "Add fuzzing based tests in Jest (jestjs#8012)" chore: remove console.log chore: Improve description of optional arguments in ExpectAPI.md (jestjs#8126) Add fuzzing based tests in Jest (jestjs#8012) Move @types/node to the root package.json (jestjs#8129) chore: use property initializer syntax (jestjs#8117) chore: delete flow types from the repo (jestjs#8061) Move changelog entry to the proper version (jestjs#8115) Release 24.5.0 Expose throwOnModuleCollision (jestjs#8113) add matchers to expect type (jestjs#8093) ...

github-actions · 2021-05-11T22:06:33Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.

add tests and documentation related to auto mocking

746ea44

facebook-github-bot added the cla signed label Mar 10, 2019

mackness mentioned this pull request Mar 10, 2019

Add more documentation on auto-mocking #6812

Closed

SimenB reviewed Mar 10, 2019

View reviewed changes

Comment thread docs/JestObjectAPI.md Outdated

SimenB reviewed Mar 10, 2019

View reviewed changes

SimenB requested changes Mar 10, 2019

View reviewed changes

SimenB requested review from pedrottimark, rickhanlonii and thymikee March 10, 2019 22:45

rickhanlonii reviewed Mar 11, 2019

View reviewed changes

Mack Solomon added 5 commits March 11, 2019 08:09

add mock function language and link to the mock function docs

91b9427

fix string typo

708cf2c

adjust language for string description

1acd876

line spacing and array property example

3ce58b7

update versioned docs and changelog

3b92d72

pedrottimark reviewed Mar 11, 2019

View reviewed changes

Comment thread docs/JestObjectAPI.md Outdated

fix following typo

48855e7

pedrottimark reviewed Mar 11, 2019

View reviewed changes

Mack Solomon added 2 commits March 11, 2019 19:09

update language to consistently use present tense / update versioned …

062b28c

…docs

update function names in test to match example code

1e80856

pedrottimark reviewed Mar 12, 2019

View reviewed changes

Comment thread docs/JestObjectAPI.md Outdated

pedrottimark reviewed Mar 12, 2019

View reviewed changes

Comment thread docs/JestObjectAPI.md Outdated

update wording of primitive description

b24fb10

pedrottimark approved these changes Mar 12, 2019

View reviewed changes

update wording of primitive description in code comment

9df0f20

SimenB approved these changes Mar 17, 2019

View reviewed changes

Merge branch 'master' into auto-mocking-documentation

e050750

Mack Solomon added 2 commits March 17, 2019 16:56

move auto-mocking changelog line under master heading

df8c6b8

move auto-mocking changelog line under master heading

b3c807f

SimenB merged commit 90c6002 into jestjs:master Mar 18, 2019

snyk-bot mentioned this pull request Dec 15, 2019

[Snyk] Upgrade babel-jest from 24.0.0 to 24.9.0 jakeherp/burger-builder#14

Open

snyk-bot mentioned this pull request Mar 21, 2020

[Snyk] Upgrade: jest, jest-cli lwojcik/sc2pte-panel-frontend#88

Closed

github-actions Bot locked as resolved and limited conversation to collaborators May 11, 2021


		#### `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 copy of the original stirng is mocked.
	A new copy of the original string is mocked.


		#### `Object`

		Objects are deeply cloned. Their interfaces are maintained and their values are mocked.

	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.


		#### `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.


		#### `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`.


		### Chore & Maintenance

		- `[*]` Add documentation and tests related to auto-mocking ([#8086](https://github.com/facebook/jest/pull/8099))


		Example:

		<!-- prettier-ignore -->

Uh oh!

Conversation

mackness commented Mar 10, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

codecov-io commented Mar 10, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mackness Mar 11, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mackness Mar 12, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SimenB left a comment

Choose a reason for hiding this comment

Uh oh!

rickhanlonii left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

pedrottimark left a comment

Choose a reason for hiding this comment

Uh oh!

SimenB left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SimenB commented Mar 18, 2019

Uh oh!

github-actions Bot commented May 11, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

mackness commented Mar 10, 2019 •

edited

Loading

codecov-io commented Mar 10, 2019 •

edited

Loading

mackness Mar 11, 2019 •

edited

Loading

mackness Mar 12, 2019 •

edited

Loading