1---
2title: Properly Handle Async Updates with nextTick and flushPromises
3impact: HIGH
4impactDescription: Race conditions and flaky tests occur when async DOM updates or API calls complete after assertions run
5type: gotcha
6tags: [vue3, testing, async, flushPromises, nextTick, vitest, vue-test-utils, race-condition]
7---
8 
9# Properly Handle Async Updates with nextTick and flushPromises
10 
11**Impact: HIGH** - Vue updates the DOM asynchronously. Without properly awaiting these updates, tests may assert against stale DOM state, causing intermittent failures and false negatives.
12 
13Use `await` with triggers and `setValue`, use `nextTick` for reactive updates, and use `flushPromises` for external async operations like API calls.
14 
15## Task Checklist
16 
17- [ ] Always await `trigger()` and `setValue()` calls
18- [ ] Use `await nextTick()` after programmatic reactive state changes
19- [ ] Use `await flushPromises()` for external async operations (API calls, timers)
20- [ ] Don't chain multiple `nextTick` calls - use `flushPromises` instead
21- [ ] Consider using `waitFor` from testing-library for polling assertions
22 
23**Incorrect:**
24```javascript
25import { mount } from '@vue/test-utils'
26import SearchComponent from './SearchComponent.vue'
27 
28// BAD: Not awaiting trigger - assertion runs before DOM updates
29test('search filters results', () => {
30  const wrapper = mount(SearchComponent)
31 
32  wrapper.find('input').setValue('vue')  // Missing await!
33  wrapper.find('button').trigger('click')  // Missing await!
34 
35  // This assertion likely fails - DOM hasn't updated yet
36  expect(wrapper.findAll('.result').length).toBe(3)
37})
38 
39// BAD: Using nextTick for API calls
40test('loads data from API', async () => {
41  const wrapper = mount(DataLoader)
42 
43  await nextTick()  // This won't wait for the API call!
44 
45  // Assertion runs before fetch completes
46  expect(wrapper.find('.data').text()).toBe('Loaded data')
47})
48```
49 
50**Correct:**
51```javascript
52import { mount, flushPromises } from '@vue/test-utils'
53import { nextTick } from 'vue'
54import SearchComponent from './SearchComponent.vue'
55import DataLoader from './DataLoader.vue'
56 
57// CORRECT: Await trigger and setValue
58test('search filters results', async () => {
59  const wrapper = mount(SearchComponent)
60 
61  await wrapper.find('input').setValue('vue')
62  await wrapper.find('button').trigger('click')
63 
64  expect(wrapper.findAll('.result').length).toBe(3)
65})
66 
67// CORRECT: Use flushPromises for API calls
68test('loads data from API', async () => {
69  const wrapper = mount(DataLoader)
70 
71  // Wait for all pending promises to resolve
72  await flushPromises()
73 
74  expect(wrapper.find('.data').text()).toBe('Loaded data')
75})
76```
77 
78## When to Use Each Method
79 
80### `await trigger()` / `await setValue()` - User Interactions
81```javascript
82// These methods return nextTick internally
83await wrapper.find('button').trigger('click')
84await wrapper.find('input').setValue('new value')
85await wrapper.find('form').trigger('submit')
86```
87 
88### `await nextTick()` - Programmatic Reactive Updates
89```javascript
90import { nextTick } from 'vue'
91 
92test('reflects programmatic state changes', async () => {
93  const wrapper = mount(Counter)
94 
95  // Direct state modification (when testing with exposed internals)
96  wrapper.vm.count = 5
97 
98  await nextTick()  // Wait for Vue to update DOM
99 
100  expect(wrapper.find('.count').text()).toBe('5')
101})
102```
103 
104### `await flushPromises()` - External Async Operations
105```javascript
106import { flushPromises } from '@vue/test-utils'
107 
108test('displays fetched data', async () => {
109  const wrapper = mount(UserProfile, {
110    props: { userId: 1 }
111  })
112 
113  // Wait for component's API call to complete
114  await flushPromises()
115 
116  expect(wrapper.find('.username').text()).toBe('John')
117})
118 
119// Sometimes you need multiple flushPromises for chained async operations
120test('processes data after fetch', async () => {
121  const wrapper = mount(DataProcessor)
122 
123  await flushPromises()  // Wait for fetch
124  await flushPromises()  // Wait for processing triggered by fetch
125 
126  expect(wrapper.find('.processed').exists()).toBe(true)
127})
128```
129 
130## Common Pattern: Combining Methods
131```javascript
132test('submits form and shows success', async () => {
133  const wrapper = mount(ContactForm)
134 
135  // Fill form (awaiting each interaction)
136  await wrapper.find('#name').setValue('John')
137  await wrapper.find('#email').setValue('[email protected]')
138 
139  // Submit form
140  await wrapper.find('form').trigger('submit')
141 
142  // Wait for API submission to complete
143  await flushPromises()
144 
145  // Assert success state
146  expect(wrapper.find('.success-message').exists()).toBe(true)
147})
148```
149 
150## Testing with MSW or Mock APIs
151```javascript
152import { flushPromises } from '@vue/test-utils'
153import { rest } from 'msw'
154import { setupServer } from 'msw/node'
155 
156const server = setupServer(
157  rest.get('/api/user', (req, res, ctx) => {
158    return res(ctx.json({ name: 'John' }))
159  })
160)
161 
162test('displays user data', async () => {
163  const wrapper = mount(UserCard)
164 
165  // MSW might require multiple flushPromises
166  await flushPromises()
167  await flushPromises()
168 
169  expect(wrapper.find('.name').text()).toBe('John')
170})
171```
172 
173## Reference
174- [Vue Test Utils - Asynchronous Behavior](https://test-utils.vuejs.org/guide/advanced/async-suspense)
175- [Vue.js Testing Guide](https://vuejs.org/guide/scaling-up/testing)
176