1---
2title: Use Vitest for Vue 3 Testing - Recommended by Vue Team
3impact: MEDIUM
4impactDescription: Using Jest or other runners with Vite projects requires complex configuration and causes slower test runs
5type: best-practice
6tags: [vue3, testing, vitest, vite, configuration, setup]
7---
8 
9# Use Vitest for Vue 3 Testing - Recommended by Vue Team
10 
11**Impact: MEDIUM** - Vitest is created and maintained by Vue/Vite team members and shares the same configuration and transform pipeline as Vite. Using Jest or other test runners with Vite-based projects requires additional configuration and can result in slower test execution and compatibility issues.
12 
13Use Vitest for new Vue 3 projects. Only consider Jest if migrating an existing test suite.
14 
15## Task Checklist
16 
17- [ ] Install Vitest and related packages for Vue testing
18- [ ] Configure vitest in vite.config.js or vitest.config.js
19- [ ] Set up proper test environment (happy-dom or jsdom)
20- [ ] Add test scripts to package.json
21- [ ] Configure globals if desired for cleaner test syntax
22- [ ] Use @vue/test-utils for component mounting
23 
24## Quick Setup
25 
26```bash
27# Install required packages
28npm install -D vitest @vue/test-utils happy-dom
29# or with jsdom
30npm install -D vitest @vue/test-utils jsdom
31```
32 
33**vite.config.js:**
34```javascript
35import { defineConfig } from 'vite'
36import vue from '@vitejs/plugin-vue'
37 
38export default defineConfig({
39  plugins: [vue()],
40  test: {
41    // Enable global test APIs (describe, it, expect)
42    globals: true,
43    // Use happy-dom for faster tests (or 'jsdom' for better compatibility)
44    environment: 'happy-dom',
45    // Optional: Setup files for global configuration
46    setupFiles: ['./src/test/setup.js']
47  }
48})
49```
50 
51**package.json:**
52```json
53{
54  "scripts": {
55    "test": "vitest",
56    "test:run": "vitest run",
57    "test:coverage": "vitest run --coverage"
58  }
59}
60```
61 
62**tsconfig.json (if using TypeScript):**
63```json
64{
65  "compilerOptions": {
66    "types": ["vitest/globals"]
67  }
68}
69```
70 
71## Test File Example
72 
73```javascript
74// src/components/Counter.test.js
75import { describe, it, expect, beforeEach } from 'vitest'  // optional with globals: true
76import { mount } from '@vue/test-utils'
77import Counter from './Counter.vue'
78 
79describe('Counter', () => {
80  let wrapper
81 
82  beforeEach(() => {
83    wrapper = mount(Counter)
84  })
85 
86  it('renders initial count', () => {
87    expect(wrapper.find('[data-testid="count"]').text()).toBe('0')
88  })
89 
90  it('increments when button clicked', async () => {
91    await wrapper.find('[data-testid="increment"]').trigger('click')
92    expect(wrapper.find('[data-testid="count"]').text()).toBe('1')
93  })
94})
95```
96 
97## Vitest vs Jest Comparison
98 
99| Feature | Vitest | Jest |
100|---------|--------|------|
101| Vite Integration | Native | Requires config |
102| Speed | Very fast (ESM native) | Slower with Vite |
103| Watch Mode | Excellent | Good |
104| Vue SFC Support | Works with Vite | Needs vue-jest |
105| Config Sharing | Same as vite.config | Separate |
106| API | Jest-compatible | Standard |
107 
108## Using with Testing Library
109 
110```bash
111npm install -D @testing-library/vue @testing-library/jest-dom
112```
113 
114```javascript
115// src/test/setup.js
116import { expect } from 'vitest'
117import * as matchers from '@testing-library/jest-dom/matchers'
118 
119expect.extend(matchers)
120```
121 
122```javascript
123// Component.test.js
124import { render, screen, fireEvent } from '@testing-library/vue'
125import UserCard from './UserCard.vue'
126 
127test('displays user name', () => {
128  render(UserCard, {
129    props: { name: 'John Doe' }
130  })
131 
132  expect(screen.getByText('John Doe')).toBeInTheDocument()
133})
134```
135 
136## Advanced Configuration
137 
138```javascript
139// vitest.config.js (separate file if preferred)
140import { defineConfig } from 'vitest/config'
141import vue from '@vitejs/plugin-vue'
142 
143export default defineConfig({
144  plugins: [vue()],
145  test: {
146    globals: true,
147    environment: 'happy-dom',
148    include: ['**/*.{test,spec}.{js,ts,jsx,tsx}'],
149    exclude: ['node_modules', 'dist', 'e2e'],
150    coverage: {
151      provider: 'v8',
152      reporter: ['text', 'json', 'html'],
153      exclude: ['node_modules', 'test']
154    },
155    // Helpful for debugging
156    reporters: ['verbose'],
157    // Run tests in sequence in CI
158    poolOptions: {
159      threads: {
160        singleThread: process.env.CI === 'true'
161      }
162    }
163  }
164})
165```
166 
167## Common Patterns
168 
169### Mocking Modules
170```javascript
171import { vi } from 'vitest'
172 
173vi.mock('@/api/users', () => ({
174  fetchUser: vi.fn().mockResolvedValue({ name: 'John' })
175}))
176```
177 
178### Testing with Fake Timers
179```javascript
180import { vi, beforeEach, afterEach } from 'vitest'
181 
182beforeEach(() => {
183  vi.useFakeTimers()
184})
185 
186afterEach(() => {
187  vi.restoreAllMocks()
188})
189 
190test('debounced search', async () => {
191  const wrapper = mount(SearchBox)
192  await wrapper.find('input').setValue('vue')
193 
194  vi.advanceTimersByTime(300)
195  await flushPromises()
196 
197  expect(wrapper.emitted('search')).toBeTruthy()
198})
199```
200 
201## Reference
202- [Vitest Documentation](https://vitest.dev/)
203- [Vue.js Testing Guide](https://vuejs.org/guide/scaling-up/testing)
204- [Vue Test Utils](https://test-utils.vuejs.org/)
205