測試驅動開發工作流程
此技能確保所有程式碼開發都遵循 TDD 原則,並具有全面的測試覆蓋率。
啟動時機
- 編寫新功能或功能
- 修復錯誤或問題
- 重構現有程式碼
- 新增 API 端點
- 建立新元件
核心原則
1. 測試先於程式碼
一律先撰寫測試,然後再實作程式碼以使測試通過。
2. 覆蓋率要求
- 最低 80% 覆蓋率(單元 + 整合 + 端對端)
- 涵蓋所有邊緣案例
- 測試錯誤情境
- 驗證邊界條件
3. 測試類型
單元測試
- 個別函數和工具程式
- 元件邏輯
- 純函數
- 輔助程式和工具程式
整合測試
- API 端點
- 資料庫操作
- 服務互動
- 外部 API 呼叫
端對端測試(Playwright)
- 關鍵使用者流程
- 完整工作流程
- 瀏覽器自動化
- UI 互動
TDD 工作流程步驟
步驟 0:偵測測試執行器
不要假設使用 npm test。以下步驟和範例中的指令使用 <test>、<test-watch> 和 <coverage> 作為專案實際執行器的佔位符。在開始前先解析一次:
-
找到專案的執行器。 讀取
package.json(packageManager、scripts.test)、lockfile、pyproject.toml/pytest.ini、go.mod、Cargo.toml。首先匹配到的就是;不要假設使用npm test。 -
區分套件管理器和測試執行器。它們並不相同。 一個專案可能使用 Bun 安裝依賴項,但仍執行 Jest 或 Vitest。檢查
package.jsonscripts.test和測試檔案:scripts.test叫用jest/vitest-> 透過偵測到的 PM 執行(npm test、pnpm test、yarn test或bun run test)。scripts.test是bun test,或測試檔案import { test, expect } from "bun:test",或沒有 jest/vitest 配置但存在 Bun -> 使用 Bun 的原生執行器(bun test)。請參閱下面的 Bun 原生測試模式。- Python:
<test>=pytest,<coverage>=pytest --cov --cov-fail-under=80。Go:go test ./...和go test -cover ./...。Rust:cargo test。
執行器指令矩陣:
| 執行器 | <test> | <test-watch> | <coverage> | <lint> |
|---|---|---|---|---|
| npm | npm test | npm test -- --watch | npm run test:coverage | npm run lint |
| pnpm | pnpm test | pnpm test --watch | pnpm test:coverage | pnpm lint |
| yarn | yarn test | yarn test --watch | yarn test:coverage | yarn lint |
| Bun(腳本執行 jest/vitest) | bun run test | bun run test --watch | bun run test:coverage | bun run lint |
Bun(原生 bun:test) | bun test | bun test --watch | bun test --coverage | bun run lint |
bun test(Bun 的內建執行器)不同於bun run test(執行package.jsontest腳本)。選錯是常見的失敗原因 - 例如,在僅限 ESM 的專案中透過npx/bun run叫用 Jest 會失敗,而bun test則會原生執行測試套件。在 RED 關卡之前確認專案期望的是哪一個,然後將下面出現的npm test全部替換為<test>/<coverage>。
步驟 1:撰寫使用者旅程
as a [角色],我想要 [動作],以便 [效益]
範例:
as a 使用者,我想要語義搜尋市場,
以便即使沒有確切關鍵字也能找到相關市場。
步驟 2:產生測試案例
針對每個使用者旅程,建立全面的測試案例:
describe('語義搜尋', () => {
it('針對查詢回傳相關市場', async () => {
// 測試實作
})
it('優雅地處理空查詢', async () => {
// 測試邊緣案例
})
it('當 Redis 不可用時,回退到子字串搜尋', async () => {
// 測試備援行為
})
it('按相似度評分排序結果', async () => {
// 測試排序邏輯
})
})
步驟 3:執行測試(它們應該會失敗)
<test>
# 測試應該會失敗 - 我們尚未實作
步驟 4:實作程式碼
編寫最少的程式碼以使測試通過:
// 由測試引導的實作
export async function searchMarkets(query: string) {
// 此處實作
}
步驟 5:再次執行測試
<test>
# 測試現在應該通過
步驟 6:重構
在保持測試綠燈的情況下改善程式碼品質:
- 消除重複
- 改善命名
- 最佳化效能
- 增強可讀性
步驟 7:驗證覆蓋率
<coverage>
# 確認達到 80%+ 覆蓋率
測試模式
單元測試模式(Jest/Vitest)
import { render, screen, fireEvent } from '@testing-library/react'
import { Button } from './Button'
describe('Button 元件', () => {
it('使用正確文字渲染', () => {
render(<Button>點我</Button>)
expect(screen.getByText('點我')).toBeInTheDocument()
})
it('點擊時呼叫 onClick', () => {
const handleClick = jest.fn()
render(<Button onClick={handleClick}>點擊</Button>)
fireEvent.click(screen.getByRole('button'))
expect(handleClick).toHaveBeenCalledTimes(1)
})
it('當 disabled prop 為 true 時被停用', () => {
render(<Button disabled>點擊</Button>)
expect(screen.getByRole('button')).toBeDisabled()
})
})
Bun 原生測試模式(bun:test)
當專案使用 Bun 的內建執行器時(請參閱步驟 0),從 bun:test 匯入並使用 bun test 執行 - 而非 bun run test。其 API 類似 Jest,因此 describe / it / expect 和大多數匹配器都可以沿用。
import { describe, it, expect, mock } from 'bun:test'
import { searchMarkets } from './search'
describe('searchMarkets', () => {
it('為空查詢回傳空列表', async () => {
expect(await searchMarkets('')).toEqual([])
})
it('按相似度評分排序結果', async () => {
const results = await searchMarkets('election')
expect(results).toEqual([...results].sort((a, b) => b.score - a.score))
})
})
bun test # 執行一次(紅/綠關卡)
bun test --watch # 開發期間的監看模式
bun test --coverage # 覆蓋率報告
- 使用
bun:test的mock.module(...)/mock(...)模擬模組,而非jest.mock(...)。 - 在
bunfig.toml的[test]區段下配置覆蓋率閾值(例如coverageThreshold),而非 Jest 的coverageThresholds配置區塊。
API 整合測試模式
import { NextRequest } from 'next/server'
import { GET } from './route'
describe('GET /api/markets', () => {
it('成功回傳市場', async () => {
const request = new NextRequest('http://localhost/api/markets')
const response = await GET(request)
const data = await response.json()
expect(response.status).toBe(200)
expect(data.success).toBe(true)
expect(Array.isArray(data.data)).toBe(true)
})
it('驗證查詢參數', async () => {
const request = new NextRequest('http://localhost/api/markets?limit=invalid')
const response = await GET(request)
expect(response.status).toBe(400)
})
it('優雅地處理資料庫錯誤', async () => {
// 模擬資料庫故障
const request = new NextRequest('http://localhost/api/markets')
// 測試錯誤處理
})
})
端對端測試模式(Playwright)
import { test, expect } from '@playwright/test'
test('使用者可以搜尋和篩選市場', async ({ page }) => {
// 導航到市場頁面
await page.goto('/')
await page.click('a[href="/markets"]')
// 確認頁面已載入
await expect(page.locator('h1')).toContainText('市場')
// 搜尋市場
await page.fill('input[placeholder="搜尋市場"]', 'election')
// 等待去抖動和結果
await page.waitForTimeout(600)
// 確認顯示搜尋結果
const results = page.locator('[data-testid="market-card"]')
await expect(results).toHaveCount(5, { timeout: 5000 })
// 確認結果包含搜尋詞
const firstResult = results.first()
await expect(firstResult).toContainText('election', { ignoreCase: true })
// 按狀態篩選
await page.click('button:has-text("活躍")')
// 確認篩選結果
await expect(results).toHaveCount(3)
})
test('使用者可以建立新市場', async ({ page }) => {
// 先登入
await page.goto('/creator-dashboard')
// 填寫市場建立表單
await page.fill('input[name="name"]', '測試市場')
await page.fill('textarea[name="description"]', '測試描述')
await page.fill('input[name="endDate"]', '2025-12-31')
// 提交表單
await page.click('button[type="submit"]')
// 確認成功訊息
await expect(page.locator('text=市場建立成功')).toBeVisible()
// 確認重新導向到市場頁面
await expect(page).toHaveURL(/\/markets\/test-market/)
})
測試檔案組織
src/
├── components/
│ ├── Button/
│ │ ├── Button.tsx
│ │ ├── Button.test.tsx # 單元測試
│ │ └── Button.stories.tsx # Storybook
│ └── MarketCard/
│ ├── MarketCard.tsx
│ └── MarketCard.test.tsx
├── app/
│ └── api/
│ └── markets/
│ ├── route.ts
│ └── route.test.ts # 整合測試
└── e2e/
├── markets.spec.ts # 端對端測試
├── trading.spec.ts
└── auth.spec.ts
模擬外部服務
Supabase 模擬
jest.mock('@/lib/supabase', () => ({
supabase: {
from: jest.fn(() => ({
select: jest.fn(() => ({
eq: jest.fn(() => Promise.resolve({
data: [{ id: 1, name: '測試市場' }],
error: null
}))
}))
}))
}
}))
Redis 模擬
jest.mock('@/lib/redis', () => ({
searchMarketsByVector: jest.fn(() => Promise.resolve([
{ slug: 'test-market', similarity_score: 0.95 }
])),
checkRedisHealth: jest.fn(() => Promise.resolve({ connected: true }))
}))
OpenAI 模擬
jest.mock('@/lib/openai', () => ({
generateEmbedding: jest.fn(() => Promise.resolve(
new Array(1536).fill(0.1) // 模擬 1536 維嵌入
))
}))
測試覆蓋率驗證
執行覆蓋率報告
<coverage>
覆蓋率閾值
{
"jest": {
"coverageThresholds": {
"global": {
"branches": 80,
"functions": 80,
"lines": 80,
"statements": 80
}
}
}
}
應避免的常見測試錯誤
失敗:錯誤:測試實作細節
// 不要測試內部狀態
expect(component.state.count).toBe(5)
通過:正確:測試使用者可見行為
// 測試使用者看到的內容
expect(screen.getByText('計數:5')).toBeInTheDocument()
失敗:錯誤:脆弱的選擇器
// 容易斷裂
await page.click('.css-class-xyz')
通過:正確:語義選擇器
// 對變更有彈性
await page.click('button:has-text("提交")')
await page.click('[data-testid="submit-button"]')
失敗:錯誤:測試未隔離
// 測試彼此依賴
test('建立使用者', () => { /* ... */ })
test('更新同一個使用者', () => { /* 依賴前一個測試 */ })
通過:正確:獨立測試
// 每個測試設定自己的資料
test('建立使用者', () => {
const user = createTestUser()
// 測試邏輯
})
test('更新使用者', () => {
const user = createTestUser()
// 更新邏輯
})
持續測試
開發期間的監看模式
<test-watch>
# 檔案變更時自動執行測試
預先提交掛鉤
# 在每次提交前執行
<test> && <lint>
CI/CD 整合
# GitHub Actions
- name: 執行測試
run: <coverage>
- name: 上傳覆蓋率
uses: codecov/codecov-action@v3
最佳實踐
- 先寫測試 - 一律 TDD
- 每個測試一個斷言 - 專注於單一行為
- 描述性測試名稱 - 解釋測試的內容
- 安排-行動-斷言 - 清晰的測試結構
- 模擬外部依賴項 - 隔離單元測試
- 測試邊緣案例 - null、undefined、空值、大量
- 測試錯誤路徑 - 不僅是快樂路徑
- 保持測試快速 - 單元測試每個 < 50ms
- 測試後清理 - 無副作用
- 檢視覆蓋率報告 - 找出缺口
成功指標
- 達到 80%+ 程式碼覆蓋率
- 所有測試通過(綠燈)
- 沒有跳過或停用的測試
- 快速測試執行(單元測試 < 30s)
- 端對端測試涵蓋關鍵使用者流程
- 測試在部署到生產環境前捕捉錯誤
請記住:測試不是可選的。它們是安全網,讓我們能夠自信地重構、快速開發並確保生產可靠性。