模擬、替身與測試替代物
背景
每個測試都需要控制被測程式碼周遭的環境。正式環境的程式碼會呼叫 HTTP API、從檔案系統讀取、取得當前時間、呼叫第三方 SDK——這些在測試環境中都無法控制、不具確定性,也很慢。測試替代物(Test Double)是解決方案:替換真實依賴的替代品,讓測試能完全控制依賴的回傳值以及它是否被呼叫。
Gerard Meszaros 在 xUnit Test Patterns(2007)中整理了這套詞彙。這些術語至今仍是業界的參考標準,儘管實務中使用得較為寬鬆:
Mock(模擬物件) — 記錄自身被呼叫方式的物件,其行為在測試斷言中被驗證。測試明確斷言 mock 是以特定參數被呼叫的。在 Vitest 中:一個 vi.fn(),之後你寫 expect(sendEmail).toHaveBeenCalledWith('alice@example.com', '歡迎')。
Stub(替代回傳物件) — 被呼叫時回傳固定值、但不被驗證的物件。測試不斷言 stub 是否被呼叫;它只關心被測程式碼如何反應回傳值。一個永遠從網路呼叫回傳 { ok: true } 的物件是 stub,不是 mock。
Spy(間諜物件) — 包裝真實實作並記錄呼叫,而不取代行為。vi.spyOn(console, 'warn') 讓真實的 console.warn 執行,同時記錄它被呼叫的情況。你之後可以對呼叫進行斷言,或選擇性地替換實作。
Fake(仿造物件) — 依賴項目的可運作簡化實作。在測試中使用記憶體內 SQLite 資料庫代替真實 PostgreSQL 伺服器就是 fake。它有真實的行為(你可以插入和查詢資料列),但不是正式環境系統。
Dummy(虛擬物件) — 為滿足函式簽章而傳入的佔位符,但在測試過程中從未真正使用。傳遞給需要 User 物件但只讀取 user.id 的函式的虛假電子郵件地址就是 dummy。
在日常的 Vitest/Jest 使用中,「mock」被通俗地用於指稱上述五種類型。但當你在推理測試實際上涵蓋了什麼時,這些區別就很重要了。
設計思維
為什麼 MSW 是首選的 API 模擬方法
模擬 API 的簡單做法是全域替換 fetch:
global.fetch = jest.fn().mockResolvedValue({
ok: true,
json: async () => ({ users: [] }),
})這有兩個嚴重問題。第一,它模擬的是實作(fetch),而非行為(API 回傳什麼)。如果你的程式碼使用 axios,或以不同方式呼叫 fetch 的包裝器,mock 就不會套用。第二,mock 繞過了真實的回應解析路徑。你的程式碼可能呼叫 response.json() 並透過 schema 驗證器映射結果——當 fetch 被替換時,這些都不會執行。
MSW 在網路層攔截,位於所有 HTTP 客戶端程式庫的下方。真實的 fetch 會執行。真實的回應物件會被建構。真實的 JSON 解析會執行。真實的 schema 驗證會執行。只有網路 I/O 被攔截——假的回應在瀏覽器(或 Node.js)本該從伺服器接收位元組的那個點被注入。
這意味著測試執行的程式碼路徑與正式環境相同。回應解析或 schema 映射中的錯誤會被捕捉。相同的 MSW handler 在瀏覽器整合測試(使用 Service Worker)和 Node.js 單元測試(使用 msw/node)中都能運作,handler 程式碼無需任何修改。
為什麼 vi.mock() 強大但危險
vi.mock('path/to/module') 在測試執行前用工廠生成的替換品取代整個模組。它很強大,因為它套用於測試檔案中對該模組的每一個 import,包括傳遞性 import。它的危險性也在於此:模擬 api/users 的測試不會執行 api/users 中任何真實的程式碼。如果真實模組有錯誤——錯誤的端點 URL、錯誤的欄位映射、缺少的錯誤處理——測試仍然會通過,因為 mock 回傳你告訴它回傳的任何值。
vi.mock() 在模組是系統邊界(HTTP 客戶端、檔案系統包裝器、第三方 SDK)且你無法或不應該執行真實實作時是合適的。對於可以直接呼叫真實實作的內部工具函式,它並不合適。
邊界規則
在被測程式碼周圍畫一條線。一側是:你擁有的程式碼、可以在測試環境中執行的邏輯、快速且具確定性的函式。另一側是:網路、檔案系統、系統時鐘、你無法控制其副作用的第三方 SDK。
在邊界處模擬所有東西。不要跨越邊界去模擬你自己那一側的東西。
當你發現自己在模擬自己程式碼定義的函式——例如 vi.mock('./utils/formatDate') 來避免處理日期格式化——那就是一個壞味道。要麼該函式確實跨越了邊界(它從系統時鐘讀取,在這種情況下模擬時鐘,而非函式),要麼它沒有(在這種情況下呼叫真實函式並讓測試處理真實日期)。
為什麼過度模擬是測試壞味道
每個函式都被模擬的測試套件會給出虛假的信心。mock 回傳「正確」的值,因為你寫它時就是這樣——而不是因為程式碼真的可以運作。改變內部函式回傳形狀的重構會在正式環境中破壞真實程式碼,卻不會破壞測試,因為測試模擬了舊的形狀。
經驗法則:如果移除 mock 需要執行緩慢、不確定性或有外部副作用的東西——保留 mock。如果移除 mock 只是意味著呼叫真實函式——移除它。
最佳實踐
必須(MUST)只在系統邊界處進行模擬——HTTP、檔案系統、系統時間和外部 SDK。 邊界規則是:在你擁有的程式碼周圍劃一條線;模擬線外側的所有東西,線內側則呼叫真實實作。如果一個函式速度快、具確定性且沒有外部副作用,就絕對禁止(MUST NOT)模擬它——模擬它等於在測試你的 mock,而非你的程式碼。只有在移除 mock 需要呼叫緩慢、不確定性或有真實外部副作用的東西時,mock 才是合理的。
必須(MUST)使用 MSW 進行 HTTP API 模擬,而非直接替換 global.fetch 或 axios。 MSW 在網路層攔截,位於所有 HTTP 客戶端程式庫的下方,因此真實的 fetch 會執行、真實的回應物件會被建構、真實的 JSON 解析和 schema 驗證都會執行。以 vi.fn() 替換 global.fetch 絕對禁止(MUST NOT)作為預設做法,因為它繞過了你的程式碼在正式環境中執行的每一個回應處理層,意味著回應解析中的錯誤不會被捕捉。相同的 MSW handler 無需修改即可在 Node.js 測試環境(msw/node)和基於瀏覽器的整合測試中運作。
應該(SHOULD)在 server.listen() 中設定 onUnhandledRequest: 'error',讓意外的請求導致測試失敗。 MSW 對未處理請求的預設行為是 console 警告,很容易被忽略。設定 'error' 可將任何不匹配 handler 的請求變成測試失敗,捕捉你的程式碼發出你沒打算覆蓋的 API 呼叫的情況。這應該(SHOULD)是每個測試設定檔的標準配置。
應該(SHOULD)使用 vi.setSystemTime() 凍結時鐘,而非模擬日期工具函式。 模擬 getTimestamp() 輔助函式只修正呼叫它的那一條程式碼路徑;直接讀取 Date.now() 的第三方程式庫和其他內部模組仍然會看到真實時間。vi.useFakeTimers() 後接 vi.setSystemTime() 在源頭凍結時間,讓每一條程式碼路徑(包括依賴項)必須(MUST)看到被凍結的值。始終在 afterEach 中用 vi.useRealTimers() 還原真實計時器。
視覺化
模擬邊界圖
測試透過真實的函式呼叫與它所擁有的程式碼互動。在系統邊界處,真實的外部依賴被測試替代物取代。外部系統永遠不會被呼叫。
範例
1. vi.fn() vs vi.spyOn() — 關鍵差異
vi.fn() 建立一個沒有真實實作的獨立 mock 函式。vi.spyOn() 包裝現有方法,在記錄呼叫的同時保留真實實作。
// vi.fn() — 從頭建立 mock,不執行真實實作
import { vi, expect, it, describe, beforeEach } from 'vitest'
describe('通知服務', () => {
it('以正確的參數呼叫 sendEmail', async () => {
// vi.fn() 完全取代實作。
// 真實 sendEmail 函式的任何程式碼都不會執行。
const sendEmail = vi.fn().mockResolvedValue({ delivered: true })
await notifyUser({ email: 'alice@example.com', name: 'Alice' }, sendEmail)
// 這是 MOCK 斷言——我們驗證它「如何」被呼叫,而非只驗證它「是否」被呼叫。
expect(sendEmail).toHaveBeenCalledOnce()
expect(sendEmail).toHaveBeenCalledWith(
'alice@example.com',
'歡迎,Alice',
expect.objectContaining({ from: 'noreply@example.com' }),
)
})
it('使用者已取消訂閱時不呼叫 sendEmail', async () => {
const sendEmail = vi.fn()
await notifyUser({ email: 'bob@example.com', name: 'Bob', unsubscribed: true }, sendEmail)
// Stub 風格的斷言——我們只關心它沒有被呼叫,不關心參數。
expect(sendEmail).not.toHaveBeenCalled()
})
})// vi.spyOn() — 包裝真實實作,記錄呼叫
import { vi, expect, it, describe, afterEach } from 'vitest'
import * as analytics from './analytics'
describe('產品頁面', () => {
afterEach(() => {
// 每個測試後還原原始實作。
vi.restoreAllMocks()
})
it('掛載時追蹤頁面瀏覽', () => {
// 真實的 analytics.track() 會執行——vi.spyOn 不會取代它。
// 我們只是記錄它被呼叫,以便我們可以對它進行斷言。
const trackSpy = vi.spyOn(analytics, 'track')
mountProductPage({ productId: 'p-123' })
expect(trackSpy).toHaveBeenCalledWith('page_view', { productId: 'p-123' })
})
it('可以選擇性地取代實作', () => {
// 你可以在 spy 上呼叫 .mockImplementation() 來取代真實方法。
const trackSpy = vi.spyOn(analytics, 'track').mockImplementation(() => {})
mountProductPage({ productId: 'p-456' })
expect(trackSpy).toHaveBeenCalledTimes(1)
// 真實的 analytics.track 沒有執行——我們取代了它。
})
})2. 使用 vi.mock() 進行模組層級替換
vi.mock() 在 Vitest 的轉換步驟中被提升到檔案頂部——它在任何 import 語句執行之前運行,因此檔案中每個 import 收到的都是模擬版本。工廠函式定義模擬模組匯出的內容。
// src/api/users.ts(真實模組——我們不希望它在測試中執行,因為它發出真實的 HTTP 請求)
export async function getUsers(): Promise<User[]> {
const res = await fetch('/api/users')
if (!res.ok) throw new Error(`HTTP ${res.status}`)
return res.json()
}
export async function createUser(data: CreateUserInput): Promise<User> {
const res = await fetch('/api/users', {
method: 'POST',
body: JSON.stringify(data),
headers: { 'Content-Type': 'application/json' },
})
if (!res.ok) throw new Error(`HTTP ${res.status}`)
return res.json()
}// src/components/UserList.test.ts
import { vi, expect, it, describe, beforeEach } from 'vitest'
import { render, screen, waitFor } from '@testing-library/react'
import UserList from './UserList'
// vi.mock() 會被提升——它在解析任何 import 之前執行。
// 此測試檔案中對 '../api/users' 的每個 import(包括 UserList 本身的 import)
// 都會收到模擬版本。
vi.mock('../api/users', () => ({
getUsers: vi.fn(),
createUser: vi.fn(),
}))
// 在 vi.mock() 之後 import,以獲得模擬版本。
import { getUsers } from '../api/users'
describe('UserList', () => {
beforeEach(() => {
// 每個測試前重置呼叫歷史和回傳值。
vi.clearAllMocks()
})
it('渲染 API 回傳的使用者清單', async () => {
// 為此測試配置 stub 回傳值。
vi.mocked(getUsers).mockResolvedValue([
{ id: '1', name: 'Alice', email: 'alice@example.com' },
{ id: '2', name: 'Bob', email: 'bob@example.com' },
])
render(<UserList />)
await waitFor(() => {
expect(screen.getByText('Alice')).toBeInTheDocument()
expect(screen.getByText('Bob')).toBeInTheDocument()
})
})
it('API 呼叫失敗時顯示錯誤狀態', async () => {
vi.mocked(getUsers).mockRejectedValue(new Error('HTTP 503'))
render(<UserList />)
await waitFor(() => {
expect(screen.getByRole('alert')).toHaveTextContent('載入使用者失敗')
})
})
})3. MSW:setupServer、handlers 與每個測試的覆寫
MSW handler 在網路層攔截請求。相同的 handler 格式在 Node.js 測試(msw/node)和瀏覽器整合測試(Service Worker)中都能運作。
// src/mocks/handlers.ts — 所有測試共用的 handler
import { http, HttpResponse } from 'msw'
export const handlers = [
http.get('/api/users', () => {
return HttpResponse.json([
{ id: '1', name: 'Alice', email: 'alice@example.com' },
{ id: '2', name: 'Bob', email: 'bob@example.com' },
])
}),
http.post('/api/users', async ({ request }) => {
const body = await request.json() as { name: string; email: string }
return HttpResponse.json(
{ id: '3', name: body.name, email: body.email },
{ status: 201 },
)
}),
http.delete('/api/users/:id', ({ params }) => {
return new HttpResponse(null, { status: 204 })
}),
]// src/setupTests.ts — Vitest 設定檔(在 vitest.config.ts 的 setupFiles 中配置)
import { setupServer } from 'msw/node'
import { handlers } from './mocks/handlers'
// 建立一次伺服器並匯出,讓測試可以呼叫 server.use() 進行覆寫。
export const server = setupServer(...handlers)
// 所有測試前啟動伺服器,每個測試後重置 handler,
// 所有測試完成後停止伺服器。
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }))
afterEach(() => server.resetHandlers())
afterAll(() => server.close())// src/components/UserList.test.ts — 使用 MSW 而非 vi.mock()
import { server } from '../setupTests'
import { http, HttpResponse } from 'msw'
import { render, screen, waitFor } from '@testing-library/react'
import UserList from './UserList'
it('從 API 渲染使用者', async () => {
// handlers.ts 中的預設 handler 回傳 Alice 和 Bob。
// 不需要覆寫——測試直接渲染並斷言。
render(<UserList />)
await waitFor(() => {
expect(screen.getByText('Alice')).toBeInTheDocument()
expect(screen.getByText('Bob')).toBeInTheDocument()
})
})
it('API 回傳 500 時顯示錯誤橫幅', async () => {
// server.use() 為此測試新增一次性覆寫。
// 測試結束後,afterEach 中的 server.resetHandlers() 會移除覆寫。
server.use(
http.get('/api/users', () => {
return new HttpResponse(null, { status: 500 })
}),
)
render(<UserList />)
await waitFor(() => {
expect(screen.getByRole('alert')).toHaveTextContent('載入使用者失敗')
})
})
it('請求進行中時顯示載入狀態', async () => {
// 使用永遠不會 resolve 的回應,讓載入狀態持續可見。
server.use(
http.get('/api/users', () => new Promise(() => {})),
)
render(<UserList />)
expect(screen.getByRole('progressbar')).toBeInTheDocument()
})4. 使用 vi.setSystemTime() 測試日期相關邏輯
import { vi, expect, it, describe, beforeEach, afterEach } from 'vitest'
import { isWeekend, formatRelativeDate, isExpired } from './date-utils'
describe('日期相關工具函式', () => {
beforeEach(() => {
// 將時間凍結到已知值:2026-01-14 星期三 09:00 UTC。
// Date.now()、new Date() 和 performance.now() 都反映此值。
vi.useFakeTimers()
vi.setSystemTime(new Date('2026-01-14T09:00:00.000Z'))
})
afterEach(() => {
// 每個測試後還原真實計時器。
vi.useRealTimers()
})
it('星期三時 isWeekend 回傳 false', () => {
expect(isWeekend()).toBe(false)
})
it('3 天前的日期 formatRelativeDate 回傳「3 天前」', () => {
const threeDaysAgo = new Date('2026-01-11T09:00:00.000Z')
expect(formatRelativeDate(threeDaysAgo)).toBe('3 天前')
})
it('到期日已過時 isExpired 回傳 true', () => {
const yesterday = new Date('2026-01-13T09:00:00.000Z')
expect(isExpired(yesterday)).toBe(true)
})
it('到期日在未來時 isExpired 回傳 false', () => {
const tomorrow = new Date('2026-01-15T09:00:00.000Z')
expect(isExpired(tomorrow)).toBe(false)
})
})Mock 清除:clearAllMocks vs resetAllMocks vs restoreAllMocks
這三個清除函式做的事情不同。混用它們會導致測試之間的狀態洩漏。
// 在 vitest.config.ts 中全域配置,避免每個檔案的樣板程式碼
export default defineConfig({
test: {
// clearMocks: true — 每個測試後清除呼叫歷史和實例
// 不重置 mock 回傳值
// resetMocks: true — 清除呼叫歷史並將回傳值重置為 undefined
// 不還原 vi.spyOn() 到原始實作
// restoreMocks: true — 清除呼叫歷史、重置回傳值,並還原
// vi.spyOn() 到原始實作
//
// 對大多數專案而言,restoreMocks: true 是最安全的預設值。
restoreMocks: true,
},
})// 每個函式單獨執行時的行為:
const fn = vi.fn().mockReturnValue(42)
fn()
fn()
vi.clearAllMocks()
// fn.mock.calls 現在是 [] — 呼叫歷史已清除
// fn() 仍然回傳 42 — 回傳值未重置
// vi.spyOn stub 未還原
vi.resetAllMocks()
// fn.mock.calls 現在是 [] — 呼叫歷史已清除
// fn() 現在回傳 undefined — 回傳值已重置
// vi.spyOn stub 未還原
vi.restoreAllMocks()
// fn.mock.calls 現在是 [] — 呼叫歷史已清除
// fn() 現在回傳 undefined — 回傳值已重置
// vi.spyOn stub 還原至原始實作常見錯誤
忘記 vi.mock() 會被提升。 vi.mock() 在編譯時被 Vitest 的轉換步驟移到檔案頂部,在任何 import 語句執行之前。在 import 語句和 vi.mock() 呼叫之間寫程式碼,並期望它先執行,會產生令人困惑的結果。所有 vi.mock() 呼叫始終最先執行。
測試之間未重置 mock。 在一個測試中設定的 vi.fn().mockResolvedValue(users) 如果未配置 vi.clearAllMocks() 或 restoreMocks: true,會洩漏到下一個測試。第二個測試通過是因為第一個測試的 mock 狀態,而非因為它自己的設置。在 vitest.config.ts 中配置 restoreMocks: true,讓所有 mock 在每個測試後自動重置。
相關 FEE
- FEE-1100 測試策略總覽 — 測試金字塔和決定模擬在哪裡值得的成本與信心取捨
- FEE-1101 使用 Vitest 進行單元測試 —
vi.fn()基礎和 Vitest 的測試結構 - FEE-1102 元件測試 — 元件測試中的模擬:使用 Testing Library 的 MSW、模擬子元件
- FEE-1103 端對端測試:Playwright 與 Cypress — E2E 測試中用於網路模擬的
cy.intercept()和 Playwrightroute
參考資料
- MSW — Getting Started — 安裝、handler 語法、瀏覽器和 Node.js 整合
- MSW — Comparison with other approaches — 為什麼 MSW 在網路層攔截以及這對測試可信度意味著什麼
- Vitest — Mocking —
vi.fn()、vi.spyOn()、vi.mock()、vi.stubGlobal()、vi.setSystemTime()和 mock 清除 - Gerard Meszaros — Test Double taxonomy (martinfowler.com) — Martin Fowler 對 Meszaros 五種測試替代物類型的摘要,含定義和範例
- Martin Fowler — Mocks Aren't Stubs — 狀態驗證(stub)和行為驗證(mock)之間的區別,以及為什麼這很重要
- Vitest —
vi.mock()hoisting behavior — 為什麼vi.mock()呼叫被移到檔案頂部以及工廠函式如何運作