Vitest 测试实战：现代前端单元测试的最佳实践

1
export function add(a: number, b: number): number {
2
  return a + b;
3
}
4

5
export function divide(a: number, b: number): number {
6
  if (b === 0) throw new Error('Division by zero');
7
  return a / b;
8
}
9

10
export function clamp(value: number, min: number, max: number): number {
11
  return Math.min(Math.max(value, min), max);
12
}
13

14
export function isEven(n: number): boolean {
15
  return n % 2 === 0;
16
}

1
import { describe, it, expect } from 'vitest';
2
import { add, divide, clamp, isEven } from './math';
3

4
describe('math utils', () => {
5
  describe('add', () => {
6
    it('should add two positive numbers', () => {
7
      expect(add(1, 2)).toBe(3);
8
    });
9

10
    it('should handle negative numbers', () => {
11
      expect(add(-1, -2)).toBe(-3);
12
      expect(add(-1, 2)).toBe(1);
13
    });
14

15
    it('should handle floating point', () => {
16
      // 注意浮点精度
17
      expect(add(0.1, 0.2)).toBeCloseTo(0.3, 10);
18
    });
19
  });
20

21
  describe('divide', () => {
22
    it('should divide two numbers', () => {
23
      expect(divide(10, 2)).toBe(5);
24
    });
25

26
    it('should throw on division by zero', () => {
27
      expect(() => divide(10, 0)).toThrowError('Division by zero');
28
    });
29

30
    // 使用 each 进行参数化测试
31
    it.each([
32
      [10, 2, 5],
33
      [9, 3, 3],
34
      [100, 10, 10],
35
      [7, 2, 3.5],
36
    ])('divide(%i, %i) = %f', (a, b, expected) => {
37
      expect(divide(a, b)).toBe(expected);
38
    });
39
  });
40

41
  describe('clamp', () => {
42
    it('should return value when within range', () => {
43
      expect(clamp(5, 0, 10)).toBe(5);
44
    });
45

46
    it('should clamp to min', () => {
47
      expect(clamp(-5, 0, 10)).toBe(0);
48
    });
49

50
    it('should clamp to max', () => {
51
      expect(clamp(15, 0, 10)).toBe(10);
52
    });
53
  });
54
});

1
export interface User {
2
  id: number;
3
  name: string;
4
  email: string;
5
}
6

7
export async function fetchUser(id: number): Promise<User> {
8
  const response = await fetch(`/api/users/${id}`);
9
  if (!response.ok) {
10
    throw new Error(`User not found: ${id}`);
11
  }
12
  return response.json();
13
}
14

15
export function fetchUserWithCallback(
16
  id: number,
17
  callback: (err: Error | null, user?: User) => void
18
): void {
19
  fetch(`/api/users/${id}`)
20
    .then(res => {
21
      if (!res.ok) throw new Error(`User not found: ${id}`);
22
      return res.json();
23
    })
24
    .then(user => callback(null, user))
25
    .catch(err => callback(err));
26
}

1
import { describe, it, expect, vi, beforeEach } from 'vitest';
2
import { fetchUser } from './user';
3

4
// Mock fetch
5
const mockFetch = vi.fn();
6
vi.stubGlobal('fetch', mockFetch);
7

8
describe('fetchUser', () => {
9
  beforeEach(() => {
10
    mockFetch.mockReset();
11
  });
12

13
  it('should fetch user successfully', async () => {
14
    const mockUser = { id: 1, name: 'Alice', email: 'alice@example.com' };
15
    mockFetch.mockResolvedValueOnce({
16
      ok: true,
17
      json: () => Promise.resolve(mockUser),
18
    });
19

20
    const user = await fetchUser(1);
21

22
    expect(user).toEqual(mockUser);
23
    expect(mockFetch).toHaveBeenCalledWith('/api/users/1');
24
  });
25

26
  it('should throw on non-ok response', async () => {
27
    mockFetch.mockResolvedValueOnce({ ok: false, status: 404 });
28

29
    await expect(fetchUser(999)).rejects.toThrowError('User not found: 999');
30
  });
31

32
  it('should handle network errors', async () => {
33
    mockFetch.mockRejectedValueOnce(new TypeError('Network error'));
34

35
    await expect(fetchUser(1)).rejects.toThrowError('Network error');
36
  });
37
});

1
export interface FormattedOutput {
2
  title: string;
3
  body: string;
4
  meta: Record<string, string>;
5
}
6

