1# Vue Testing
2 
3Test patterns for Vue 3 components, composables, and utilities.
4 
5## Quick Reference
6 
7| Test Type        | Pattern                              |
8| ---------------- | ------------------------------------ |
9| Component        | `mount(Component, { props, slots })` |
10| User interaction | `await wrapper.trigger('click')`     |
11| Emitted events   | `wrapper.emitted('update')`          |
12| Composable       | Call directly, test return values    |
13| Utils            | Pure function testing (easiest)      |
14 
15## Stack
16 
17- **Vitest** - test runner
18- **@vue/test-utils** - component mounting, interaction
19- **@testing-library/vue** - user-centric alternative
20- **happy-dom / jsdom** - DOM environment
21 
22## File Location
23 
24Colocate tests with code:
25 
26```
27Button.vue → Button.spec.ts
28useAuth.ts → useAuth.spec.ts
29formatters.ts → formatters.spec.ts
30```
31 
32## Component Tests
33 
34### Basic
35 
36```ts
37import { mount } from '@vue/test-utils'
38import Button from './Button.vue'
39 
40it('renders slot', () => {
41  const wrapper = mount(Button, {
42    slots: { default: 'Click me' }
43  })
44  expect(wrapper.text()).toBe('Click me')
45})
46 
47it('emits on click', async () => {
48  const wrapper = mount(Button)
49  await wrapper.trigger('click')
50  expect(wrapper.emitted('click')).toHaveLength(1)
51})
52```
53 
54### Props
55 
56```ts
57it('applies variant class', () => {
58  const wrapper = mount(Button, {
59    props: { variant: 'primary' }
60  })
61  expect(wrapper.classes()).toContain('btn-primary')
62})
63```
64 
65### Emits
66 
67```ts
68it('emits update with payload', async () => {
69  const wrapper = mount(Input)
70  await wrapper.find('input').setValue('new value')
71  expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['new value'])
72})
73```
74 
75### Slots
76 
77```ts
78it('renders named slots', () => {
79  const wrapper = mount(Card, {
80    slots: {
81      header: '<h1>Title</h1>',
82      default: '<p>Content</p>'
83    }
84  })
85  expect(wrapper.html()).toContain('<h1>Title</h1>')
86})
87```
88 
89## Composable Tests
90 
91Call directly, no mounting needed:
92 
93```ts
94import { useCounter } from './useCounter'
95 
96it('increments count', () => {
97  const { count, increment } = useCounter(0)
98  expect(count.value).toBe(0)
99  increment()
100  expect(count.value).toBe(1)
101})
102 
103it('resets to initial', () => {
104  const { count, increment, reset } = useCounter(5)
105  increment()
106  increment()
107  expect(count.value).toBe(7)
108  reset()
109  expect(count.value).toBe(5)
110})
111```
112 
113## Utils Tests
114 
115Easiest - pure functions:
116 
117```ts
118import { formatCurrency, slugify } from './formatters'
119 
120describe('formatCurrency', () => {
121  it('formats USD', () => {
122    expect(formatCurrency(10.5)).toBe('$10.50')
123  })
124})
125 
126describe('slugify', () => {
127  it('converts to lowercase', () => {
128    expect(slugify('Hello World')).toBe('hello-world')
129  })
130 
131  it('removes special chars', () => {
132    expect(slugify('Hello! World?')).toBe('hello-world')
133  })
134})
135```
136 
137## Mocking
138 
139**Composables:**
140 
141```ts
142import { vi } from 'vitest'
143 
144vi.mock('./useAuth', () => ({
145  useAuth: vi.fn(() => ({
146    user: { id: 1, name: 'Test' },
147    isAuthenticated: true
148  }))
149}))
150```
151 
152**API calls:**
153 
154```ts
155global.fetch = vi.fn(() =>
156  Promise.resolve({
157    json: () => Promise.resolve({ data: [] })
158  })
159)
160```
161 
162## Router Mocking
163 
164Mock `useRoute` and `useRouter` for component tests:
165 
166```ts
167import { vi } from 'vitest'
168import { mount } from '@vue/test-utils'
169 
170vi.mock('vue-router', () => ({
171  useRoute: vi.fn(() => ({
172    params: { id: '123' },
173    query: { filter: 'active' },
174    path: '/users/123',
175  })),
176  useRouter: vi.fn(() => ({
177    push: vi.fn(),
178    replace: vi.fn(),
179  })),
180}))
181 
182it('uses route params', () => {
183  const wrapper = mount(UserPage)
184  expect(wrapper.text()).toContain('123')
185})
186```
187 
188**Dynamic route mocking per test:**
189 
190```ts
191import { useRoute } from 'vue-router'
192 
193it('handles different routes', () => {
194  vi.mocked(useRoute).mockReturnValue({
195    params: { id: '456' },
196  } as any)
197 
198  const wrapper = mount(UserPage)
199  expect(wrapper.text()).toContain('456')
200})
201```
202 
203## Suspense and Teleport
204 
205**Testing async components with Suspense:**
206 
207```ts
208import { flushPromises, mount } from '@vue/test-utils'
209 
210it('renders async content', async () => {
211  const wrapper = mount(AsyncComponent, {
212    global: {
213      stubs: { Suspense: false }, // Don't stub Suspense
214    },
215  })
216 
217  // Wait for async setup to complete
218  await flushPromises()
219 
220  expect(wrapper.text()).toContain('Loaded content')
221})
222```
223 
224**Testing Teleport:**
225 
226```ts
227it('teleports modal content', () => {
228  const wrapper = mount(Modal, {
229    global: {
230      stubs: {
231        teleport: true, // Stub teleport to render inline
232      },
233    },
234  })
235 
236  expect(wrapper.text()).toContain('Modal content')
237})
238```
239 
240**Access teleported content:**
241 
242```ts
243it('finds teleported content', () => {
244  document.body.innerHTML = '<div id="modal-target"></div>'
245 
246  mount(Modal, { props: { open: true } })
247 
248  // Content teleports to #modal-target
249  expect(document.body.innerHTML).toContain('Modal content')
250})
251```
252 
253## Best Practices
254 
255**Do:**
256 
257- Test behavior (what user sees/does), not implementation
258- Arrange-Act-Assert structure
259- One assertion per test
260- Descriptive test names
261- Mock external dependencies
262 
263**Don't:**
264 
265- Test Vue internals (reactivity)
266- Test third-party libraries
267- Test trivial getters/setters
268- Test implementation details
269 
270## What to Test
271 
272**Test:**
273 
274- User interactions (clicks, inputs)
275- Conditional rendering
276- Props validation, emitted events
277- Computed values, business logic
278 
279**Skip:**
280 
281- Vue internals, third-party libs
282- Trivial getters/setters
283- Implementation details
284 
285## Running
286 
287```bash
288pnpm test                          # all
289pnpm exec vitest Button.spec.ts   # specific
290pnpm exec vitest --watch           # watch
291pnpm test --coverage               # coverage
292```
293 
294**Docs:** [vitest.dev](https://vitest.dev/) · [test-utils.vuejs.org](https://test-utils.vuejs.org/)
295