Document caveat with mocks, Enzyme, snapshots and React 16

CHANGELOG.md

@@ -1,5 +1,10 @@
 ## master
 
+### Fixes
+
+* `[docs]` Document caveat with mocks, Enzyme, snapshots and React 16
+   ([#5258](https://github.com/facebook/jest/issues/5258))
+
 ## jest 22.0.5
 
 ### Fixes

CONTRIBUTING.md

@@ -95,7 +95,7 @@ accurately.
    ```sh
    cd website       # Only needed if you are not already in the website directory
    yarn
-   yarn test
+   yarn start
    ```
 2. You can run a development server to check if the changes you made are being
    displayed accurately by running `yarn start` in the website directory.

docs/TutorialReact.md

@@ -184,6 +184,43 @@ with `jest -u` to overwrite the existing snapshot.
 The code for this example is available at
 [examples/snapshot](https://github.com/facebook/jest/tree/master/examples/snapshot).
 
+#### Snapshot Testing with Mocks, Enzyme and React 16
+
+There's a caveat around snapshot testing when using Enzyme and React 16+.
+If you mock out a module using the following style:
+
+```js
+jest.mock('../SomeDirectory/SomeComponent', () => 'SomeComponent');
+```
+
+Then you will see warnings in the console:
+
+```
+Warning: <SomeComponent /> is using uppercase HTML. Always use lowercase HTML tags in React.
+
+# Or:
+Warning: The tag <SomeComponent> is unrecognized in this browser. If you meant to render a React component, start its name with an uppercase letter.
+```
+
+React 16 triggers these warnings due to how it checks element types, and
+the mocked module fails these checks. Your options are:
+
+   1. Render as text. This way you won't see the props passed to the mock
+      component in the snapshot, but it's straightforward:
+      ```js
+      jest.mock('./SomeComponent', () => () => 'SomeComponent');
+      ```
+   2. Render as a custom element. DOM "custom elements" aren't checked for
+      anything and shouldn't fire warnings. They are lowercase and have a
+      dash in the name.
+      ```js
+      jest.mock('./Widget', () => 'mock-widget');
+      ```
+   3. Use `react-test-renderer`. The test renderer doesn't care about
+      element types and will happily accept e.g. `SomeComponent`. You could
+      check snapshots using the test renderer, and check component
+      behaviour separately using Enzyme.
+
 ### DOM Testing
 
 If you'd like to assert, and manipulate your rendered components you can use

docs/TutorialReactNative.md

@@ -211,7 +211,8 @@ jest.mock('react-native-video', () => 'Video');
 ```
 
 This will render the component as `<Video {...props} />` with all of its props
-in the snapshot output.
+in the snapshot output. See also [caveats around Enzyme and React
+16](tutorial-react.html#snapshot-testing-with-mocks-enzyme-and-react-16).
 
 Sometimes you need to provide a more complex manual mock. For example if you'd
 like to forward the prop types or static fields of a native component to a mock,