1---
2title: Use flushPromises for Testing Async Components
3impact: HIGH
4impactDescription: Without awaiting async operations, tests make assertions before the component has rendered, causing false negatives
5type: gotcha
6tags: [vue3, testing, async, defineAsyncComponent, flushPromises, vitest]
7---
8 
9# Use flushPromises for Testing Async Components
10 
11**Impact: HIGH** - When testing async components created with `defineAsyncComponent`, you must use `await flushPromises()` to ensure the component has loaded before making assertions. Vue updates asynchronously, so tests that don't account for this will make assertions before the component has rendered.
12 
13## Task Checklist
14 
15- [ ] Use `async/await` in test functions for async components
16- [ ] Call `await flushPromises()` after mounting async components
17- [ ] Test loading states by making assertions before `flushPromises()`
18- [ ] Test error states using rejected promises in `defineAsyncComponent`
19- [ ] Use `trigger()` with `await` as it returns a Promise
20 
21**Incorrect:**
22 
23```javascript
24import { mount } from '@vue/test-utils'
25import { defineAsyncComponent } from 'vue'
26 
27const AsyncWidget = defineAsyncComponent(() =>
28  import('./Widget.vue')
29)
30 
31test('renders async component', () => {
32  const wrapper = mount(AsyncWidget)
33 
34  // FAILS: Component hasn't loaded yet
35  expect(wrapper.text()).toContain('Widget Content')
36})
37```
38 
39**Correct:**
40 
41```javascript
42import { mount, flushPromises } from '@vue/test-utils'
43import { defineAsyncComponent, nextTick } from 'vue'
44 
45const AsyncWidget = defineAsyncComponent(() =>
46  import('./Widget.vue')
47)
48 
49test('renders async component', async () => {
50  const wrapper = mount(AsyncWidget)
51 
52  // Wait for async component to load
53  await flushPromises()
54 
55  expect(wrapper.text()).toContain('Widget Content')
56})
57 
58test('shows loading state initially', async () => {
59  const AsyncWithLoading = defineAsyncComponent({
60    loader: () => import('./Widget.vue'),
61    loadingComponent: { template: '<div>Loading...</div>' },
62    delay: 0
63  })
64 
65  const wrapper = mount(AsyncWithLoading)
66 
67  // Check loading state immediately
68  expect(wrapper.text()).toContain('Loading...')
69 
70  // Wait for component to load
71  await flushPromises()
72 
73  // Check final state
74  expect(wrapper.text()).toContain('Widget Content')
75})
76```
77 
78## Testing with Suspense
79 
80```javascript
81import { mount, flushPromises } from '@vue/test-utils'
82import { Suspense, defineAsyncComponent, h } from 'vue'
83 
84const AsyncWidget = defineAsyncComponent(() =>
85  import('./Widget.vue')
86)
87 
88test('renders async component with Suspense', async () => {
89  const wrapper = mount({
90    components: { AsyncWidget },
91    template: `
92      <Suspense>
93        <AsyncWidget />
94        <template #fallback>
95          <div>Loading...</div>
96        </template>
97      </Suspense>
98    `
99  })
100 
101  // Initially shows fallback
102  expect(wrapper.text()).toContain('Loading...')
103 
104  // Wait for async resolution
105  await flushPromises()
106 
107  // Now shows actual content
108  expect(wrapper.text()).toContain('Widget Content')
109})
110```
111 
112## Testing Error States
113 
114```javascript
115import { mount, flushPromises } from '@vue/test-utils'
116import { defineAsyncComponent } from 'vue'
117 
118test('shows error component on load failure', async () => {
119  const AsyncWithError = defineAsyncComponent({
120    loader: () => Promise.reject(new Error('Failed to load')),
121    errorComponent: { template: '<div>Error loading component</div>' }
122  })
123 
124  const wrapper = mount(AsyncWithError)
125 
126  await flushPromises()
127 
128  expect(wrapper.text()).toContain('Error loading component')
129})
130```
131 
132## Utilities Reference
133 
134| Utility | Purpose |
135|---------|---------|
136| `await flushPromises()` | Resolves all pending promises |
137| `await nextTick()` | Waits for Vue's next DOM update cycle |
138| `await wrapper.trigger('click')` | Triggers event and waits for update |
139 
140## Dynamic Import Handling
141 
142**Note:** Dynamic imports (`import('./File.vue')`) may require additional handling beyond `flushPromises()` in test environments. Test runners like Vitest handle module resolution differently than runtime bundlers, which can cause timing issues with dynamic imports. If `flushPromises()` alone doesn't resolve the component, consider:
143 
144- Mocking the dynamic import to return the component synchronously
145- Using multiple `await flushPromises()` calls in sequence
146- Wrapping assertions in `waitFor()` or retry utilities
147- Configuring your test runner's module resolution settings
148 
149```javascript
150// If flushPromises() isn't sufficient, mock the import
151vi.mock('./Widget.vue', () => ({
152  default: { template: '<div>Widget Content</div>' }
153}))
154 
155// Or use multiple flush calls for nested async operations
156await flushPromises()
157await flushPromises()
158```
159 
160## References
161 
162- [Vue Test Utils - Asynchronous Behavior](https://test-utils.vuejs.org/guide/advanced/async-suspense)
163- [Vue.js Async Components Documentation](https://vuejs.org/guide/components/async)
164