From d824527d67aff438869ad2232697526cf39b5959 Mon Sep 17 00:00:00 2001
From: Yevhen Kozlov <skyboyer@gmail.com>
Date: Sun, 26 May 2019 01:17:05 +0300
Subject: [PATCH] [Docs] explained why need to re-call .find() after update

This behavior currently is explained only in 2-to-3 version migration guide. People who never used v2 have small chance to get there.
Since it's related to different methods and both mount/shallow suppose this file is better place for describing that.
---
 docs/common-issues.md | 45 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/common-issues.md b/docs/common-issues.md
index 5c8f13810..901851466 100644
--- a/docs/common-issues.md
+++ b/docs/common-issues.md
@@ -10,6 +10,51 @@ This could be due to a regression, or the feature is not yet implemented. If you
 certain query syntax, make sure it is implemented first before raising an issue. Here is the list of
 selectors we currently support: https://github.com/airbnb/enzyme/blob/master/docs/api/selector.md
 
+### Nested component may not be updated after wrapper updates
+
+Assume we have a simple component with an `<input />` and a `<button>`. Clicking the `<button>` updates the `<input>`'s value.
+
+However, this test fails:
+```jsx
+const input = wrapper.find('input');
+const button = wrapper.find('button');
+button.prop('onClick')();
+expect(input.prop('value')).to.equal('test');
+```
+fails. While this test:
+```jsx
+const input = wrapper.find('input');
+const button = wrapper.find('button');
+button.prop('onClick')();
+expect(wrapper.find('input').prop('value')).to.equal('test');
+```
+passes.
+
+This is because the wrapper returned by `.find()` (and every other method that produces a new wrapper) is immutable and won't update.
+
+More details and motivation can be found at [migration from 2 to 3: Calling props() after a state change](https://github.com/airbnb/enzyme/blob/master/docs/guides/migration-from-2-to-3.md#calling-props-after-a-state-change).
+
+###### Solutions
+
+Instead of storing `.find()` results into a local variable, re-find from the root after any change.
+
+```jsx
+wrapper.find('button').props().onClick();
+expect(wrapper.find('input').prop('value')).to.equal('test');
+```
+
+or we may wrap that into helper function(s) to call them each time
+
+```jsx
+function getButton(wrapper) {
+  return wrapper.find('button');
+}
+
+// …
+
+getButton(wrapper).prop('onClick')();
+```
+
 ### Testing third party libraries
 
 Some third party libraries are difficult or impossible to test. enzyme's scope is severely limited to what