Add guide on next tick (#1156)

* docs: update getting started

* docs: update common tips

* docs: update testing-async-components

* docs: remove details on sync updating

* Update testin-async-components

* docs: update common-tips section

* docs: reword getting-started

* docs: reword

* docs: update getting-started

* docs: reword

* docs: reword

* docs: update example

Author: eddyerburgh

docs/guides/common-tips.md

@@ -27,6 +27,30 @@ const wrapper = shallowMount(Component)
 wrapper.vm // the mounted Vue instance
 ```
 
+### Using `nextTick`
+
+Vue batches watcher updates and runs them asynchronously on the "next tick".
+
+In practice, this means you must wait for updates to run after you set a reactive property. You can wait for updates with `Vue.nextTick()`:
+
+```js
+it('updates text', async () => {
+  const wrapper = mount(Component)
+  wrapper.trigger('click')
+  await Vue.nextTick()
+  expect(wrapper.text()).toContain('updated')
+})
+```
+
+The following methods often cause watcher updates that require you to wait for the next tick:
+
+- `setChecked`
+- `setData`
+- `setSelected`
+- `setProps`
+- `setValue`
+- `trigger`
+
 ### Asserting Emitted Events
 
 Each mounted wrapper automatically records all events emitted by the underlying Vue instance. You can retrieve the recorded events using the `wrapper.emitted()` method:

docs/guides/dom-events.md

@@ -207,7 +207,3 @@ A key name after the dot `keydown.up` is translated to a `keyCode`. This is supp
 | home      | 36       |
 | pageup    | 33       |
 | pagedown  | 34       |
-
-### Important
-
-Vue Test Utils triggers event synchronously. Consequently, `Vue.nextTick` is not required.

docs/guides/getting-started.md

@@ -102,15 +102,29 @@ it('button click should increment the count', () => {
 })
 ```
 
-### What about `nextTick`?
+In order to test that the counter text has updated, we need to learn about `nextTick`.
 
-Vue batches pending DOM updates and applies them asynchronously to prevent unnecessary re-renders caused by multiple data mutations. This is why in practice we often have to use `Vue.nextTick` to wait until Vue has performed the actual DOM update after we trigger some state change.
+### Using `nextTick`
 
-To simplify usage, Vue Test Utils applies all updates synchronously so you don't need to use `Vue.nextTick` to wait for DOM updates in your tests.
+Vue batches pending DOM updates and applies them asynchronously to prevent unnecessary re-renders caused by multiple data mutations.
 
-_Note: `nextTick` is still necessary when you need to explictly advance the event loop, for operations such as asynchronous callbacks or promise resolution._
+_You can read more about asynchronous updates in the [Vue docs](https://vuejs.org/v2/guide/reactivity.html#Async-Update-Queue)_
 
-If you do still need to use `nextTick` in your test files, be aware that any errors thrown inside it may not be caught by your test runner as it uses promises internally. There are two approaches to fixing this: either you can set the `done` callback as Vue's global error handler at the start of the test, or you can call `nextTick` without an argument and return it as a promise:
+We need to use `Vue.nextTick()` to wait until Vue has performed the DOM update after we set a reactive property. In the counter example, setting the `count` property schedules a DOM update to run on the next tick.
+
+We can `await` `Vue.nextTick()` by writing the tests in an async function:
+
+```js
+it('button click should increment the count text', async () => {
+  expect(wrapper.text()).toContain('0')
+  const button = wrapper.find('button')
+  button.trigger('click')
+  await Vue.nextTick()
+  expect(wrapper.text()).toContain('1')
+})
+```
+
+When you use `nextTick` in your test files, be aware that any errors thrown inside it may not be caught by your test runner as it uses promises internally. There are two approaches to fixing this: either you can set the `done` callback as Vue's global error handler at the start of the test, or you can call `nextTick` without an argument and return it as a promise:
 
 ```js
 // this will not be caught

docs/guides/testing-async-components.md

@@ -1,8 +1,33 @@
 ## Testing Asynchronous Behavior
 
-To simplify testing, Vue Test Utils applies DOM updates _synchronously_. However, there are some techniques you need to be aware of when testing a component with asynchronous behavior such as callbacks or promises.
+There are two types of asynchronous behavior you will encounter in your tests:
 
-One of the most common asynchronous behaviors is API calls and Vuex actions. The following examples shows how to test a method that makes an API call. This example uses Jest to run the test and to mock the HTTP library `axios`. More about Jest manual mocks can be found [here](https://jestjs.io/docs/en/manual-mocks#content).
+1. Updates applied by Vue
+2. Asynchronous behavior outside of Vue
+
+## Updates applied by Vue
+
+Vue batches pending DOM updates and applies them asynchronously to prevent unnecessary re-renders caused by multiple data mutations.
+
+_You can read more about asynchronous updates in the [Vue docs](https://vuejs.org/v2/guide/reactivity.html#Async-Update-Queue)_
+
+In practice, this means you have to use `Vue.nextTick()` to wait until Vue has performed updates after you set a reactive property.
+
+The easiest way to use `Vue.nextTick()` is to write your tests in an async function:
+
+```js
+it('button click should increment the count text', async () => {
+  expect(wrapper.text()).toContain('0')
+  const button = wrapper.find('button')
+  button.trigger('click')
+  await Vue.nextTick()
+  expect(wrapper.text()).toContain('1')
+})
+```
+
+## Asynchronous behavior outside of Vue
+
+One of the most common asynchronous behaviors outside of Vue is API calls in Vuex actions. The following examples shows how to test a method that makes an API call. This example uses Jest to run the test and to mock the HTTP library `axios`. More about Jest manual mocks can be found [here](https://jestjs.io/docs/en/manual-mocks.html#content).
 
 The implementation of the `axios` mock looks like this: