vue-testing

Vue 3 Testing Patterns

Test framework selection

Layer	Framework
Component, composable, plain TS unit	Vitest + @vue/test-utils (preferred for Vite projects)
Component (alt)	@testing-library/vue (RTL-style API)
Component in browser	Cypress component testing (slower, more realistic)
End-to-end	Playwright (preferred) or Cypress

For Vue 3 + Vite, Vitest is the modern default. Match what's installed.

Vitest setup

vite.config.ts:

import { defineConfig } from 'vitest/config';
import vue from '@vitejs/plugin-vue';
import path from 'path';

export default defineConfig({
  plugins: [vue()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./vitest.setup.ts'],
    coverage: {
      reporter: ['text', 'html'],
      exclude: ['**/*.config.*', '**/*.spec.*', 'src/main.ts'],
    },
  },
  resolve: {
    alias: { '@': path.resolve(__dirname, './src') },
  },
});

vitest.setup.ts:

// Add custom matchers if needed
import { afterEach } from 'vitest';
import { config } from '@vue/test-utils';

afterEach(() => {
  // cleanup mounted components
});

// Stub global components if needed
config.global.stubs = {
  RouterLink: true,
  RouterView: true,
};

Install: pnpm add -D vitest @vue/test-utils @vitejs/plugin-vue jsdom.

mount vs shallowMount

import { mount, shallowMount } from '@vue/test-utils';

// mount renders ALL children real
const wrapper = mount(MyComponent, { props: { name: 'Alice' } });

// shallowMount stubs ALL child components (renders <ChildComponent-stub />)
const wrapper = shallowMount(MyComponent, { props: { name: 'Alice' } });

Prefer mount — catches integration bugs (prop passing, slot rendering). Use shallowMount only for very large component trees where rendering full subtrees is slow.

Component test (basics)

// src/components/UserCard.spec.ts
import { describe, it, expect, vi } from 'vitest';
import { mount } from '@vue/test-utils';
import UserCard from './UserCard.vue';

describe('UserCard', () => {
  it('renders user name and email', () => {
    const wrapper = mount(UserCard, {
      props: { user: { id: '1', name: 'Alice', email: '[email protected]' } },
    });
    expect(wrapper.text()).toContain('Alice');
    expect(wrapper.text()).toContain('[email protected]');
  });

  it('emits "delete" when delete button clicked', async () => {
    const wrapper = mount(UserCard, {
      props: { user: { id: '1', name: 'Alice', email: '[email protected]' } },
    });
    await wrapper.find('[data-testid="delete-btn"]').trigger('click');
    expect(wrapper.emitted('delete')).toEqual([['1']]);
  });

  it('renders header slot when provided', () => {
    const wrapper = mount(UserCard, {
      props: { user: { id: '1', name: 'Alice', email: '[email protected]' } },
      slots: { header: '<h2>Custom Header</h2>' },
    });
    expect(wrapper.find('h2').text()).toBe('Custom Header');
  });
});