不穩定測試偵測器 (Flaky Test Detector)
識別、診斷並消除不穩定的測試。它會多次執行你的測試套件,隔離非確定性的失敗,對根本原因進行分類,並套用有針對性的修復方法。
流程 (Pipeline)
- 偵測 測試執行器與設定
- 收集 透過重複執行來找出不穩定的候選測試
- 分析 失敗模式以識別根本原因
- 修復 針對每個不穩定類別套用經過驗證的策略
- 驗證 透過重新執行偵測循環來確認修復效果
階段 1:偵測測試執行器與設定
讀取專案設定:
cat package.json
識別測試執行器:
| 指示標誌 | 執行器 | 基本指令 |
|---|---|---|
"vitest" 在 devDependencies 中 | Vitest | npx vitest |
"jest" 在 devDependencies 中 | Jest | npx jest |
"react-scripts" 在 devDependencies 中 | react-scripts | npx react-scripts test |
"@playwright/test" 在 devDependencies 中 | Playwright | npx playwright test |
"cypress" 在 devDependencies 中 | Cypress | npx cypress run |
"mocha" 在 devDependencies 中 | Mocha | npx mocha |
"ava" 在 devDependencies 中 | AVA | npx ava |
檢查現有的重試/不穩定設定:
- Vitest:
vitest.config.ts中的retry - Jest:
jest.config.ts中的testRetry或設定檔中的jest.retryTimes() - Playwright:
playwright.config.ts中的retries - Cypress:
cypress.config.ts中的retries
階段 2:收集不穩定的候選測試
多次執行完整測試套件並收集失敗結果:
# 執行 3 次以上,記錄每次結果
for i in 1 2 3; do
echo "=== 第 $i 次執行 ==="
npx vitest --reporter=json 2>/dev/null | tee ".flaky-run-$i.json"
done
快速檢查上次失敗的執行:
npx vitest --reporter=json 2>/dev/null | tee ".flaky-last-run.json"
對於 Jest:
for i in 1 2 3; do
echo "=== 第 $i 次執行 ==="
npx jest --json 2>/dev/null | tee ".flaky-run-$i.json"
done
對於 Playwright:
for i in 1 2 3; do
echo "=== 第 $i 次執行 ==="
npx playwright test --reporter=json 2>/dev/null | tee ".flaky-run-$i.json"
done
收集各次執行的測試結果,並識別:
- 總是通過 — 穩定,從分析中排除
- 總是失敗 — 損壞的測試,單獨報告
- 有時通過,有時失敗 — 不穩定的候選測試
階段 3:分析根本原因
對於每個不穩定的候選測試,根據症狀進行分類:
類別 A:非同步時序 (Async timing)
症狀:
- 測試在本地通過,但在 CI 上失敗(較慢的環境)
- 失敗訊息提及 timeout、
setTimeout、setInterval、requestAnimationFrame - DOM 斷言在瀏覽器測試中間歇性失敗
診斷:
# 在測試檔案中搜尋非同步模式
grep -n "setTimeout\|setInterval\|waitFor\|delay\|sleep\|requestAnimationFrame\|transition\|animation" <測試檔案>
尋找以下模式:
- 使用固定逾時而非輪詢/重試
- 在 Vitest 中缺少
waitFor或expect.poll - 在 Testing Library 中缺少
waitFor/findBy* - 在非同步操作完成之前就進行斷言
類別 B:共享可變狀態 (Shared mutable state)
症狀:
- 失敗取決於測試執行順序(使用
--shard或--bail 1會改變結果) - 測試單獨執行通過,但在完整套件中失敗
- 模組層級變數、單例、全域變數
診斷:
# 檢查共享狀態模式
grep -n "let [a-z]* = \|var [a-z]* = \|const [a-z]* = \|global\." <測試檔案> | head -20
尋找以下模式:
- 測試層級的變數未在測試之間重置
- Mock 狀態洩漏到其他測試(
vi.fn()/jest.fn()未清除) - 環境變數的變更未恢復
- 檔案系統或資料庫狀態未清理
類別 C:測試隔離 (Test isolation)
症狀:
- 使用
--testPathPattern=<單一檔案>測試通過,但在完整套件中失敗 - 當特定其他測試在其之前執行時,測試會失敗
診斷: 以隨機順序執行測試來確認:
# Vitest(順序 + 隨機)
npx vitest --sequence=sequential --reporter=json 2>/dev/null
npx vitest --sequence=random --reporter=json 2>/dev/null
尋找以下模式:
- 缺少
beforeEach/afterEach清理 - 測試修改 DOM 或全域變數後未恢復
- 資料庫/種子資料未為每個測試隔離
- Mock 實作洩漏(缺少
vi.restoreAllMocks()/jest.restoreAllMocks())
類別 D:環境敏感性 (Environment sensitivity)
症狀:
- 僅在 CI 上失敗(從不在本地)
- 在特定的作業系統/瀏覽器組合上失敗
- 在特定時間失敗(時區、日期相關)
診斷: 尋找以下模式:
- 硬編碼的時間/日期值
- 特定於語言環境的格式化
- 依賴時區的斷言
- 螢幕解析度、視窗大小的假設
- Node.js/Python 版本特定的行為
- 依賴網路的測試(API 呼叫、速率限制)
類別 E:競爭條件 (Race conditions)
症狀:
- 失敗涉及並發操作、Web Worker 或平行請求
Promise.all、Promise.race、延遲 0ms 的setTimeout- 共用發射器上的事件監聽器
診斷:
grep -n "Promise\.all\|Promise\.race\|Promise\.any\|Promise\.allSettled\|setTimeout\|setImmediate\|process\.nextTick" <測試檔案>
階段 4:套用修復
根據偵測到的類別來套用修復:
修復 A:非同步時序
替換脆弱的時序模式:
- await new Promise(r => setTimeout(r, 1000))
- expect(screen.getByText('Loaded')).toBeInTheDocument()
+ await waitFor(() => {
+ expect(screen.getByText('Loaded')).toBeInTheDocument()
+ }, { timeout: 5000, interval: 100 })
對於 Vitest,使用 expect.poll 或 waitFor:
import { waitFor } from '@testing-library/react'
// 或者 Vitest 內建:
await expect.poll(() => getStatus(), { timeout: 5000, interval: 100 }).toBe('done')
對於 Playwright,使用自動等待定位器:
// 不好:
await page.waitForTimeout(2000)
expect(await page.textContent('.status')).toBe('done')
// 好:
await expect(page.locator('.status')).toHaveText('done', { timeout: 10000 })
修復 B:共享可變狀態
+ import { vi } from 'vitest'
+
+ beforeEach(() => {
+ vi.clearAllMocks()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
重置模組層級狀態:
beforeEach(() => {
// 重置計數器、快取、單例
counter = 0
cache.clear()
})
隔離執行時期設定的變更:
const ORIGINAL_RUNTIME_MODE = getRuntimeMode()
afterEach(() => {
setRuntimeMode(ORIGINAL_RUNTIME_MODE)
})
修復 C:測試隔離
+ beforeEach(() => {
+ document.body.innerHTML = ''
+ localStorage.clear()
+ })
+
+ afterEach(() => {
+ vi.restoreAllMocks()
+ vi.useRealTimers()
+ })
對於基於資料庫的測試:
beforeEach(async () => {
await db.migrate.latest()
await db.seed.run()
})
afterEach(async () => {
await db.migrate.rollback()
})
修復 D:環境敏感性
模擬時間相關程式碼:
beforeEach(() => {
vi.useFakeTimers()
vi.setSystemTime(new Date('2024-01-15T12:00:00Z'))
})
afterEach(() => {
vi.useRealTimers()
})
對於語言環境敏感的測試:
import { locale } from '../i18n'
beforeEach(() => {
locale.set('en-US')
})
對於依賴網路的測試,模擬所有外部呼叫:
vi.mock('../api/client')
// 或
global.fetch = vi.fn()
修復 E:競爭條件
在測試中確保順序處理:
// 與其使用 Promise.all,不如順序測試
await operation1()
await operation2()
對於事件發射器測試:
const events: string[] = []
emitter.on('data', (d) => events.push(d))
emitter.emit('data', 'a')
emitter.emit('data', 'b')
await vi.waitFor(() => {
expect(events).toEqual(['a', 'b'])
})
階段 5:新增重試設定
在修復根本原因後,新增重試作為安全網。建議使用 CI 專用設定檔或 CI 工作指令,並直接寫入重試次數的數值,而不是在測試設定中讀取執行時期環境變數。
Vitest — vitest.ci.config.ts:
import baseConfig from './vitest.config'
export default defineConfig({
...baseConfig,
test: {
...baseConfig.test,
retry: 2,
// 不穩定測試的順序執行:
sequence: {
seed: 123,
shuffle: false,
},
},
})
在 CI 中使用 vitest --config vitest.ci.config.ts 執行。
或者使用 vi.retry() 針對特定測試/檔案:
vi.retry(2)
describe('不穩定的檔案', () => { ... })
Jest — jest.ci.config.ts(需要 jest-retry):
const baseConfig = require('./jest.config')
export default {
...baseConfig,
setupFilesAfterSetup: ['jest-retry'],
retryTimes: 2,
}
在 CI 中使用 jest --config jest.ci.config.ts 執行。
Playwright — playwright.ci.config.ts:
import baseConfig from './playwright.config'
export default defineConfig({
...baseConfig,
retries: 2,
})
在 CI 中使用 playwright test --config playwright.ci.config.ts 執行。
階段 6:驗證
重新執行不穩定測試的偵測循環:
for i in 1 2 3; do
echo "=== 第 $i 次執行 ==="
npx vitest --reporter=json 2>/dev/null | tee ".flaky-verify-$i.json"
done
比較各次執行的結果:
- 零個不穩定測試 — 成功,報告已修復的數量
- 仍有不穩定的測試 — 回到階段 3 進行更深入的分析
產生 FLAKY_REPORT.md
修復完成後,產生一份摘要報告:
# 不穩定測試報告 (Flaky Test Report)
| 測試 | 執行器 | 類別 | 狀態 | 套用的修復 |
|------|--------|----------|--------|-------------|
| `auth.test.ts` | Vitest | 非同步時序 | 已修復 | 將 `setTimeout` 替換為 `waitFor` |
| `api.test.ts` | Jest | 共享狀態 | 已修復 | 新增 `beforeEach` 清理 |
| `login.spec.ts` | Playwright | 環境敏感性 | 已隔離 | 需要設定 API Mock |
**穩定度比率:** 98/100 個測試 (98%)
**下一步:** 手動檢視其餘不穩定的測試
範例
使用者:「我們的 CI 充滿了不穩定的測試,我們使用 vitest」
代理程式動作:
- 使用迴圈執行
npx vitest --reporter=json3 次 - 偵測到 4 個測試在各次執行中通過/失敗不一致
- 對於
auth.test.ts:grep 顯示在斷言前有setTimeout(500) - 將其替換為
waitFor—auth.test.ts現在在 3 次執行中保持一致 - 對於
api.test.ts:模組層級的驗證 token 在測試之間洩漏 - 新增
beforeEach(() => localStorage.clear())— 穩定 - 在
vitest.config.ts中設定 CI 重試次數為 2 - 驗證:所有 4 個先前不穩定的測試都一致通過
- 顯示報告
使用者:「Playwright 的端對端測試在 CI 上不穩定」
代理程式動作:
- 執行
npx playwright test --reporter=json3 次,識別出login.spec.ts不穩定 - 分析:使用了
page.waitForTimeout(3000)— 非同步時序問題 - 將其替換為
await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 }) - 在 CI 的
playwright.config.ts中設定retries: 2 - 同時偵測到
user-profile.spec.ts— 環境敏感性(時區) - 在測試設定中模擬時區
- 驗證:兩個測試在 3/3 次執行中皆通過