Community研究與資料分析github.com

sametcelikbicak/flaky-test-detector

偵測、分析並消除各種測試框架中的不穩定測試(Flaky Test)。此 AI 代理技能能夠識別非確定性的測試失敗、分類根本原因,並套用針對性的修復方法。

flaky-test-detector 是什麼?

這是一個專門用於偵測、分析並修復不穩定測試(Flaky Test)的 AI 代理技能。它支援多種主流測試框架,包括 Vitest、Jest、Playwright、Cypress、Mocha 和 AVA。此技能會循環執行測試套件以找出不一致的測試案例,然後根據非同步時序、共享可變狀態、測試隔離、環境敏感性或競爭條件等常見不穩定類型進行分類。接著,它會根據分類結果自動套用經過驗證的修復策略,例如使用 `waitFor` 取代固定逾時、在 `beforeEach` 中重置狀態,或模擬時區與網路請求。最後,技能會驗證修復效果,並產生一份詳細的「不穩定測試報告」(FLAKY_REPORT.md),摘要說明受影響的測試、根本原因類別、修復狀態以及整體穩定度。使用者可以透過自然語言描述問題來啟動此技能,例如「我們的 CI 充滿了不穩定的測試,我們使用 Vitest」或「Playwright 的端對端測試在 CI 上不穩定」。

相容平台✓Claude Code~Codex CLI✓Cursor✓OpenCode✓Windsurf
npx skills add sametcelikbicak/flaky-test-detector

Installed? Explore more 研究與資料分析 skills: affaan-m/uspto-database, affaan-m/scholar-evaluation, affaan-m/literature-review · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

不穩定測試偵測器 (Flaky Test Detector)

識別、診斷並消除不穩定的測試。它會多次執行你的測試套件,隔離非確定性的失敗,對根本原因進行分類,並套用有針對性的修復方法。

流程 (Pipeline)

  1. 偵測 測試執行器與設定
  2. 收集 透過重複執行來找出不穩定的候選測試
  3. 分析 失敗模式以識別根本原因
  4. 修復 針對每個不穩定類別套用經過驗證的策略
  5. 驗證 透過重新執行偵測循環來確認修復效果

階段 1:偵測測試執行器與設定

讀取專案設定:

cat package.json

識別測試執行器:

指示標誌執行器基本指令
"vitest" 在 devDependencies 中Vitestnpx vitest
"jest" 在 devDependencies 中Jestnpx jest
"react-scripts" 在 devDependencies 中react-scriptsnpx react-scripts test
"@playwright/test" 在 devDependencies 中Playwrightnpx playwright test
"cypress" 在 devDependencies 中Cypressnpx cypress run
"mocha" 在 devDependencies 中Mochanpx mocha
"ava" 在 devDependencies 中AVAnpx 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」

代理程式動作:

  1. 使用迴圈執行 npx vitest --reporter=json 3 次
  2. 偵測到 4 個測試在各次執行中通過/失敗不一致
  3. 對於 auth.test.ts:grep 顯示在斷言前有 setTimeout(500)
  4. 將其替換為 waitFor — auth.test.ts 現在在 3 次執行中保持一致
  5. 對於 api.test.ts:模組層級的驗證 token 在測試之間洩漏
  6. 新增 beforeEach(() => localStorage.clear()) — 穩定
  7. 在 vitest.config.ts 中設定 CI 重試次數為 2
  8. 驗證:所有 4 個先前不穩定的測試都一致通過
  9. 顯示報告

使用者:「Playwright 的端對端測試在 CI 上不穩定」

代理程式動作:

  1. 執行 npx playwright test --reporter=json 3 次,識別出 login.spec.ts 不穩定
  2. 分析:使用了 page.waitForTimeout(3000) — 非同步時序問題
  3. 將其替換為 await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 })
  4. 在 CI 的 playwright.config.ts 中設定 retries: 2
  5. 同時偵測到 user-profile.spec.ts — 環境敏感性(時區)
  6. 在測試設定中模擬時區
  7. 驗證:兩個測試在 3/3 次執行中皆通過

相關技能