Skip to content
FEE
Frontend Engineering Essentials
Mid Level

模擬、替身與測試替代物 ​

背景 ​

每個測試都需要控制被測程式碼周遭的環境。正式環境的程式碼會呼叫 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:

ts
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() 包裝現有方法,在記錄呼叫的同時保留真實實作。

ts
// 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()
  })
})
ts
// 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 收到的都是模擬版本。工廠函式定義模擬模組匯出的內容。

ts
// 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()
}
ts
// 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)中都能運作。

ts
// 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 })
  }),
]
ts
// 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())
ts
// 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() 測試日期相關邏輯 ​

ts
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 ​

這三個清除函式做的事情不同。混用它們會導致測試之間的狀態洩漏。

ts
// 在 vitest.config.ts 中全域配置,避免每個檔案的樣板程式碼
export default defineConfig({
  test: {
    // clearMocks: true      — 每個測試後清除呼叫歷史和實例
    //                         不重置 mock 回傳值
    // resetMocks: true      — 清除呼叫歷史並將回傳值重置為 undefined
    //                         不還原 vi.spyOn() 到原始實作
    // restoreMocks: true    — 清除呼叫歷史、重置回傳值,並還原
    //                         vi.spyOn() 到原始實作
    //
    // 對大多數專案而言,restoreMocks: true 是最安全的預設值。
    restoreMocks: true,
  },
})
ts
// 每個函式單獨執行時的行為:
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 ​

參考資料 ​