1---
2title: Wrap Async Setup Components in Suspense for Testing
3impact: HIGH
4impactDescription: Components with async setup() fail to render in tests without Suspense wrapper, causing cryptic errors
5type: gotcha
6tags: [vue3, testing, suspense, async-setup, vue-test-utils, vitest]
7---
8 
9# Wrap Async Setup Components in Suspense for Testing
10 
11**Impact: HIGH** - Components using `async setup()` require a `<Suspense>` wrapper to function correctly. Testing them without Suspense causes the component to never render, leading to test failures and confusing errors.
12 
13Create a test wrapper component with Suspense or use a `mountSuspense` helper function for testing async components.
14 
15## Task Checklist
16 
17- [ ] Identify components with async setup (uses `await` in `<script setup>` or `async setup()`)
18- [ ] Create a wrapper component with `<Suspense>` for testing
19- [ ] Use `flushPromises()` after mounting to wait for async resolution
20- [ ] Access the actual component via `findComponent()` for assertions
21- [ ] Consider using `@testing-library/vue` with caution (has Suspense issues)
22 
23**Incorrect:**
24```javascript
25import { mount } from '@vue/test-utils'
26import AsyncUserProfile from './AsyncUserProfile.vue'
27 
28// BAD: Async component without Suspense wrapper
29test('displays user data', async () => {
30  // This won't render - Vue expects Suspense wrapper for async setup
31  const wrapper = mount(AsyncUserProfile, {
32    props: { userId: 1 }
33  })
34 
35  await flushPromises()
36 
37  // This fails - component never rendered
38  expect(wrapper.find('.username').text()).toBe('John')
39})
40```
41 
42**Correct - Manual Wrapper Component:**
43```javascript
44import { mount, flushPromises } from '@vue/test-utils'
45import { defineComponent, Suspense } from 'vue'
46import AsyncUserProfile from './AsyncUserProfile.vue'
47 
48test('displays user data', async () => {
49  // Create wrapper component with Suspense
50  const TestWrapper = defineComponent({
51    components: { AsyncUserProfile },
52    template: `
53      <Suspense>
54        <AsyncUserProfile :user-id="1" />
55        <template #fallback>Loading...</template>
56      </Suspense>
57    `
58  })
59 
60  const wrapper = mount(TestWrapper)
61 
62  // Initially shows fallback
63  expect(wrapper.text()).toContain('Loading...')
64 
65  // Wait for async setup to complete
66  await flushPromises()
67 
68  // Find the actual component for detailed assertions
69  const profile = wrapper.findComponent(AsyncUserProfile)
70  expect(profile.find('.username').text()).toBe('John')
71})
72```
73 
74**Correct - Reusable Helper Function:**
75```javascript
76// test-utils.js
77import { mount, flushPromises } from '@vue/test-utils'
78import { defineComponent, Suspense, h } from 'vue'
79 
80export async function mountSuspense(component, options = {}) {
81  const { props, slots, ...mountOptions } = options
82 
83  const wrapper = mount(
84    defineComponent({
85      render() {
86        return h(
87          Suspense,
88          null,
89          {
90            default: () => h(component, props, slots),
91            fallback: () => h('div', 'Loading...')
92          }
93        )
94      }
95    }),
96    mountOptions
97  )
98 
99  // Wait for async component to resolve
100  await flushPromises()
101 
102  return {
103    wrapper,
104    // Provide easy access to the actual component
105    component: wrapper.findComponent(component)
106  }
107}
108```
109 
110```javascript
111// AsyncUserProfile.test.js
112import { mountSuspense } from './test-utils'
113import AsyncUserProfile from './AsyncUserProfile.vue'
114 
115test('displays user data', async () => {
116  const { component } = await mountSuspense(AsyncUserProfile, {
117    props: { userId: 1 },
118    global: {
119      stubs: {
120        // Stub any child components if needed
121      }
122    }
123  })
124 
125  expect(component.find('.username').text()).toBe('John')
126})
127 
128test('handles errors gracefully', async () => {
129  const { component } = await mountSuspense(AsyncUserProfile, {
130    props: { userId: 'invalid' }
131  })
132 
133  expect(component.find('.error').exists()).toBe(true)
134})
135```
136 
137## Testing with onErrorCaptured
138 
139```javascript
140import { mount, flushPromises } from '@vue/test-utils'
141import { defineComponent, Suspense, h, ref, onErrorCaptured } from 'vue'
142import AsyncComponent from './AsyncComponent.vue'
143 
144test('catches async errors', async () => {
145  const capturedError = ref(null)
146 
147  const TestWrapper = defineComponent({
148    setup() {
149      onErrorCaptured((error) => {
150        capturedError.value = error
151        return true // Prevent error propagation
152      })
153      return { capturedError }
154    },
155    render() {
156      return h(Suspense, null, {
157        default: () => h(AsyncComponent, { shouldFail: true }),
158        fallback: () => h('div', 'Loading...')
159      })
160    }
161  })
162 
163  const wrapper = mount(TestWrapper)
164  await flushPromises()
165 
166  expect(capturedError.value).toBeTruthy()
167  expect(capturedError.value.message).toContain('Failed to load')
168})
169```
170 
171## Using with Nuxt's mountSuspended
172 
173```javascript
174// If using Nuxt, use the built-in mountSuspended helper
175import { mountSuspended } from '@nuxt/test-utils/runtime'
176import AsyncPage from './AsyncPage.vue'
177 
178test('renders async page', async () => {
179  const wrapper = await mountSuspended(AsyncPage, {
180    props: { id: 1 }
181  })
182 
183  expect(wrapper.find('h1').text()).toBe('Page Title')
184})
185```
186 
187## Important Caveats
188 
189### @testing-library/vue Limitation
190```javascript
191// CAUTION: @testing-library/vue has issues with Suspense
192// Use @vue/test-utils for async components instead
193 
194// If you must use Testing Library, create manual wrapper:
195import { render, waitFor } from '@testing-library/vue'
196 
197test('async component with testing library', async () => {
198  const TestWrapper = {
199    template: `
200      <Suspense>
201        <AsyncComponent />
202      </Suspense>
203    `,
204    components: { AsyncComponent }
205  }
206 
207  const { getByText } = render(TestWrapper)
208 
209  await waitFor(() => {
210    expect(getByText('Loaded content')).toBeInTheDocument()
211  })
212})
213```
214 
215### Accessing Component Instance
216```javascript
217test('access vm on async component', async () => {
218  const { wrapper, component } = await mountSuspense(AsyncComponent)
219 
220  // The wrapper.vm is the Suspense wrapper - not useful
221  // Use component.vm for the actual async component
222  expect(component.vm.someData).toBe('value')
223})
224```
225 
226## Reference
227- [Vue Test Utils - Async Suspense](https://test-utils.vuejs.org/guide/advanced/async-suspense)
228- [Vue.js Suspense Documentation](https://vuejs.org/guide/built-ins/suspense.html)
229- [Testing Library Vue Suspense Issue](https://github.com/testing-library/vue-testing-library/issues/230)
230