Starting point

enzymejs · Sep 26, 2017 · e283e6d · e283e6d
1 parent d024934
commit e283e6d
Show file tree

Hide file tree

Showing 19 changed files with 237 additions and 393 deletions.
diff --git a/README.md b/README.md
@@ -7,13 +7,63 @@ Enzyme
 [![Discord Channel](https://img.shields.io/badge/discord-testing@reactiflux-738bd7.svg?style=flat-square)](https://discord.gg/0ZcbPKXt5bY8vNTA)
 
 
-
 Enzyme is a JavaScript Testing utility for React that makes it easier to assert, manipulate,
 and traverse your React Components' output.
 
 Enzyme's API is meant to be intuitive and flexible by mimicking jQuery's API for DOM manipulation
 and traversal.
 
+Upgrading from Enzyme 2.x or React < 16
+===========
+
+Are you here to check whether or not Enzyme is compatible with React 16? Are you currently using
+Enzyme 2.x? Great! Check out our [migration guide](/docs/guides/migration-from-2-to-3.md) for help
+moving on to Enzyme v3 where React 16 is supported.
+
+### [Installation](/docs/installation/README.md)
+
+To get started with enzyme, you can simply install it via npm. You will need to install enzyme
+along with an Adapter corresponding to the version of react (or other UI Component library) you
+are using. For instance, if you are using enzyme with React 16, you can run:
+
+```bash
+npm i --save-dev enzyme enzyme-adapter-react-16
+```
+
+Each adapter may have additional peer dependencies which you will need to install as well. For instance,
+`enzyme-adapter-react-16` has peer dependencies on `react`, `react-dom`, and `react-test-renderer`.
+
+At the moment, Enzyme has adapters that provide compatibility with `React 16.x`, `React 15.x`,
+`React 0.14.x` and `React 0.13.x`.
+
+The following adapters are officially provided by enzyme, and have the following compatibility with
+React:
+
+| Enzyme Adapter Package | React semver compatibility |
+| --- | --- |
+| `enzyme-adapter-react-16` | `^16.0.0` |
+| `enzyme-adapter-react-15` | `^15.5.0` |
+| `enzyme-adapter-react-15.4` | `15.0.0-0 - 15.4.x` |
+| `enzyme-adapter-react-14` | `^0.14.0` |
+| `enzyme-adapter-react-13` | `^0.13.0` |
+
+It is possible for the community to create additional (non-official) adapters that will make enzyme
+work with other libraries. If you have made one, feel free to make a PR to this README and add a
+link to it!
+
+Finally, you need to configure enzyme to use the adapter you want it to use. To do this, you can use
+the top level `configure(...)` API.
+
+```js
+import Enzyme from 'enzyme';
+import Adapter from 'enzyme-adapter-react-16';
+
+Enzyme.configure({ adapter: new Adapter() });
+```
+
+Running Enzyme Tests
+===========
+
 Enzyme is unopinionated regarding which test runner or assertion library you use, and should be
 compatible with all major test runners and assertion libraries out there. The documentation and
 examples for enzyme use [mocha](https://mochajs.org/) and [chai](http://chaijs.com/), but you
@@ -49,32 +99,6 @@ testing your React components, you can consider using:
 
 [Using Enzyme with Tape and AVA](/docs/guides/tape-ava.md)
 
-### [Installation](/docs/installation/README.md)
-
-To get started with enzyme, you can simply install it with npm:
-
-```bash
-npm i --save-dev enzyme
-```
-
-Enzyme is currently compatible with `React 15.x`, `React 0.14.x` and `React 0.13.x`. In order to
-achieve this compatibility, some dependencies cannot be explicitly listed in our `package.json`.
-
-If you are using `React 0.14` or `React <15.5`, in addition to `enzyme`, you will have to ensure that
-you also have the following npm modules installed if they were not already:
-
-```bash
-npm i --save-dev react-addons-test-utils react-dom
-```
-
-If you are using `React >=15.5`, in addition to `enzyme`, you will have to ensure that you also have
-the following npm modules installed if they were not already:
-
-```bash
-npm i --save-dev react-test-renderer react-dom
-```
-
-
 Basic Usage
 ===========
 

diff --git a/SUMMARY.md b/SUMMARY.md
@@ -2,6 +2,7 @@
 
 * [Introduction](/README.md)
 * [Guides](/docs/guides.md)
+  * [Migration from 2.x to 3.x](/docs/guides/migration-from-2-to-3.md)
   * [Browserify](/docs/guides/browserify.md)
   * [WebPack](/docs/guides/webpack.md)
   * [JSDOM](/docs/guides/jsdom.md)
@@ -12,9 +13,10 @@
   * [Lab](/docs/guides/lab.md)
   * [Tape and AVA](/docs/guides/tape-ava.md)
 * [Installation](/docs/installation/README.md)
-  * [Working with React 0.13.x](/docs/installation/react-013.md)
-  * [Working with React 0.14.x](/docs/installation/react-014.md)
+  * [Working with React 16.x](/docs/installation/react-16.md)
   * [Working with React 15.x](/docs/installation/react-15.md)
+  * [Working with React 0.14.x](/docs/installation/react-014.md)
+  * [Working with React 0.13.x](/docs/installation/react-013.md)
 * [API Reference](/docs/api/README.md)
   * [Shallow Rendering](/docs/api/shallow.md)
     * [at(index)](/docs/api/ShallowWrapper/at.md)
@@ -130,5 +132,4 @@
   * [Selectors](/docs/api/selector.md)
 * [Change Log](/CHANGELOG.md)
 * [Future](/docs/future.md)
-  * [Adapter & Compatibility Proposal](/docs/future/compatibility.md)
 * [Contributing Guide](/CONTRIBUTING.md)
diff --git a/docs/common-issues.md b/docs/common-issues.md
@@ -2,44 +2,6 @@
 
 This list aims to be comprehensive. If you find an issue that has been frequently brought up in Github *issues* that is not here, please open a PR to add it.
 
-### Webpack Build Issues
-
-- [Related Github issue](https://github.com/airbnb/enzyme/issues/684)
-
-###### Common Solutions
-
-_Mismatched versions of React and React* libraries._
-
-It is important to ensure all React and React* libraries your project depend on are matching versions.
-If you are using React 15.4.0, you should ensure your React* libraries (like react-test-utils) are equivalently on 15.4.0.
-
-_Bad configuration._
-
-Please see the guide for [webpack](/docs/guides/webpack) to ensure your configuration is correct for weback.
-
-### Error: Cannot find module 'react-dom/lib/ReactTestUtils'
-
-- [Related Github issue](https://github.com/airbnb/enzyme/issues/684)
-- [Related code](https://github.com/airbnb/enzyme/blob/3aeb02461eabf2fd402613991915d8d6f4b88536/src/react-compat.js#L97-L105)
-
-###### Reason
-
-In order to properly support multiple versions of React, we have conditional requirements that npm does not support with tools like
-`peerDependencies`. Instead we manually require and throw errors if the dependency is not met.
-
-###### Solution
-
-Install a matching version of React for `react-test-utils`. Example package.json
-
-```json
-{
-  "devDependencies": {
-    "react": "15.4.0",
-    "react-test-utils": "15.4.0"
-  }
-}
-```
-
 ### Query Selector fails
 
 ###### Reason

diff --git a/docs/future.md b/docs/future.md
@@ -7,18 +7,6 @@ There are several things we'd like to address with Enzyme that often get asked.
 of projects that we plan on addressing in the near future:
 
 
-### Enzyme Adapter & Compatibility
-
-[See the full proposal](future/compatibility.md)
-
-
-#### Improved CSS Selector Support
-
-Currently, "hierarchical" CSS selectors are not supported in Enzyme. That means that the only CSS
-selectors that can be used right now are those that operate on a specific node.  As time progresses
-we would like to provide a more complete subset of all valid CSS selectors.
-
-
 #### Improved event simulation and propagation support
 
 Event simulation is limited for Shallow rendering. Event propagation is not supported, and one must

diff --git a/docs/guides/browserify.md b/docs/guides/browserify.md
@@ -1,52 +1,9 @@
 # Using Enzyme with Browserify
 
 If you are using a test runner that runs code in a browser-based environment, you may be using
-[browserify]() in order to bundle your React code.
+[browserify](http://browserify.org/) in order to bundle your React code.
 
-Browserify uses static analysis to create a dependency graph at build-time of your source code to
-build a bundle. Enzyme has a hand full of conditional `require()` calls in it in order to remain
-compatible with React 0.13 and React 0.14.
-
-Unfortunately, these conditional requires mean there is a bit of extra setup with bundlers like
-browserify.
-
-In your browserify configuration, you simply need to make sure that the following files are
-labeled as "external", which means they will be ignored:
-
-```
-react/addons
-react/lib/ReactContext
-react/lib/ExecutionEnvironment
-```
-
-Here is an example piece of configuration code marking these as external:
-
-```js
-const browserify = require('browserify');
-
-const b = browserify();
-
-// make sure to mark these as external!
-b.external('react/addons');
-b.external('react/lib/ReactContext');
-b.external('react/lib/ExecutionEnvironment');
-
-// the rest of your browserify configuration
-```
-
-
-## React 0.14 Compatibility
-
-If you are using React 0.14, the instructions above will be the same but with a different list of
-externals:
-
-```
-react-dom
-react-dom/server
-react-addons-test-utils
-```
-
-
-## Example Projects
-
-- [enzyme-example-karma](https://github.com/lelandrichardson/enzyme-example-karma)
+Prior to Enzyme 3.0 there were some issues with conditional requires that were used
+to maintain backwards compatibility with React versions. With Enzyme 3.0+, this
+should no longer be an issue. If it is, please file a GitHub issue or make a PR
+to this documentation with instructions on how to set it up.
diff --git a/docs/guides/jest.md b/docs/guides/jest.md
@@ -36,7 +36,3 @@ If you are using Jest 0.9 – 14.0 with Enzyme and using Jest's automocking feat
 ```
 
 If you are using a previous version of Jest together with npm3, you may need to unmock [more modules](https://github.com/airbnb/enzyme/blob/78febd90fe2fb184771b8b0356b0fcffbdad386e/docs/guides/jest.md).
-
-## Example Project for Jest prior to version 15
-
-- [enzyme-example-jest](https://github.com/lelandrichardson/enzyme-example-jest)
diff --git a/docs/guides/jsdom.md b/docs/guides/jsdom.md
@@ -115,9 +115,3 @@ nvm use 0.12
 ```bash
 nvm use 4
 ```
-
-
-
-## Example Projects
-
-- [enzyme-example-mocha](https://github.com/lelandrichardson/enzyme-example-mocha)
diff --git a/docs/guides/karma.md b/docs/guides/karma.md
@@ -28,13 +28,6 @@ module.exports = function karmaConfig(config) {
           },
         }],
       },
-      externals: {
-        cheerio: 'window',
-        'react/addons': true,
-        'react/lib/ExecutionEnvironment': true,
-        'react/lib/ReactContext': true,
-        'react-addons-test-utils': 'react-dom',
-      },
     },
     // ...
   });
@@ -55,21 +48,8 @@ module.exports = function karmaConfig(config) {
       transform: [
         ['babelify', { presets: ['airbnb'] }],
       ],
-      configure(bundle) {
-        bundle.on('prebundle', () => {
-          bundle.external('react/addons');
-          bundle.external('react/lib/ReactContext');
-          bundle.external('react/lib/ExecutionEnvironment');
-        });
-      },
     },
     // ...
   });
 };
 ```
-
-
-## Example Projects
-
-- [enzyme-example-karma](https://github.com/lelandrichardson/enzyme-example-karma)
-- [enzyme-example-karma-webpack](https://github.com/lelandrichardson/enzyme-example-karma-webpack)