Add async guide #282

lmiller1990 · 2017-12-20T08:03:20Z

As discussed in #246 , some more guides for common pitfalls might be nice.

@eddyerburgh this is just my first draft, I'd like some input on the content, style, etc. Thanks!

eddyerburgh

Thanks for the PR! So I wasn't aware that watchers weren't running during update!

I'm going to run watchers as part of update, so your original example will pass.

We should keep the section on testing async APIs.

it looks like a good guide. Some minor points:

can you stylize methods without the parentheses, so done() becomes done.
we should mention update

callumacrae · 2017-12-20T10:57:39Z

docs/en/guides/testing-async-components.md

+    wrapper.find('input').trigger('input')
+
+    wrapper.vm.$nextTick(() => {
+      expect(wrapper.vm.showButton).toBe(true)


If this assertion throws, will the error be caught, or will the test time out? In my experience, it's the latter.

Mind you, I've been using mocha which doesn't handle uncaught promise errors. might be different with jest

I think it will time out @callumacrae . What is the best thing to do in this situation?

not sure. i made an issue about it here: #213

LinusBorg · 2017-12-20T11:03:30Z

docs/en/guides/testing-async-components.md

@@ -0,0 +1,159 @@
+# Testing Asynchronous Components


This headline might be confused with "Async components".

Maybe: "Testing Asynchronous Behaviour" ?

Good catch @LinusBorg . I think your suggested title is better. Minor, but In my day to day life I spell it behaviour, should use use American English (no u) or English/Europe/everywhere else English?

Hm. I think we should probably stick do American english as that's the bigger "market"?

OTOH @eddyerburgh is british so ..., :-P

Indeed I am British 🇬🇧

I am Australian (English colony) so we use the same style. But I agree we should use the American English since I believe the official docs would use that.

Yeah, we should use US English

lmiller1990 · 2017-12-20T11:24:34Z

@eddyerburgh good idea about mentioning update. What exactly does update do, just force nextTick?

eddyerburgh · 2017-12-20T12:20:15Z

@lmiller1990 At the moment, it forces a component re-render.

I think we should also make it run all the component and child component watchers. I'm trying to think whether this would have unintended consequences 🤔

lmiller1990 · 2017-12-21T00:29:27Z

Removed watch example, since that'll be solved in #283 .

Will look add adding more about update. Can you think of any good examples where running update is important for async tests @eddyerburgh ? I haven't had to use it much. Or were you just thinking to add something so users are more aware of how vue-test-utils works, in a synchronous fashion?

eddyerburgh · 2017-12-22T09:53:42Z

In fact, calling a synchronous method that updates state will also require calling update.
Any time state is changed, you need to call update. In all vue-test-utils methods that change or can change state, like trigger, setData, setProps, update is called to trigger a re render.

If state is changed outside of vue-test-utils, by mutating the state directly, or by triggering a method, update must be called to update the render tree.

@lmiller1990 An example for this guide would be when you trigger an async method by calling it on the vm:

const Component = {
  template: `<div>{{someData}}</div>`,
  data() {
    return {
      someData: 0
    }
  },
  methods: {
    asyncMethod() {
     Promise.resolve(() => {
      this.someData++
     })
    }
  }
}

const wrapper = mount(Component)
wrapper.vm.asyncMethod()
await flushPromises()
wrapper.update()
expect(wrapper.text()).toBe(1)

lmiller1990 · 2017-12-22T16:28:58Z

@eddyerburgh I haven't actually ran into this issue - calling the methods on the wrapper seems to actually implicitly call update as well. The following (basically what you wrote above) actually passes.

<template>
  <div>
    {{someData}}
  </div>
</template>

<script>
  export default {
    data () {
      return {
        someData: 0
      }
    },
    methods: {
      asyncMethod () {
        Promise.resolve(() => {
        }).then(() => {
          this.someData += 1
        })
      }
    }
  }
</script>

import {shallow} from 'vue-test-utils'
import Update from './Update'
import flushPromises from 'flush-promises'

describe('Update', () => {
  it('works', async () => {
    const wrapper = shallow(Update)
    wrapper.vm.asyncMethod()
    await flushPromises()
    expect(wrapper.vm.someData).toBe(1)
    expect(wrapper.text()).toBe('1')
  })
})

I haven't actually hit any situations where I've had to call update. Do you have another example?

eddyerburgh · 2017-12-22T16:54:37Z

Ah—when flush-promises has finished, the component will have re rendered.

Looks like we don't need to include updates in this guide 😂

lmiller1990 · 2017-12-23T12:44:06Z

@eddyerburgh ok. Is there anything else you think I should change or improve? Would be nice to get this in.

Also, I fixed up the failing tests regarding no trailing whitespace, but it appears to be actually linting the example code, and complaining that await is a reserved keyword and it also doesn't like @click. Any way to ignore these?

wtho · 2017-12-23T15:54:17Z

Just a thought:.
What if the asyncMethod is not promise-based, but e. g. callback-based? I know it is less often and maybe bad style, but it should still be possible to test this code.

eddyerburgh · 2017-12-24T08:47:00Z

docs/en/guides/testing-async-components.md

+</template>
+
+<script>
+  import axios from 'axios'


Could you add a line break after the import statement

eddyerburgh · 2017-12-24T08:48:28Z

docs/en/guides/testing-async-components.md

+  }
+</script>
+```
+A test can be written like this:


Can you add a link to the Jest manual mocks page—https://facebook.github.io/jest/docs/en/manual-mocks.html#content

eddyerburgh · 2017-12-24T08:50:01Z

docs/en/guides/testing-async-components.md

+})
+```
+
+This test currently fails, because the assertion is called before the promise resolves. One solution is to use the npm package, `flush-promises`. which immediately resolve any unresolved promises. This test is also asynchronous, so like the previous example, we need to let the test runner know to wait before making any assertions. 


which immediately resolve any unresolved promises

to

which can be used to flush all pending resolved promise handlers

eddyerburgh · 2017-12-24T08:53:27Z

docs/en/guides/testing-async-components.md

+jest.mock('axios')
+
+test('Foo', () => {
+  it('fetches async when a button is clicked', () => {


You need to make the function async, that's why there's a linting error:
it('fetches async when a button is clicked', () => {

to

it('fetches async when a button is clicked', async () => {

eddyerburgh · 2017-12-24T09:05:52Z

docs/en/guides/testing-async-components.md

+
+This test currently fails, because the assertion is called before the promise resolves. One solution is to use the npm package, `flush-promises`. which immediately resolve any unresolved promises. This test is also asynchronous, so like the previous example, we need to let the test runner know to wait before making any assertions. 
+
+If you are using Jest, there are a few options, such as passing a `done` callback, as shown above. Another is to prepend the test with the ES7 'async' keyword. We can now use the the ES7 `await` keyword with `flushPromises`, to immediately resolve the API call.


such as passing a done callback, as shown above

It isn't shown above. Can you add an example using done. Instead of using flushPromises you can just use a setTimeout:

test('Foo', (done) => { it('fetches async when a button is clicked', () => { const wrapper = shallow(Foo) wrapper.find('button').trigger('click') setTimeout(() => { expect(wrapper.vm.value).toEqual('value') done() }) }) })

(note I haven't tested this code)

We should add a note on why this works, with a link to this blog post—https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/. Basically, the microtask queue, which processes promise callbacks, runs before the task queue, which processes timeout callbacks. So when a setTimeout callback is executed, any resolved promises will have been executed.

eddyerburgh

Looks good, there's just a couple issues to resolve.

Can you test that the examples work, just so we're sure.

lmiller1990 · 2017-12-24T15:03:26Z

Thanks for the feedback @eddyerburgh .

Updates:

Add example using done
Include the option to use $nextTick or setTimeout (both seem fine, I ran the tests. Do you have a preference? I used $nextTick in the example code, but mention both in the explanation.
Include link about why setTimeout works. I didn't know why, that was a really interesting read.
Improve some wording.
Run all tests locally (was doing so anyway, but just to check).

PS merry christmas!

eddyerburgh · 2017-12-24T19:17:33Z

docs/en/guides/testing-async-components.md

+})
+```
+
+The reason `$nextTick` or `setTimeout` allow the test to pass is because the microtask queue where promise callbacks are processed run efore the task queue, where `$nextTick` and `setTimeout` are processed. This means by the time the `$nexTick` and `setTimeout` run, any promise callbacks on the microtask queue will have been executed. See [here](https://jakearchibald.com/2015/tasks-microtasks-queues-and-schedules/) for a more detailed explanation.


small typo — efore

eddyerburgh · 2017-12-24T19:22:07Z

docs/en/guides/testing-async-components.md


-If you are using Jest, there are a few options, such as passing a `done` callback, as shown above. Another is to prepend the test with the ES7 'async' keyword. We can now use the the ES7 `await` keyword with `flushPromises`, to immediately resolve the API call.
+Another solution is to use the npm package, `flush-promises`, which can be used to flush all pending resolved promise handlers, and prepend the test with the ES7 'async' keyword. The ES7 `await` keyword with `flushPromises` can now be used to immediately resolve the API call.


Can we reword this:

Another solution is to use the npm package, flush-promises, which can be used to flush all pending resolved promise handlers, and prepend the test with the ES7 'async' keyword. The ES7 await keyword with flushPromises can now be used to immediately resolve the API call.

To something like this:

Another solution is to use an async function and the npm package flush-promises. flush-promises flushes all pending resolved promise handlers. You can await the call of flushPromises to flush the promises and improve the readability of your test.

lmiller1990 · 2017-12-25T12:42:09Z

Done! Thanks for the feedback.

doun · 2017-12-25T14:39:54Z

@lmiller1990 Would u add an example for catching exceptions:
try{ await a(); expect(CONDITION); await b(); expect(CONDITION); } catch(e){ }
be careful that exception throw by expect() should NOT be caught, or it will pass all tests

lmiller1990 · 2017-12-25T15:24:19Z

@doun the current test shouldn't swallow any exceptions, but throw an error. I haven't experienced what you described, can you link to an example/post some sample code? Or do you mean I should add an example showing how to test if an error was throw from some async code?

I think a small note might be worth including.

doun · 2017-12-25T15:42:48Z

It's not about current sample code.
I just did this days ago, sample code:

test("expect fail", async ()=>{
try{
  var resultA = await TaskA()
  expect(resultA).toBe(true)
  var resultB = await TaskB()
  expect(true).toBe(false)
}
//all exceptions caught, the test will pass
catch(e){
}
})

I wanted to catch only async exceptions, but the test framework(jest) also use exceptions to catch expect failures.

lmiller1990 · 2017-12-25T15:48:21Z

@doun Thanks for the sample. It appears you are just testing regular JavaScript methods, not in the context of a Vue component? Or can you provide the component and some more context? What is TaskA and TaskB?

I'm not sure this belongs here -- of course it is important, but it doesn't feel specific enough to Vue components to include in this particular guide.

One good practise can be to use expect.assertions at the top of your tests - that way, if an error occurs and Jest skips to the catch block, because expect.assertions is not the correct amount, the test will fail.

doun · 2017-12-25T16:07:49Z

No, it’s about async test, not about vue component test. Your idea is awesome, thanks!

…

在 2017年12月25日，下午11:48，Lachlan ***@***.***> 写道： @doun <https://github.com/doun> Thanks for the sample. It appears you are just testing regular JavaScript methods, not Vue component specific ones? Or can you provide the component and some more context? I'm not sure this belongs here -- of course it is important, but it doesn't feel specific enough to Vue components to include. One good practise can be to use expect.assertions at the top of your tests - that way, if an error occurs and Jest skips to the catch block, because expect.assertions is not the correct amount, the test will fail. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#282 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAieRGPvkXmG187Ex2t8QP8xH5qvLCIHks5tD8PHgaJpZM4RIB7x>.

eddyerburgh

Two final edits I'd like you to make, then we can merge 🙂

eddyerburgh · 2017-12-26T07:04:26Z

docs/en/guides/testing-async-components.md

+})
+```
+
+This test currently fails because the assertion is called before the promise in `fetchResults` resolves. Most unit test libraries provide a callback to let the runner know when the test is complete. Jest and Karma both use `done`. We can use `done` in combination with `$nextTick` or `setTimeout` to ensure any promises resolve before the assertion is made. 


Jest and Karma both use

should be

Jest and Mocha both use

eddyerburgh · 2017-12-26T07:05:06Z

docs/en/guides/testing-async-components.md

@@ -0,0 +1,98 @@
+# Testing Asynchronous Behavior
+
+To simplify testing, `vue-test-utils` applies 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.


applies updates synchronously

to

applies DOM updates synchronously

lmiller1990 · 2017-12-26T08:48:06Z

Thanks , I added those changes.

eddyerburgh · 2017-12-26T09:02:18Z

Thanks @lmiller1990 🙂

lmiller1990 · 2017-12-26T11:00:19Z

Thank you @eddyerburgh , the part about how setTimeout and task/microtasks was new to me. OSS is great. I feel like I've learned more doing OS in the last year than like 4 years at school at 2 in the workforce.

Ray-56 · 2018-06-20T05:38:04Z

if
had setTimeout 1500s, expected is error.
how do i handle it?

lmiller1990 · 2018-06-20T09:48:18Z

@guokangf can you post your question on stackoverflow with vue-test-utils tag and the test you trying to write? I can help you there. This repo is just for issues with vue-test-utils.

Thanks.

lmiller1990 added 7 commits December 15, 2017 00:47

Add new guide page

b16c3c2

Add a bit more

c9180e1

Upadte

9e64bcb

Add more explanation

0d2959e

Add examples

b600b8a

Foratting

1a31d96

Foramtting

309aebc

lmiller1990 mentioned this pull request Dec 20, 2017

To do before release #246

Closed

13 tasks

eddyerburgh requested changes Dec 20, 2017

View reviewed changes

callumacrae reviewed Dec 20, 2017

View reviewed changes

LinusBorg reviewed Dec 20, 2017

View reviewed changes

Remove watcher section

34c8a38

Spacing

d675067

lmiller1990 mentioned this pull request Dec 23, 2017

How/what to test when testing vue components vuejs/v2.vuejs.org#1344

Closed

eddyerburgh reviewed Dec 24, 2017

View reviewed changes

eddyerburgh requested changes Dec 24, 2017

View reviewed changes

Make improvements using feedback

7b88e8a

eddyerburgh reviewed Dec 24, 2017

View reviewed changes

Fix type and reword flush-promises explanation

cc8aa0a

lmiller1990 added 2 commits December 25, 2017 22:57

Change from @click to v-on:click

46d7265

Fix linting error

cc47f9f

eddyerburgh requested changes Dec 26, 2017

View reviewed changes

updates -> DOM updates, Jest and Karma -> Jest and Mocha

85e97e3

eddyerburgh approved these changes Dec 26, 2017

View reviewed changes

eddyerburgh merged commit 2819e51 into vuejs:dev Dec 26, 2017


		This test currently fails, because the assertion is called before the promise resolves. One solution is to use the npm package, `flush-promises`. which immediately resolve any unresolved promises. This test is also asynchronous, so like the previous example, we need to let the test runner know to wait before making any assertions.

		If you are using Jest, there are a few options, such as passing a `done` callback, as shown above. Another is to prepend the test with the ES7 'async' keyword. We can now use the the ES7 `await` keyword with `flushPromises`, to immediately resolve the API call.


		If you are using Jest, there are a few options, such as passing a `done` callback, as shown above. Another is to prepend the test with the ES7 'async' keyword. We can now use the the ES7 `await` keyword with `flushPromises`, to immediately resolve the API call.
		Another solution is to use the npm package, `flush-promises`, which can be used to flush all pending resolved promise handlers, and prepend the test with the ES7 'async' keyword. The ES7 `await` keyword with `flushPromises` can now be used to immediately resolve the API call.

		@@ -0,0 +1,98 @@
		# Testing Asynchronous Behavior

		To simplify testing, `vue-test-utils` applies 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.

Add async guide #282

Add async guide #282

Conversation

lmiller1990 commented Dec 20, 2017

eddyerburgh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

callumacrae Dec 20, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmiller1990 Dec 20, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmiller1990 commented Dec 20, 2017

eddyerburgh commented Dec 20, 2017

lmiller1990 commented Dec 21, 2017

eddyerburgh commented Dec 22, 2017

lmiller1990 commented Dec 22, 2017

eddyerburgh commented Dec 22, 2017

lmiller1990 commented Dec 23, 2017

wtho commented Dec 23, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eddyerburgh Dec 24, 2017 • edited

Choose a reason for hiding this comment

eddyerburgh Dec 24, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eddyerburgh left a comment

Choose a reason for hiding this comment

lmiller1990 commented Dec 24, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmiller1990 commented Dec 25, 2017 • edited

doun commented Dec 25, 2017

lmiller1990 commented Dec 25, 2017 • edited

doun commented Dec 25, 2017

lmiller1990 commented Dec 25, 2017 • edited

doun commented Dec 25, 2017 via email

eddyerburgh left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmiller1990 commented Dec 26, 2017 • edited

eddyerburgh commented Dec 26, 2017

lmiller1990 commented Dec 26, 2017

Ray-56 commented Jun 20, 2018 • edited

lmiller1990 commented Jun 20, 2018 • edited

callumacrae Dec 20, 2017 •

edited

lmiller1990 Dec 20, 2017 •

edited

eddyerburgh Dec 24, 2017 •

edited

eddyerburgh Dec 24, 2017 •

edited

lmiller1990 commented Dec 24, 2017 •

edited

lmiller1990 commented Dec 25, 2017 •

edited

lmiller1990 commented Dec 25, 2017 •

edited

lmiller1990 commented Dec 25, 2017 •

edited

lmiller1990 commented Dec 26, 2017 •

edited

Ray-56 commented Jun 20, 2018 •

edited

lmiller1990 commented Jun 20, 2018 •

edited