Automatic mocks/ automocking is not described in the docs

[jonathan-stone]

Do you want to request a feature or report a bug?
Docs bug.
I'm writing this with the intention of creating a PR to resolve this issue.

What is the current behavior?
The docs refer to automatic mocks repeatedly, but do not describe what automatic mocks are. They seem to assume the reader knows what automatic mocks are and how to use them, and merely describe how to create/enable/disable automatic mocks.

jest.genMockFromModule
The docs say:

Given the name of a module, use the automatic mocking system to generate a mocked version of the module for you.

This is useful when you want to create a manual mock that extends the automatic mock's behavior.

jest.disableAutomock / jest.enableAutomock

The docs say:

Enables automatic mocking in the module loader.

This does not describe what automatic mocking is, just that it happens.

automock configuration option

The docs say:

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).

Note: Core modules, like fs, are not mocked by default. They can be mocked explicitly, like jest.mock('fs').

The docs do not say what automatic mocking is or does when it's enabled. So it's hard to know whether you want to use it or not.

If the current behavior is a bug, please provide the steps to reproduce and
either a repl.it demo through https://repl.it/languages/jest or a minimal
repository on GitHub that we can yarn install and yarn test.

What is the expected behavior?
The docs describe what genMockFromModule does, exactly. Something like: "Returns a mock with the same shape as the specified module. " Note, I'm not sure what exactly to write here as it is not documented anywhere.

The docs describe what exactly happens when you enable automocking: they describe where exactly it happens, and what the result is. Something like: "Replaces calls to require() and import() with calls to an internal Jest function, which returns an object whose shape matches the exports of the automocked module. Any mocked functions or methods are replaced with mock functions (jest.fn()) which always return undefined."

Please provide your exact Jest configuration and mention your Jest, node,
yarn/npm version and operating system.
Jest docs in master branch as of 1/10/2018.

[hkmarques]

Yes, please! I'm also trying to figure out what exactly jest.genMockFromModule does as in my first attempt things didn't go as planned, but the docs for it simply point at this magical bird which can't really be found.

[vovkasm]

Partially this explained in packages/jest-mock/README.md. But yes, add this info to documentation site please!

[jonathan-stone]

Thanks @vovkasm, I hadn't seen that before. Very helpful! I'll use that in the docs update.

[github-actions]

This issue 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.