7
export function formatArticle(raw: string, author: string): FormattedOutput {
8
  const lines = raw.trim().split('\n');
9
  const title = lines[0].replace(/^#\s*/, '');
10
  const body = lines.slice(1).join('\n').trim();
11

12
  return {
13
    title,
14
    body,
15
    meta: {
16
      author,
17
      wordCount: String(body.length),
18
      createdAt: new Date().toISOString().split('T')[0],
19
    },
20
  };
21
}

1
import { describe, it, expect, vi } from 'vitest';
2
import { formatArticle } from './formatter';
3

4
describe('formatArticle', () => {
5
  // 冻结时间以确保快照稳定
6
  beforeEach(() => {
7
    vi.useFakeTimers();
8
    vi.setSystemTime(new Date('2026-04-05'));
9
  });
10

11
  afterEach(() => {
12
    vi.useRealTimers();
13
  });
14

15
  it('should format article correctly', () => {
16
    const raw = `# Hello World
17
This is the body of the article.
18
It has multiple lines.`;
19

20
    // 内联快照 - 直接写在测试文件中
21
    expect(formatArticle(raw, 'Alice')).toMatchInlineSnapshot(`
22
      {
23
        "body": "This is the body of the article.
24
      It has multiple lines.",
25
        "meta": {
26
          "author": "Alice",
27
          "createdAt": "2026-04-05",
28
          "wordCount": "50",
29
        },
30
        "title": "Hello World",
31
      }
32
    `);
33
  });
34

35
  it('should match file snapshot', () => {
36
    const raw = `# Test
37
Body content`;
38

39
    // 文件快照 - 保存到 __snapshots__ 目录
40
    expect(formatArticle(raw, 'Bob')).toMatchSnapshot();
41
  });
42
});

1
import { expect } from 'vitest';
2

3
// 自定义快照序列化器 - 隐藏动态字段
4
expect.addSnapshotSerializer({
5
  serialize(val: any, config, indentation, depth, refs, printer) {
6
    // 将日期字符串替换为占位符
7
    const sanitized = JSON.parse(JSON.stringify(val, (key, value) => {
8
      if (key === 'createdAt' || key === 'updatedAt') {
9
        return '[DATE]';
10
      }
11
      if (key === 'id' && typeof value === 'string' && value.length > 20) {
12
        return '[UUID]';
13
      }
14
      return value;
15
    }));
16
    return printer(sanitized, config, indentation, depth, refs);
17
  },
18
  test(val) {
19
    return val && typeof val === 'object' && ('createdAt' in val || 'id' in val);
20
  },
21
});

1
import { sendEmail } from './email';
2
import { sendSMS } from './sms';
3
import { logger } from './logger';
4

5
export async function notifyUser(
6
  userId: string,
7
  message: string,
8
  channels: ('email' | 'sms')[]
9
): Promise<{ success: boolean; channels: string[] }> {
10
  const sent: string[] = [];
11

12
  for (const channel of channels) {
13
    try {
14
      if (channel === 'email') {
15
        await sendEmail(userId, message);
16
        sent.push('email');
17
      } else if (channel === 'sms') {
18
        await sendSMS(userId, message);
19
        sent.push('sms');
20
      }
21
    } catch (err) {
22
      logger.error(`Failed to send ${channel} to ${userId}`, err);
23
    }
24
  }
25

26
  return { success: sent.length > 0, channels: sent };
27
}

1
import { describe, it, expect, vi, beforeEach } from 'vitest';
2
import { notifyUser } from './notification';
3

4
// Mock 整个模块
5
vi.mock('./email', () => ({
6
  sendEmail: vi.fn().mockResolvedValue(undefined),
7
}));
8

9
vi.mock('./sms', () => ({
10
  sendSMS: vi.fn().mockResolvedValue(undefined),
11
}));
12

13
vi.mock('./logger', () => ({
14
  logger: {
15
    error: vi.fn(),
16
    info: vi.fn(),
17
  },
18
}));
19

20
// 导入被 mock 的模块以进行断言
21
import { sendEmail } from './email';
22
import { sendSMS } from './sms';
23
import { logger } from './logger';
24

25
describe('notifyUser', () => {
26
  beforeEach(() => {
27
    vi.clearAllMocks();
28
  });
29

30
  it('should send email notification', async () => {
31
    const result = await notifyUser('user-1', 'Hello!', ['email']);
32

33
    expect(result).toEqual({ success: true, channels: ['email'] });
34
    expect(sendEmail).toHaveBeenCalledWith('user-1', 'Hello!');
35
    expect(sendSMS).not.toHaveBeenCalled();
36
  });
37

38
  it('should send both email and sms', async () => {
39
    const result = await notifyUser('user-1', 'Hello!', ['email', 'sms']);
40

41
    expect(result).toEqual({ success: true, channels: ['email', 'sms'] });
42
    expect(sendEmail).toHaveBeenCalledOnce();
43
    expect(sendSMS).toHaveBeenCalledOnce();
44
  });
45

46
  it('should handle partial failure gracefully', async () => {
47
    // email 失败，sms 成功
48
    vi.mocked(sendEmail).mockRejectedValueOnce(new Error('SMTP error'));
49

50
    const result = await notifyUser('user-1', 'Hello!', ['email', 'sms']);
51

52
    expect(result).toEqual({ success: true, channels: ['sms'] });
53
    expect(logger.error).toHaveBeenCalledWith(
54
      'Failed to send email to user-1',
55
      expect.any(Error)
56
    );
57
  });
58

59
  it('should return failure when all channels fail', async () => {
60
    vi.mocked(sendEmail).mockRejectedValueOnce(new Error('SMTP error'));
61
    vi.mocked(sendSMS).mockRejectedValueOnce(new Error('SMS quota exceeded'));
62

63
    const result = await notifyUser('user-1', 'Hello!', ['email', 'sms']);
64

65
    expect(result).toEqual({ success: false, channels: [] });
66
    expect(logger.error).toHaveBeenCalledTimes(2);
67
  });
68
});

1
export class StorageService {
2
  private prefix: string;
3

4
  constructor(prefix = 'app') {
5
    this.prefix = prefix;
6
  }
7

8
  private getKey(key: string): string {
9
    return `${this.prefix}:${key}`;
10
  }
11

12
  set(key: string, value: unknown): void {
13
    const serialized = JSON.stringify(value);
14
    localStorage.setItem(this.getKey(key), serialized);
15
  }
16

17
  get<T>(key: string): T | null {
18
    const raw = localStorage.getItem(this.getKey(key));
19
    if (raw === null) return null;
20
    try {
21
      return JSON.parse(raw) as T;
22
    } catch {
23
      return null;
24
    }
25
  }
26

27
  remove(key: string): void {
28
    localStorage.removeItem(this.getKey(key));
29
  }
30

31
  clear(): void {
32
    const keys = Object.keys(localStorage);
33
    for (const key of keys) {
34
      if (key.startsWith(`${this.prefix}:`)) {
35
        localStorage.removeItem(key);
36
      }
37
    }
38
  }
39
}

1
import { describe, it, expect, vi, beforeEach } from 'vitest';
2
import { StorageService } from './storage';
3

4
describe('StorageService', () => {
5
  let storage: StorageService;
6

7
  beforeEach(() => {
8
    // 使用 jsdom 的 localStorage
9
    localStorage.clear();
10
    storage = new StorageService('test');
11
  });
12

13
  it('should set and get values', () => {
14
    storage.set('user', { name: 'Alice', age: 30 });
15

16
    const user = storage.get<{ name: string; age: number }>('user');
17
    expect(user).toEqual({ name: 'Alice', age: 30 });
18
  });
19

20
  it('should return null for missing keys', () => {
21
    expect(storage.get('nonexistent')).toBeNull();
22
  });
23

24
  it('should handle invalid JSON gracefully', () => {
25
    // 直接写入非法 JSON
26
    localStorage.setItem('test:broken', '{invalid json}');
27
    expect(storage.get('broken')).toBeNull();
28
  });
29

30
  it('should use spy to verify localStorage calls', () => {
31
    const setItemSpy = vi.spyOn(Storage.prototype, 'setItem');
32

33
    storage.set('key', 'value');
34

35
    expect(setItemSpy).toHaveBeenCalledWith('test:key', '"value"');
36
    setItemSpy.mockRestore();
37
  });
38

39
  it('should clear only prefixed keys', () => {
40
    storage.set('a', 1);
41
    storage.set('b', 2);
42
    localStorage.setItem('other:c', '3'); // 不同前缀
43

44
    storage.clear();
45

46
    expect(storage.get('a')).toBeNull();
47
    expect(storage.get('b')).toBeNull();
48
    expect(localStorage.getItem('other:c')).toBe('3');
49
  });
50
});

1
export function debounce<T extends (...args: any[]) => any>(
2
  fn: T,
3
  delay: number
4
): (...args: Parameters<T>) => void {
5
  let timer: ReturnType<typeof setTimeout> | null = null;
6

7
  return (...args: Parameters<T>) => {
8
    if (timer !== null) {
9
      clearTimeout(timer);
10
    }
11
    timer = setTimeout(() => {
12
      fn(...args);
13
      timer = null;
14
    }, delay);
15
  };
16
}

1
import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
2
import { debounce } from './debounce';
3

4
describe('debounce', () => {
5
  beforeEach(() => {
6
    vi.useFakeTimers();
7
  });
8

9
  afterEach(() => {
10
    vi.useRealTimers();
11
  });
12

13
  it('should delay function execution', () => {
14
    const fn = vi.fn();
15
    const debounced = debounce(fn, 300);
16

17
    debounced();
18
    expect(fn).not.toHaveBeenCalled();
19

20
    vi.advanceTimersByTime(299);
21
    expect(fn).not.toHaveBeenCalled();
22

23
    vi.advanceTimersByTime(1);
24
    expect(fn).toHaveBeenCalledOnce();
25
  });
26

27
  it('should reset timer on subsequent calls', () => {
28
    const fn = vi.fn();
29
    const debounced = debounce(fn, 300);
30

31
    debounced();
32
    vi.advanceTimersByTime(200);
33
    debounced(); // 重置计时器
34
    vi.advanceTimersByTime(200);
35

36
    expect(fn).not.toHaveBeenCalled(); // 还没到 300ms
37

38
    vi.advanceTimersByTime(100);
39
    expect(fn).toHaveBeenCalledOnce();
40
  });
41

42
  it('should pass arguments correctly', () => {
43
    const fn = vi.fn();
44
    const debounced = debounce(fn, 100);
45

46
    debounced('hello', 42);
47
    vi.runAllTimers();
48

49
    expect(fn).toHaveBeenCalledWith('hello', 42);
50
  });
51
});

1
<script setup lang="ts">
2
import { ref, computed } from 'vue';
3

4
const props = withDefaults(defineProps<{
5
  initial?: number;
6
  min?: number;
7
  max?: number;
8
}>(), {
9
  initial: 0,
10
  min: -Infinity,
11
  max: Infinity,
12
});
13

14
const emit = defineEmits<{
15
  change: [value: number];
16
}>();
17

18
const count = ref(props.initial);
19

20
const canDecrement = computed(() => count.value > props.min);
21
const canIncrement = computed(() => count.value < props.max);
22

23
function increment() {
24
  if (canIncrement.value) {
25
    count.value++;
26
    emit('change', count.value);
27
  }
28
}
29

30
function decrement() {
31
  if (canDecrement.value) {
32
    count.value--;
33
    emit('change', count.value);
34
  }
35
}
36
</script>
37

38
<template>
39
  <div class="counter">
40
    <button
41
      data-testid="decrement"
42
      :disabled="!canDecrement"
43
      @click="decrement"
44
    >
45
      -
46
    </button>
47
    <span data-testid="count">{{ count }}</span>
48
    <button
49
      data-testid="increment"
50
      :disabled="!canIncrement"
51
      @click="increment"
52
    >
53
      +
54
    </button>
55
  </div>
56
</template>

1
import { describe, it, expect } from 'vitest';
2
import { mount } from '@vue/test-utils';
3
import Counter from './Counter.vue';
4

5
describe('Counter', () => {
6
  it('should render with default initial value', () => {
7
    const wrapper = mount(Counter);
8
    expect(wrapper.get('[data-testid="count"]').text()).toBe('0');
9
  });
10

11
  it('should render with custom initial value', () => {
12
    const wrapper = mount(Counter, {
13
      props: { initial: 10 },
14
    });
15
    expect(wrapper.get('[data-testid="count"]').text()).toBe('10');
16
  });
17

18
  it('should increment on click', async () => {
19
    const wrapper = mount(Counter);
20

21
    await wrapper.get('[data-testid="increment"]').trigger('click');
22
    expect(wrapper.get('[data-testid="count"]').text()).toBe('1');
23
  });
24

25
  it('should decrement on click', async () => {
26
    const wrapper = mount(Counter, { props: { initial: 5 } });
27

28
    await wrapper.get('[data-testid="decrement"]').trigger('click');
29
    expect(wrapper.get('[data-testid="count"]').text()).toBe('4');
30
  });
31

32
  it('should emit change event', async () => {
33
    const wrapper = mount(Counter);
34

35
    await wrapper.get('[data-testid="increment"]').trigger('click');
36

37
    expect(wrapper.emitted('change')).toHaveLength(1);
38
    expect(wrapper.emitted('change')![0]).toEqual([1]);
39
  });
40

41
  it('should respect max limit', async () => {
42
    const wrapper = mount(Counter, {
43
      props: { initial: 2, max: 3 },
44
    });
45

46
    await wrapper.get('[data-testid="increment"]').trigger('click'); // 3
47
    await wrapper.get('[data-testid="increment"]').trigger('click'); // still 3
48

49
    expect(wrapper.get('[data-testid="count"]').text()).toBe('3');
50
    expect(
51
      wrapper.get('[data-testid="increment"]').attributes('disabled')
52
    ).toBeDefined();
53
  });
54

55
  it('should respect min limit', async () => {
56
    const wrapper = mount(Counter, {
57
      props: { initial: 1, min: 0 },
58
    });
59

60
    await wrapper.get('[data-testid="decrement"]').trigger('click'); // 0
61
    await wrapper.get('[data-testid="decrement"]').trigger('click'); // still 0
62

63
    expect(wrapper.get('[data-testid="count"]').text()).toBe('0');
64
    expect(
65
      wrapper.get('[data-testid="decrement"]').attributes('disabled')
66
    ).toBeDefined();
67
  });
68
});

1
import { defineStore } from 'pinia';
2
import { ref, computed } from 'vue';
3

4
export interface Todo {
5
  id: number;
6
  text: string;
7
  done: boolean;
8
}
9

10
export const useTodoStore = defineStore('todo', () => {
11
  const todos = ref<Todo[]>([]);
12
  let nextId = 1;
13

14
  const remaining = computed(() => todos.value.filter(t => !t.done).length);
15

16
  function addTodo(text: string) {
17
    todos.value.push({ id: nextId++, text, done: false });
18
  }
19

20
  function toggleTodo(id: number) {
21
    const todo = todos.value.find(t => t.id === id);
22
    if (todo) todo.done = !todo.done;
23
  }
24

25
  function removeTodo(id: number) {
26
    todos.value = todos.value.filter(t => t.id !== id);
27
  }
28

29
  return { todos, remaining, addTodo, toggleTodo, removeTodo };
30
});

1
import { describe, it, expect, beforeEach } from 'vitest';
2
import { setActivePinia, createPinia } from 'pinia';
3
import { useTodoStore } from './todo';
4

5
describe('Todo Store', () => {
6
  beforeEach(() => {
7
    // 每个测试创建新的 pinia 实例，确保隔离
8
    setActivePinia(createPinia());
9
  });
10

11
  it('should start empty', () => {
12
    const store = useTodoStore();
13
    expect(store.todos).toHaveLength(0);
14
    expect(store.remaining).toBe(0);
15
  });
16

17
  it('should add todo', () => {
18
    const store = useTodoStore();
19
    store.addTodo('Buy milk');
20

21
    expect(store.todos).toHaveLength(1);
22
    expect(store.todos[0]).toMatchObject({ text: 'Buy milk', done: false });
23
    expect(store.remaining).toBe(1);
24
  });
25

26
  it('should toggle todo', () => {
27
    const store = useTodoStore();
28
    store.addTodo('Buy milk');
29

30
    store.toggleTodo(store.todos[0].id);
31
    expect(store.todos[0].done).toBe(true);
32
    expect(store.remaining).toBe(0);
33

34
    store.toggleTodo(store.todos[0].id);
35
    expect(store.todos[0].done).toBe(false);
36
    expect(store.remaining).toBe(1);
37
  });
38

39
  it('should remove todo', () => {
40
    const store = useTodoStore();
41
    store.addTodo('A');
42
    store.addTodo('B');
43

44
    const idToRemove = store.todos[0].id;
45
    store.removeTodo(idToRemove);
46

47
    expect(store.todos).toHaveLength(1);
48
    expect(store.todos[0].text).toBe('B');
49
  });
50
});