Community程式設計與開發github.com

測試準則

編碼技能。編寫測試或進行 TDD:新功能、錯誤修復、重構。強制執行測試優先開發,並達到單元測試、整合測試和端對端測試 80% 以上的覆蓋率。可透過 /tests-guidelines、「tests」、「coverage」、「unit test」、「integration test」、「TDD」觸發。

測試準則 是什麼?

此技能建立一個嚴謹的測試驅動開發 (TDD) 工作流程,強制在編寫任何實作程式碼之前先撰寫測試。它支援三種測試類型:用於個別函式和元件的單元測試、用於 API 端點和資料庫操作的整合測試,以及使用 Playwright 用於關鍵使用者流程的端對端測試。此技能會自動偵測專案的測試執行器(npm、pnpm、yarn、Bun 原生或 Python/Go/Rust 生態系統),並使用適當的指令,從而消除配置錯誤。明確的紅/綠/重構循環、80% 以上的覆蓋率閾值,以及關於測試隔離和語義選擇器的最佳實踐指南,有助於開發人員維護可靠的測試套件。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/orenatobr/tests-guidelines/tree/HEAD/skills/tests-guidelines

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

測試驅動開發工作流程

此技能確保所有程式碼開發都遵循 TDD 原則,並具有全面的測試覆蓋率。

啟動時機

  • 編寫新功能或功能
  • 修復錯誤或問題
  • 重構現有程式碼
  • 新增 API 端點
  • 建立新元件

核心原則

1. 測試先於程式碼

一律先撰寫測試,然後再實作程式碼以使測試通過。

2. 覆蓋率要求

  • 最低 80% 覆蓋率(單元 + 整合 + 端對端)
  • 涵蓋所有邊緣案例
  • 測試錯誤情境
  • 驗證邊界條件

3. 測試類型

單元測試

  • 個別函數和工具程式
  • 元件邏輯
  • 純函數
  • 輔助程式和工具程式

整合測試

  • API 端點
  • 資料庫操作
  • 服務互動
  • 外部 API 呼叫

端對端測試(Playwright)

  • 關鍵使用者流程
  • 完整工作流程
  • 瀏覽器自動化
  • UI 互動

TDD 工作流程步驟

步驟 0:偵測測試執行器

不要假設使用 npm test。以下步驟和範例中的指令使用 <test>、<test-watch> 和 <coverage> 作為專案實際執行器的佔位符。在開始前先解析一次:

  1. 找到專案的執行器。 讀取 package.json(packageManager、scripts.test)、lockfile、pyproject.toml / pytest.ini、go.mod、Cargo.toml。首先匹配到的就是;不要假設使用 npm test。

  2. 區分套件管理器和測試執行器。它們並不相同。 一個專案可能使用 Bun 安裝依賴項,但仍執行 Jest 或 Vitest。檢查 package.json scripts.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>
npmnpm testnpm test -- --watchnpm run test:coveragenpm run lint
pnpmpnpm testpnpm test --watchpnpm test:coveragepnpm lint
yarnyarn testyarn test --watchyarn test:coverageyarn lint
Bun(腳本執行 jest/vitest)bun run testbun run test --watchbun run test:coveragebun run lint
Bun(原生 bun:test)bun testbun test --watchbun test --coveragebun run lint

bun test(Bun 的內建執行器)不同於 bun run test(執行 package.json test 腳本)。選錯是常見的失敗原因 - 例如,在僅限 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

最佳實踐

  1. 先寫測試 - 一律 TDD
  2. 每個測試一個斷言 - 專注於單一行為
  3. 描述性測試名稱 - 解釋測試的內容
  4. 安排-行動-斷言 - 清晰的測試結構
  5. 模擬外部依賴項 - 隔離單元測試
  6. 測試邊緣案例 - null、undefined、空值、大量
  7. 測試錯誤路徑 - 不僅是快樂路徑
  8. 保持測試快速 - 單元測試每個 < 50ms
  9. 測試後清理 - 無副作用
  10. 檢視覆蓋率報告 - 找出缺口

成功指標

  • 達到 80%+ 程式碼覆蓋率
  • 所有測試通過(綠燈)
  • 沒有跳過或停用的測試
  • 快速測試執行(單元測試 < 30s)
  • 端對端測試涵蓋關鍵使用者流程
  • 測試在部署到生產環境前捕捉錯誤

請記住:測試不是可選的。它們是安全網,讓我們能夠自信地重構、快速開發並確保生產可靠性。

相關技能