-//
-//
-
-// Expected tree output
-// tree = renderer.getNode();
-tree = {
- type: 'div',
- nodeType: 'host',
- props: {},
- rendered: [
- {
- type: Foo,
- props: {},
- nodeType: 'host',
- rendered: null,
- },
- ],
-};
-
-renderer = Adapter.createRenderer({
- // In this case, we treat `Bar` as a host node
- // but `Qoo` is not, so gets rendered
- isHost: el => [Bar].includes(el.type),
-});
-
-renderer.render(
);
-
-// Conceptual debug output:
-//
-//
-//
-// Hello World!
-//
-//
-//
-
-// Expected tree output
-// tree = renderer.getNode();
-tree = {
- type: Bam,
- nodeType: 'function',
- props: {},
- rendered: {
- type: Bar,
- nodeType: 'host',
- props: { special: true },
- rendered: [
- {
- type: Qoo,
- nodeType: 'function',
- props: {},
- rendered: {
- type: 'span',
- nodeType: 'host',
- props: { className: 'Qoo' },
- rendered: ['Hello World!'],
- },
- },
- ],
- },
-};
diff --git a/docs/guides.md b/docs/guides.md
index 78db45470..5012fc7c2 100644
--- a/docs/guides.md
+++ b/docs/guides.md
@@ -1,11 +1,11 @@
-# Enzyme Guides
+# enzyme Guides
-- [*Using Enzyme with Browserify*](guides/browserify.md)
-- [*Using Enzyme with WebPack*](guides/webpack.md)
-- [*Using Enzyme with JSDOM*](guides/jsdom.md)
-- [*Using Enzyme with Jest*](guides/jest.md)
-- [*Using Enzyme with Karma*](guides/karma.md)
-- [*Using Enzyme with Mocha*](guides/mocha.md)
-- [*Using Enzyme with React Native*](guides/react-native.md)
-- [*Using Enzyme with Lab*](guides/lab.md)
-- [*Using Enzyme with Tape and AVA*](guides/tape-ava.md)
+- [*Using enzyme with Browserify*](guides/browserify.md)
+- [*Using enzyme with WebPack*](guides/webpack.md)
+- [*Using enzyme with JSDOM*](guides/jsdom.md)
+- [*Using enzyme with Jest*](guides/jest.md)
+- [*Using enzyme with Karma*](guides/karma.md)
+- [*Using enzyme with Mocha*](guides/mocha.md)
+- [*Using enzyme with React Native*](guides/react-native.md)
+- [*Using enzyme with Lab*](guides/lab.md)
+- [*Using enzyme with Tape and AVA*](guides/tape-ava.md)
diff --git a/docs/guides/browserify.md b/docs/guides/browserify.md
index a92ce4667..75e351c96 100644
--- a/docs/guides/browserify.md
+++ b/docs/guides/browserify.md
@@ -1,52 +1,9 @@
-# Using Enzyme with Browserify
+# 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..fa4347dbb 100644
--- a/docs/guides/jest.md
+++ b/docs/guides/jest.md
@@ -1,10 +1,10 @@
-# Using Jest with Enzyme
+# Using Jest with enzyme
## Jest version 15 and up
-Starting with version 15, Jest [no longer mocks modules by default](https://facebook.github.io/jest/blog/2016/09/01/jest-15.html). Because of this, you no longer have to add _any_ special configuration for Jest to use it with Enzyme.
+Starting with version 15, Jest [no longer mocks modules by default](https://facebook.github.io/jest/blog/2016/09/01/jest-15.html). Because of this, you no longer have to add _any_ special configuration for Jest to use it with enzyme.
-Install Jest, and its Babel integrations, as recommended in the [Jest docs](https://facebook.github.io/jest/docs/getting-started.html). Install Enzyme. Then, simply require/import React, Enzyme functions, and your module at the top of a test file.
+Install Jest, and its Babel integrations, as recommended in the [Jest docs](https://facebook.github.io/jest/docs/getting-started.html). Install enzyme. Then, simply require/import React, enzyme functions, and your module at the top of a test file.
```js
import React from 'react';
@@ -21,7 +21,7 @@ You do **not** need to include Jest's own renderer, unless you want to use it _o
## Jest prior to version 15
-If you are using Jest 0.9 – 14.0 with Enzyme and using Jest's automocking feature, you will need to mark react and enzyme to be unmocked in your `package.json`:
+If you are using Jest 0.9 – 14.0 with enzyme and using Jest's automocking feature, you will need to mark react and enzyme to be unmocked in your `package.json`:
`package.json`:
```json
@@ -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..7f02d15c0 100644
--- a/docs/guides/jsdom.md
+++ b/docs/guides/jsdom.md
@@ -1,4 +1,4 @@
-# Using Enzyme with JSDOM
+# Using enzyme with JSDOM
[JSDOM](https://github.com/tmpvar/jsdom) is a JavaScript based headless browser that can be used to create a realistic testing environment.
@@ -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..748c2428f 100644
--- a/docs/guides/karma.md
+++ b/docs/guides/karma.md
@@ -1,13 +1,13 @@
-# Using Enzyme with Karma
+# Using enzyme with Karma
-Karma is a popular test runner that can run tests in browser environments. Enzyme is compatible with
+Karma is a popular test runner that can run tests in browser environments. enzyme is compatible with
Karma, but often requires a little bit of configuration.
This configuration largely depends on which plugins you are using to bundle your JavaScript code. In
the case of Browserify or Webpack, see the below documentation in order to get these up and running.
-## Enzyme + Karma + Webpack
+## enzyme + Karma + Webpack
See the [webpack guide](webpack.md).
@@ -28,20 +28,13 @@ 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',
- },
},
// ...
});
};
```
-## Enzyme + Karma + Browserify
+## enzyme + Karma + Browserify
See the [browserify guide](browserify.md).
@@ -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/guides/lab.md b/docs/guides/lab.md
index 6fe23f443..70ad4ab5a 100644
--- a/docs/guides/lab.md
+++ b/docs/guides/lab.md
@@ -1,9 +1,9 @@
-# Using Enzyme with Lab and Code
+# Using enzyme with Lab and Code
[Lab](https://github.com/hapijs/lab) is a simple test utility for node & part of the [Hapi.js](https://github.com/hapijs/hapi) framework universe. Lab's initial code borrowed heavily from [Mocha](https://github.com/mochajs/mocha). [Code](https://github.com/hapijs/code) is Lab's standard assertion library and was created as a direct rewrite of [Chai](https://github.com/chaijs).
-# Example Test: Enzyme + Lab + Code
+# Example Test: enzyme + Lab + Code
```jsx
import { shallow, mount, render } from 'enzyme';
diff --git a/docs/future/migration.md b/docs/guides/migration-from-2-to-3.md
similarity index 51%
rename from docs/future/migration.md
rename to docs/guides/migration-from-2-to-3.md
index b56592862..388c93525 100644
--- a/docs/future/migration.md
+++ b/docs/guides/migration-from-2-to-3.md
@@ -1,39 +1,40 @@
-# Migration Guide for Enzyme v2.x to v3.x
+# 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.
+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 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
-on react internals, and to make enzyme more "pluggable", paving the way for Enzyme to be used
+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
+on react internals, and to make enzyme more "pluggable", paving the way for enzyme to be used
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
+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
+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
-Enzyme now has an "Adapter" system. This means that you now need to install Enzyme along with
-another module that provides the Adapter that tells Enzyme how to work with your version of React
+enzyme now has an "Adapter" system. This means that you now need to install enzyme along with
+another module that provides the Adapter that tells enzyme how to work with your version of React
(or whatever other react-like library you are using).
-At the time of writing this, Enzyme publishes "officially supported" adapters for React 0.13.x,
+At the time of writing this, enzyme publishes "officially supported" adapters for React 0.13.x,
0.14.x, 15.x, and 16.x. These adapters are npm packages of the form `enzyme-adapter-react-{{version}}`.
-You will want to configure Enzyme with the adapter you'd like to use before using enzyme in your
-tests. The way to do this is whith `Enzyme.configure(...)`. For example, if your project depends
-on React 16, you would want to configure Enzyme this way:
+You will want to configure enzyme with the adapter you'd like to use before using enzyme in your
+tests. The way to do this is whith `enzyme.configure(...)`. For example, if your project depends
+on React 16, you would want to configure enzyme this way:
```js
import Enzyme from 'enzyme';
@@ -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
+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
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.
@@ -88,16 +91,17 @@ const iconCount = wrapper.find(Icon).length;
In v2.x, `iconCount` would be 1. In v3.x, it will be 2. This is because in v2.x it would find all
of the elements matching the selector, and then remove any duplicates. Since `ICONS.success` is
included twice in the render tree, but it's a constant that's reused, it would show up as a
-duplicate in the eyes of Enzyme v2.x. In Enzyme v3, the elements that are traversed are
+duplicate in the eyes of enzyme v2.x. In enzyme v3, the elements that are traversed are
transformations of the underlying react elements, and are thus different references, resulting in
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
-Enzyme has a `.children()` method which is intended to return the rendered children of a wrapper.
+enzyme has a `.children()` method which is intended to return the rendered children of a wrapper.
When using `mount(...)`, it can sometimes be unclear exactly what this would mean. Consider for
example the following react components:
@@ -120,6 +124,38 @@ class Foo extends React.Component {
}
```
+Now lets say we have a test which does something like:
+
+```js
+const wrapper = mount(
);
+```
+
+At this point, there is an ambiguity about what `wrapper.find(Box).children()` should return.
+Although the `
` element has a `children` prop of `
`, the actual
+rendered children of the element that the box component renders is a `
...
`
+element.
+
+Prior enzyme v3, we would observe the following behavior:
+
+```js
+wrapper.find(Box).children().debug();
+// =>
+```
+
+In enzyme v3, we now have `.children()` return the *rendered* children. In other words, it returns
+the element that is returned from that component's `render` function.
+
+```js
+wrapper.find(Box).children().debug();
+// =>
+//
+```
+
+This may seem like a subtle difference, but making this change will be important for future APIs
+we would like to introduce.
+
## 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
@@ -155,18 +191,18 @@ class CurrentTime extends React.Component {
```
In this code, there is a timer that continuously changes the rendered output of this component. This
-might be a reasonable thing to do in your application. The thing is, Enzyme has no way of knowing
-that these changes are taking place, and no way to automatically update the render tree. In Enzyme
-v2, Enzyme operated *directly* on the in-memory representation of the render tree that React itself
-had. This means that even though Enzyme couldn't know when the render tree was updated, updates
+might be a reasonable thing to do in your application. The thing is, enzyme has no way of knowing
+that these changes are taking place, and no way to automatically update the render tree. In enzyme
+v2, enzyme operated *directly* on the in-memory representation of the render tree that React itself
+had. This means that even though enzyme couldn't know when the render tree was updated, updates
would be reflected anyway, since React *does* know.
-Enzyme v3 architecturally created a layer where React would create an intermediate representation
-of the render tree at an instance in time and pass that to Enzyme to traverse and inspect. This has
+enzyme v3 architecturally created a layer where React would create an intermediate representation
+of the render tree at an instance in time and pass that to enzyme to traverse and inspect. This has
many advantages, but one of the side effects is that now the intermediate representation does not
receive automatic updates.
-Enzyme does attempt to automatically "update" the root wrapper in most common scenarios, but these
+enzyme does attempt to automatically "update" the root wrapper in most common scenarios, but these
are only the state changes that it knows about. For all other state changes, you may need to call
`wrapper.update()` yourself.
@@ -200,7 +236,7 @@ class Counter extends React.Component {
This is a basic "counter" component in React. Here our resulting markup is a function of
`this.state.count`, which can get updated by the `increment` and `decrement` functions. Let's take a
-look at what some Enzyme tests with this component might look like, and when we do or don't have to
+look at what some enzyme tests with this component might look like, and when we do or don't have to
call `update()`.
```js
@@ -223,7 +259,7 @@ wrapper.find('.dec').simulate('click');
wrapper.find('.count').text(); // => "Count: 1"
```
-In this case Enzyme will automatically check for updates after an event simulation takes place, as
+In this case enzyme will automatically check for updates after an event simulation takes place, as
it knows that this is a very common place for state changes to occur. In this case there is no
difference between v2 and v3.
@@ -240,11 +276,11 @@ wrapper.instance().decrement();
wrapper.find('.count').text(); // => "Count: 0" (would have been "Count: 1" in v2)
```
-The problem here is that once we grab the instance using `wrapper.instance()`, Enzyme has no way of
+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:
+The fix here is to use enzyme's `wrapper.update()` method after a state change has occurred:
```js
const wrapper = shallow(
);
@@ -261,15 +297,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)`
+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:
@@ -288,16 +326,16 @@ share the same constructor:
```js
const wrapper = mount(
);
-// this is what would happen with Enzyme v2
+// this is what would happen with enzyme v2
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 +356,120 @@ 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
+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.
-## `instance()` can be called at any level of the tree
+## With `mount`, `.getNode()` should not be used. `.instance()` does what it used to.
-TODO: talk about this
+For `mount` wrappers, the `.getNode()` method used to return the actual component instance. This
+method no longer exists, but `.instance()` is functionally equivalent to what `.getNode()` used to
+be.
+## With `shallow`, `.getNode()` should be replaced with `getElement()`
+For shallow wrappers, if you were previously using `.getNode()`, you will want to replace those
+calls with `.getElement()`, which is now functionally equivalent to what `.getNode()` used to do.
+One caveat is that previously `.getNode()` would return the actual element instance that was
+created in the `render` function of the component you were testing, but now it will be a
+structurally equal react element, but not referentially equal. Your tests will need to be updated to
+account for this.
+## Private properties and methods have been removed
+There are several properties that are on an enzyme "wrapper" that were considered to be private and
+were undocumented as a result. Despite being undocumented, people may haev been relying on them. In
+an effort to make making changes less likely to be accidentally breaking in the future, we have
+decided to make these properties properly "private". The following properties will no longer be
+accessible on enzyme `shallow` or `mount` instances:
+- `.node`
+- `.nodes`
+- `.renderer`
+- `.unrendered`
+- `.root`
+- `.options`
+## Cheerio has been updated, thus `render(...)` has been updated as well
+enzyme's top level `render` API returns a [Cheerio](https://github.com/cheeriojs/cheerio) object.
+The version of Cheerio that we use has been upgraded to 1.0.0. For debugging issues across enzyme
+v2.x and v3.x with the `render` API, we recommend checking out [Cheerio's Changelog](https://github.com/cheeriojs/cheerio/blob/48eae25c93702a29b8cd0d09c4a2dce2f912d1f4/History.md) and
+posting an issue on that repo instead of enzyme's unless you believe it is a bug in enzyme's use
+of the library.
+## CSS Selector
+enzyme v3 now uses a real CSS selector parser rather than its own incomplete parser implementation.
+This is done with [rst-selector-parser](https://github.com/aweary/rst-selector-parser) a fork of [scalpel](https://github.com/gajus/scalpel/) which is a CSS parser implemented with [nearley](https://nearley.js.org/).
+We don't think this should cause any breakages across enzyme v2.x to v3.x, but if you believe you
+have found something that did indeed break, please file an issue with us. Thank you to
+[Brandon Dail](https://github.com/aweary) for making this happen!
+## Node Equality now ignores `undefined` values
+We have updated enzyme to consider node "equality" in a semantically identical way to how react
+treats nodes. More specifically, we've updated enzyme's algorithms to treat `undefined` props as
+equivalent to the absence of a prop. Consider the following example:
+
+```js
+class Foo extends React.Component {
+ render() {
+ return
;
+ }
+}
+```
+With this component, the behavior in enzyme v2.x the behavior would have been like:
+```js
+const wrapper = shallow(
);
+wrapper.equals(
); // => false
+wrapper.equals(
); // => true
+```
+With enzyme v3, the behavior is now as follows:
+```js
+const wrapper = shallow(
);
+wrapper.equals(
); // => true
+wrapper.equals(
); // => true
+```
-# Migration Guide (for React 0.13 - React 15.x)
+## Lifecycle methods
+enzyme v2.x had an optional flag that could be passed in to all `shallow` calls which would make it
+so that more of the component's lifecycle methods were called (such as `componentDidMount` and
+`componentDidUpdate`).
-## Root Wrapper
+With enzyme v3, we have now turned on this mode by default, instead of making it opt-in. It is now
+possible to *opt-out* instead. Additionally, you can now opt-out at a global level.
-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
+If you'd like to opt out globally, you can run the following:
-
```js
-const x = 'x';
-const Foo = props =>
;
-const wrapper = mount(
);
+import Enzyme from 'enzyme';
+
+Enzyme.configure({ disableLifecycleMethods: true });
```
+This will default enzyme back to the previous behavior globally. If instead you'd only like to opt
+enzyme to the previous behavior for a specific test, you can do the following:
+
```js
-expect(wrapper.props()).to.deep.equal({ outer: x });
-```
+import { shallow } from 'enzyme';
-## for mount, getNode() should not be used. instance() does what it used to.
+// ...
+
+const wrapper = shallow(
, { disableLifecycleMethods: true });
+```
diff --git a/docs/guides/mocha.md b/docs/guides/mocha.md
index 700dc6854..735936112 100644
--- a/docs/guides/mocha.md
+++ b/docs/guides/mocha.md
@@ -1,6 +1,6 @@
-# Using Enzyme with Mocha
+# Using enzyme with Mocha
-Enzyme was originally designed to work with Mocha, so getting it up and running with Mocha should
+enzyme was originally designed to work with Mocha, so getting it up and running with Mocha should
be no problem at all. Simply install it and start using it:
```bash
@@ -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..d2a927cd5 100644
--- a/docs/guides/react-native.md
+++ b/docs/guides/react-native.md
@@ -1,7 +1,7 @@
-# Using Enzyme to Test Components in React Native
+# Using enzyme to Test Components in React Native
As of v0.18, React Native uses React as a dependency rather than a forked version of the library,
-which means it is now possible to use Enzyme's `shallow` with React Native components.
+which means it is now possible to use enzyme's `shallow` with React Native components.
Unfortunately, React Native has many environmental dependencies that can be hard to simulate without
a host device.
@@ -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..e4bf45c4b 100644
--- a/docs/guides/systemjs.md
+++ b/docs/guides/systemjs.md
@@ -1,73 +1,9 @@
-# Using Enzyme with SystemJS
+# Using enzyme with SystemJS
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..3c554555f 100644
--- a/docs/guides/tape-ava.md
+++ b/docs/guides/tape-ava.md
@@ -1,10 +1,10 @@
-# Using Enzyme with Tape and AVA
+# Using enzyme with Tape and AVA
-Enzyme works well with [Tape](https://github.com/substack/tape) and [AVA](https://github.com/avajs/ava).
+enzyme works well with [Tape](https://github.com/substack/tape) and [AVA](https://github.com/avajs/ava).
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);
@@ -34,10 +37,13 @@ test('mount', (t) => {
```jsx
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..4895f515b 100644
--- a/docs/guides/webpack.md
+++ b/docs/guides/webpack.md
@@ -1,92 +1,9 @@
-# Using Enzyme with Webpack
+# 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..d2cd67de6 100644
--- a/docs/installation/README.md
+++ b/docs/installation/README.md
@@ -1,17 +1,19 @@
# Installation
-Enzyme should be installed using npm:
+enzyme should be installed using npm:
```bash
npm i --save-dev enzyme
```
-Enzyme can be used with your test runner of choice. All examples in the documentation will be
+enzyme can be used with your test runner of choice. All examples in the documentation will be
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..c889d31ce 100644
--- a/docs/installation/react-013.md
+++ b/docs/installation/react-013.md
@@ -1,6 +1,6 @@
# Working with React 0.13
-If you are wanting to use Enzyme with React 0.13, but don't already have React 0.13 installed, you
+If you are wanting to use enzyme with React 0.13, but don't already have React 0.13 installed, you
should do so:
```bash
@@ -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..1cef870f0
--- /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(
);
+```
diff --git a/packages/enzyme-adapter-react-15/src/ReactFifteenAdapter.js b/packages/enzyme-adapter-react-15/src/ReactFifteenAdapter.js
index 19aef1359..564332de7 100644
--- a/packages/enzyme-adapter-react-15/src/ReactFifteenAdapter.js
+++ b/packages/enzyme-adapter-react-15/src/ReactFifteenAdapter.js
@@ -4,6 +4,7 @@ import ReactDOM from 'react-dom';
import ReactDOMServer from 'react-dom/server';
// eslint-disable-next-line import/no-unresolved, import/extensions
import TestUtils from 'react-dom/test-utils';
+// eslint-disable-next-line import/no-unresolved, import/extensions
import ShallowRenderer from 'react-test-renderer/shallow';
import values from 'object.values';
import { EnzymeAdapter } from 'enzyme';