From e283e6dcf0cf530f099b964fc79b640cf076954d Mon Sep 17 00:00:00 2001 From: Leland Richardson Date: Sat, 16 Sep 2017 16:38:07 -0700 Subject: [PATCH] Starting point --- README.md | 78 ++++++++++------ SUMMARY.md | 7 +- docs/common-issues.md | 38 -------- docs/future.md | 12 --- docs/guides/browserify.md | 53 +---------- docs/guides/jest.md | 4 - docs/guides/jsdom.md | 6 -- docs/guides/karma.md | 20 ---- .../migration-from-2-to-3.md} | 91 +++++++----------- docs/guides/mocha.md | 6 -- docs/guides/react-native.md | 5 - docs/guides/systemjs.md | 72 +------------- docs/guides/tape-ava.md | 11 ++- docs/guides/webpack.md | 93 +------------------ docs/installation/README.md | 6 +- docs/installation/react-013.md | 22 ++++- docs/installation/react-014.md | 25 ++++- docs/installation/react-15.md | 25 ++++- docs/installation/react-16.md | 56 +++++++++++ 19 files changed, 237 insertions(+), 393 deletions(-) rename docs/{future/migration.md => guides/migration-from-2-to-3.md} (84%) create mode 100644 docs/installation/react-16.md diff --git a/README.md b/README.md index 219a9c093..89e64b68b 100644 --- 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 index 88d1c780f..6d69e4d14 100644 --- 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 index 648d61366..35137c29b 100644 --- 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 index 9ce5c318d..d76f2c480 100644 --- 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 index a92ce4667..3b66a25b7 100644 --- 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 index ebd0ff950..ef6351ba0 100644 --- 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 index 943c3926f..d02a7fb78 100644 --- 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 index 682f4e878..a6b5b19c7 100644 --- 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) diff --git a/docs/future/migration.md b/docs/guides/migration-from-2-to-3.md similarity index 84% rename from docs/future/migration.md rename to docs/guides/migration-from-2-to-3.md index b56592862..dd5d736ef 100644 --- a/docs/future/migration.md +++ b/docs/guides/migration-from-2-to-3.md @@ -1,7 +1,7 @@ # Migration Guide for Enzyme v2.x to v3.x The change from Enzyme v2.x to v3.x is a more significant change than in previous major releases, -due to the fact that the internal implementation has been almost completely rewritten. +due to the fact that the internal implementation of Enzyme has been almost completely rewritten. The goal of this rewrite was to address a lot of the major issues that have plagued Enzyme since its initial release. It was also to simultaneously remove a lot of the dependence that Enzyme has @@ -10,16 +10,17 @@ with "React-like" libraries such as Preact and Inferno. We have done our best to make Enzyme v3 as API compatible with v2.x as possible, however there are a hand full of breaking changes that we decided we needed to make, intentionally, in order to -support this new architecture. +support this new architecture and also improve the usability of the library long-term. Airbnb has one of the largest Enzyme test suites, coming in at around 30,000 enzyme unit tests. After upgrading Enzyme to v3.x in Airbnb's code base, 99.6% of these tests succeeded with no modifications at all. Most of the tests that broke we found to be easy to fix, and some we found to actually be depending on what could arguably be considered a bug in v2.x, and the breakage was -desired. +actually desired. In this guide, we will go over a couple of the most common breakages that we ran into, and how to -fix them. Hopefully this will make your upgrade path that much easier. +fix them. Hopefully this will make your upgrade path that much easier. If during your upgrade you +find a breakage that doesn't seem to make sense to you, feel free to file an issue. ## Configuring your Adapter @@ -44,18 +45,20 @@ Enzyme.configure({ adapter: new Adapter() }); The list of adapter npm packages for React semver ranges are as follows: -- `enzyme-adapter-react-16` for `^16.0.0-0` -- `enzyme-adapter-react-15` for `^15.5.0` -- `enzyme-adapter-react-15.4` for `>= 15.0.0 && <15.5.0` -- `enzyme-adapter-react-14` for `^0.14.x` -- `enzyme-adapter-react-13` for `^0.13.x` +| 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` | ## Element referential identity is no longer preserved Enzyme's new architecture means that the react "render tree" is transformed into an intermediate representation that is common across all react versions so that Enzyme can properly traverse it -independent of React's internal representations. A side effect of this is that Enzyme no longer +independent of React's internal representations. A side effect of this is that Enzyme no longer has access to the actual object references that were returned from `render` in your React components. This normally isn't much of a problem, but can manifest as a test failure in some cases. @@ -93,7 +96,8 @@ transformations of the underlying react elements, and are thus different referen two elements being found. Although this is a breaking change, I believe the new behavior is closer to what people would -actually expect and want. +actually expect and want. Having Enzyme wrappers be immutable results in more deterministic tests +that are less prone to flakiness from external factors. ## `children()` now has slightly different meaning @@ -120,6 +124,8 @@ class Foo extends React.Component { } ``` +TODO: finish talking about this + ## For `mount`, updates are sometimes required when they weren't before React applications are dynamic. When testing your react components, you often want to test them @@ -242,7 +248,7 @@ wrapper.find('.count').text(); // => "Count: 0" (would have been "Count: 1" in v The problem here is that once we grab the instance using `wrapper.instance()`, Enzyme has no way of knowing if you are going to execute something that will cause a state transition, and thus does not -know when to ask for an updated render tree from React. As a result, `.text()` never changes value. +know when to ask for an updated render tree from React. As a result, `.text()` never changes value. The fix here is to use Enzyme's `wrapper.update()` method after a state change has occurred: @@ -261,15 +267,17 @@ wrapper.find('.count').text(); // => "Count: 1" ``` In practice we have found that this isn't actually needed that often, and when it is it is not -difficult to add. This breaking change was worth the architectural benefits of the new adapter -system in v3. +difficult to add. Additionally, having the Enzyme wrapper automatically update alongside the real +render tree can result in flaky tests when writing asynchronous tests. This breaking change was +worth the architectural benefits of the new adapter system in v3, and we believe is a better choice +for an assertion library to take. ## `ref(refName)` now returns the actual ref instead of a wrapper In Enzyme v2, the wrapper returned from `mount(...)` had a prototype method on it `ref(refName)` that returned a wrapper around the actual element of that ref. This has now been changed to -return the actual ref, which I believe is more intuitive. +return the actual ref, which we believe is a more intuitive API. Consider the following simple react component: @@ -293,11 +301,11 @@ expect(wrapper.ref('abc')).toBeInstanceOf(wrapper.constructor); ``` In v3, the contract is slightly changed. The ref is exactly what React would assign as the ref. In -this case, it would be an DOM Element: +this case, it would be a DOM Element: ```js const wrapper = mount(); -// this is what would happen with Enzyme v2 +// this is what happens with Enzyme v3 expect(wrapper.ref('abc')).toBeInstanceOf(Element); ``` @@ -318,55 +326,28 @@ const wrapper = mount(); expect(wrapper.ref('abc')).toBeInstanceOf(Box); ``` - In our experience, this is most often what people would actually want and expect out of the `.ref(...)` method. +## With `mount`, `instance()` can be called at any level of the tree -# New Features in Enzyme v3 - - -## `instance()` can be called at any level of the tree - -TODO: talk about this - - - - - - - - - - - - - - - - +Enzyme now allows for you to grab the `instance()` of a wrapper at any level of the render tree, +not just at the root. This means that you can `.find(...)` a specific component, then grab its +instance and call `.setState(...)` or any other methods on the instance that you'd like. +## for mount, getNode() should not be used. instance() does what it used to. -# Migration Guide (for React 0.13 - React 15.x) -## Root Wrapper +## Private properties and methods have been removed -The initially returned wrapper used to be around the element passed -into the `mount` API, and for `shallow` it was around the root node of the rendered output of the element passed in. After the upgrade, the -two APIs are now symmetrical, starting off +- `.node` +- `.nodes` +- `.renderer` - -```js -const x = 'x'; -const Foo = props =>
; -const wrapper = mount(); -``` -```js -expect(wrapper.props()).to.deep.equal({ outer: x }); -``` +## Cheerio has been updated, thus `render(...)` has been updated as well -## for mount, getNode() should not be used. instance() does what it used to. +## CSS Selector diff --git a/docs/guides/mocha.md b/docs/guides/mocha.md index 700dc6854..b9f507f2d 100644 --- a/docs/guides/mocha.md +++ b/docs/guides/mocha.md @@ -24,9 +24,3 @@ describe('', () => { }); ``` - - -## Example Projects - -- [enzyme-example-mocha](https://github.com/lelandrichardson/enzyme-example-mocha) -- [enzyme-example-react-native](https://github.com/lelandrichardson/enzyme-example-react-native) diff --git a/docs/guides/react-native.md b/docs/guides/react-native.md index 580277e53..ddbc88006 100644 --- a/docs/guides/react-native.md +++ b/docs/guides/react-native.md @@ -38,8 +38,3 @@ mocha --require react-native-mock/mock --recursive path/to/test/dir // This will mutate `react-native`'s require cache with `react-native-mock`'s. require('react-native-mock/mock'); // <-- side-effects!!! ``` - - -## Example Projects - -- [enzyme-example-react-native](https://github.com/lelandrichardson/enzyme-example-react-native) diff --git a/docs/guides/systemjs.md b/docs/guides/systemjs.md index f4c0ebb2e..212941fde 100644 --- a/docs/guides/systemjs.md +++ b/docs/guides/systemjs.md @@ -3,71 +3,7 @@ If you are using a test runner that runs code in a browser-based environment, you may be using [SystemJS]() in order to bundle your React code. -SystemJS 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 SystemJS. - -In your SystemJS 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: - -```json -/* package.json */ -{ - "jspm": { - "overrides": { - "npm:enzyme@2.3.0": { - "map": { - "react/addons": "@empty", - "react/lib/ExecutionEnvironment": "@empty", - "react/lib/ReactContext": "@empty" - } - } - } - } -} -``` - - -## 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 -``` - -## React 15 Compatibility - -If you are using React 15, your config should include these externals: - -```json -/* package.json */ -{ - "jspm": { - "overrides": { - "npm:enzyme@2.3.0": { - "map": { - "react/addons": "@empty", - "react/lib/ExecutionEnvironment": "@empty", - "react/lib/ReactContext": "@empty" - } - } - } - } -} -``` +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/tape-ava.md b/docs/guides/tape-ava.md index c2362b800..f9f1fa767 100644 --- a/docs/guides/tape-ava.md +++ b/docs/guides/tape-ava.md @@ -4,7 +4,7 @@ Enzyme works well with [Tape](https://github.com/substack/tape) and [AVA](https: Simply install it and start using it: ```bash -npm i --save-dev enzyme +npm i --save-dev enzyme enzyme-adapter-react-16 ``` ## Tape @@ -12,10 +12,13 @@ npm i --save-dev enzyme ```jsx import test from 'tape'; import React from 'react'; -import { shallow, mount } from 'enzyme'; +import { shallow, mount, configure } from 'enzyme'; +import Adapter from 'enzyme-adapter-react-16'; import Foo from '../path/to/foo'; +configure({ adapter: new Adapter() }); + test('shallow', (t) => { const wrapper = shallow(); t.equal(wrapper.contains(Foo), true); @@ -35,9 +38,13 @@ test('mount', (t) => { import test from 'ava'; import React from 'react'; import { shallow, mount } from 'enzyme'; +import { shallow, mount, configure } from 'enzyme'; +import Adapter from 'enzyme-adapter-react-16'; import Foo from '../path/to/foo'; +configure({ adapter: new Adapter() }); + test('shallow', (t) => { const wrapper = shallow(); t.is(wrapper.contains(Foo), true); diff --git a/docs/guides/webpack.md b/docs/guides/webpack.md index de20b03ff..71c2df4da 100644 --- a/docs/guides/webpack.md +++ b/docs/guides/webpack.md @@ -1,92 +1,9 @@ # Using Enzyme with Webpack If you are using a test runner that runs code in a browser-based environment, you may be using -[webpack]() in order to bundle your React code. +[webpack](https://webpack.js.org/) in order to bundle your React code. -Webpack uses static analysis to create a dependency graph at build-time of your source code to -build a bundle. Enzyme has a handful 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 -webpack. - -In your webpack configuration, you simply need to make sure that the following files are -labeled as "external", which means they will be ignored: - -``` -cheerio -react/addons -react/lib/ReactContext -react/lib/ExecutionEnvironment -``` - -Depending on if you are using Webpack 1 or Webpack 2 you will need different configurations. - -### Webpack 1 - -```js -/* webpack.config.js */ -module.exports = { - // ... - externals: { - cheerio: 'window', - 'react/addons': true, - 'react/lib/ExecutionEnvironment': true, - 'react/lib/ReactContext': true, - 'react-addons-test-utils': 'react-dom', - }, - // ... -}; -``` - -### Webpack 2 - -```js -/* webpack.config.js */ -module.exports = { - // ... - externals: { - cheerio: 'window', - 'react/addons': 'react', - 'react/lib/ExecutionEnvironment': 'react', - 'react/lib/ReactContext': 'react', - 'react-addons-test-utils': 'react-dom', - }, - // ... -}; -``` - - -## 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: - -``` -cheerio -react-dom -react-dom/server -react-addons-test-utils -``` - -## React 15 Compatibility - -If you are using React 15, your config should include these externals: - -```js -/* webpack.config.js */ -module.exports = { - // ... - externals: { - 'react/addons': true, - 'react/lib/ExecutionEnvironment': true, - 'react/lib/ReactContext': true, - 'react-addons-test-utils': 'react-dom', - }, - // ... -}; -``` - -## Example Projects - -- [enzyme-example-karma-webpack](https://github.com/lelandrichardson/enzyme-example-karma-webpack) +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/installation/README.md b/docs/installation/README.md index 6d2668cce..c53a834b1 100644 --- a/docs/installation/README.md +++ b/docs/installation/README.md @@ -10,8 +10,10 @@ Enzyme can be used with your test runner of choice. All examples in the document provided using [mocha](https://mochajs.org/) and [BDD style chai](http://chaijs.com/api/bdd/), although neither library is a dependency of enzyme. -{% include "./react-013.md" %} +{% include "./react-16.md" %} + +{% include "./react-15.md" %} {% include "./react-014.md" %} -{% include "./react-15.md" %} +{% include "./react-013.md" %} diff --git a/docs/installation/react-013.md b/docs/installation/react-013.md index b89bd1fb0..27a4f37b3 100644 --- a/docs/installation/react-013.md +++ b/docs/installation/react-013.md @@ -10,13 +10,22 @@ npm i react@0.13 --save Next, to get started with enzyme, you can simply install it with npm: ```bash -npm i --save-dev enzyme +npm i --save-dev enzyme enzyme-adapter-react-13 ``` And then you're ready to go! In your test files you can simply `require` or `import` enzyme: ES6: ```js +// setup file +import { configure } from 'enzyme'; +import Adapter from 'enzyme-adapter-react-13'; + +configure({ adapter: new Adapter() }); +``` + +```js +// test file import { shallow, mount, render } from 'enzyme'; const wrapper = shallow(); @@ -25,8 +34,17 @@ const wrapper = shallow(); ES5: ```js +// setup file +var Enzyme = require('enzyme'); +var Adapter = require('enzyme-adapter-react-13'); + +configure({ adapter: new Adapter() }); +``` + + +```js +// test file var enzyme = require('enzyme'); var wrapper = enzyme.shallow(); ``` - diff --git a/docs/installation/react-014.md b/docs/installation/react-014.md index e7a92ec06..388509ea9 100644 --- a/docs/installation/react-014.md +++ b/docs/installation/react-014.md @@ -7,7 +7,7 @@ installed, you should do so: npm i --save react@0.14 react-dom@0.14 ``` -Further, enzyme requires the test utilities addon be installed: +Further, enzyme with React 0.14 requires the test utilities addon be installed: ```bash npm i --save-dev react-addons-test-utils@0.14 @@ -16,13 +16,22 @@ npm i --save-dev react-addons-test-utils@0.14 Next, to get started with enzyme, you can simply install it with npm: ```bash -npm i --save-dev enzyme +npm i --save-dev enzyme enzyme-adapter-react-14 ``` And then you're ready to go! In your test files you can simply `require` or `import` enzyme: ES6: ```js +// setup file +import { configure } from 'enzyme'; +import Adapter from 'enzyme-adapter-react-14'; + +configure({ adapter: new Adapter() }); +``` + +```js +// test file import { shallow, mount, render } from 'enzyme'; const wrapper = shallow(); @@ -31,9 +40,17 @@ const wrapper = shallow(); ES5: ```js -var enzyme = require('enzyme'); +// setup file +var Enzyme = require('enzyme'); +var Adapter = require('enzyme-adapter-react-14'); -var wrapper = enzyme.shallow(); +configure({ adapter: new Adapter() }); ``` + +```js +// test file +var enzyme = require('enzyme'); +var wrapper = enzyme.shallow(); +``` diff --git a/docs/installation/react-15.md b/docs/installation/react-15.md index 8418142c6..721fb1f14 100644 --- a/docs/installation/react-15.md +++ b/docs/installation/react-15.md @@ -4,25 +4,34 @@ If you are wanting to use Enzyme with React 15, but don't already have React 15 installed, you should do so: ```bash -npm i --save react@15.0.0-rc.2 react-dom@15.0.0-rc.2 +npm i --save react@15 react-dom@15 ``` Further, enzyme requires the test utilities addon be installed: ```bash -npm i --save-dev react-addons-test-utils@15.0.0-rc.2 +npm i --save-dev react-test-renderer@15 ``` Next, to get started with enzyme, you can simply install it with npm: ```bash -npm i --save-dev enzyme +npm i --save-dev enzyme enzyme-adapter-react-15 ``` And then you're ready to go! In your test files you can simply `require` or `import` enzyme: ES6: ```js +// setup file +import { configure } from 'enzyme'; +import Adapter from 'enzyme-adapter-react-15'; + +configure({ adapter: new Adapter() }); +``` + +```js +// test file import { shallow, mount, render } from 'enzyme'; const wrapper = shallow(); @@ -31,6 +40,16 @@ const wrapper = shallow(); ES5: ```js +// setup file +var Enzyme = require('enzyme'); +var Adapter = require('enzyme-adapter-react-15'); + +configure({ adapter: new Adapter() }); +``` + + +```js +// test file var enzyme = require('enzyme'); var wrapper = enzyme.shallow(); diff --git a/docs/installation/react-16.md b/docs/installation/react-16.md new file mode 100644 index 000000000..7717f3832 --- /dev/null +++ b/docs/installation/react-16.md @@ -0,0 +1,56 @@ +# Working with React 16 + +If you are wanting to use Enzyme with React 16, but don't already have React 16 and react-dom +installed, you should do so: + +```bash +npm i --save react@16 react-dom@16 +``` + +Further, enzyme requires the test utilities addon be installed: + +```bash +npm i --save-dev react-test-renderer@16 +``` + +Next, to get started with enzyme, you can simply install it with npm: + +```bash +npm i --save-dev enzyme enzyme-react-adapter-16 +``` + +And then you're ready to go! In your test files you can simply `require` or `import` enzyme: + +ES6: +```js +// setup file +import { configure } from 'enzyme'; +import Adapter from 'enzyme-adapter-react-16'; + +configure({ adapter: new Adapter() }); +``` + +```js +// test file +import { shallow, mount, render } from 'enzyme'; + +const wrapper = shallow(); +``` + +ES5: + +```js +// setup file +var Enzyme = require('enzyme'); +var Adapter = require('enzyme-adapter-react-16'); + +configure({ adapter: new Adapter() }); +``` + + +```js +// test file +var enzyme = require('enzyme'); + +var wrapper = enzyme.shallow(); +```