Community研究&データ分析github.com

sametcelikbicak/flaky-test-detector

任意のテストランナーでフレーキーテストを検出、分析、排除します。非決定的なテスト失敗を特定し、根本原因を分類し、的を絞った修正を適用するAIエージェントスキルです。

flaky-test-detector とは?

このスキルは、テストスイート内のフレーキーテスト(不安定なテスト)を自動的に検出、診断、修正するためのAIエージェント向けツールです。Vitest、Jest、Playwright、Cypress、Mocha、AVAなど、主要なテストランナーをサポートしています。パイプラインは、テストランナーの検出、複数回のテスト実行によるフレーキー候補の収集、失敗パターンの分析による根本原因の特定(非同期タイミング、共有可変状態、テスト分離、環境依存、競合状態の5カテゴリ)、カテゴリに応じた修正の適用、そして修正後の再検証という6つのフェーズで構成されています。さらに、CI用のリトライ設定や最終的なレポート生成も自動化します。これにより、開発者はフレーキーテストの手動デバッグにかかる時間を大幅に削減し、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に質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Flaky Test Detector

フレーキーテストを特定、診断、排除します。テストスイートを複数回実行し、非決定的な失敗を分離し、根本原因を分類し、的を絞った修正を適用します。

パイプライン

  1. 検出: ランナーと設定を検出
  2. 収集: 繰り返し実行によりフレーキー候補を収集
  3. 分析: 失敗パターンを分析して根本原因を特定
  4. 修正: 各フレーキーカテゴリに対して実証済みの戦略を適用
  5. 検証: 検出ループを再実行して修正を確認

フェーズ 1: ランナーと設定の検出

プロジェクトのセットアップを読み取ります:

cat package.json

テストランナーを特定します:

指標ランナー基本コマンド
"vitest" in devDependenciesVitestnpx vitest
"jest" in devDependenciesJestnpx jest
"react-scripts" in devDependenciesreact-scriptsnpx react-scripts test
"@playwright/test" in devDependenciesPlaywrightnpx playwright test
"cypress" in devDependenciesCypressnpx cypress run
"mocha" in devDependenciesMochanpx mocha
"ava" in devDependenciesAVAnpx 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 "=== RUN $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 "=== RUN $i ==="
  npx jest --json 2>/dev/null | tee ".flaky-run-$i.json"
done

Playwrightの場合:

for i in 1 2 3; do
  echo "=== RUN $i ==="
  npx playwright test --reporter=json 2>/dev/null | tee ".flaky-run-$i.json"
done

実行結果を収集し、以下を特定します:

  • 常に成功 — 安定、分析から除外
  • 常に失敗 — 壊れたテスト、別途報告
  • 成功したり失敗したりする — フレーキー候補

フェーズ 3: 根本原因の分析

各フレーキー候補について、症状別に分類します:

カテゴリ A: 非同期タイミング

症状:

  • ローカルでは成功するがCIでは失敗する(遅い環境)
  • タイムアウト、setTimeout、setInterval、requestAnimationFrame に関する失敗
  • ブラウザテストでDOMアサーションが断続的に失敗する

診断:

# テストファイル内の非同期パターンをgrep

探すべき点:

  • ポーリング/リトライの代わりに固定タイムアウトを使用
  • Vitestでの waitFor または expect.poll の欠如
  • Testing Libraryでの waitFor / findBy* の欠如
  • 非同期操作が完了する前のアサーション

カテゴリ B: 共有可変状態

症状:

  • テストの順序に依存して失敗する(--shard または --bail 1 を実行すると結果が変わる)
  • 単独では成功するが、全スイートでは失敗する
  • モジュールレベルの変数、シングルトン、グローバル変数

診断:

# 共有状態パターンをチェック

探すべき点:

  • テスト間でリセットされないテストレベルの変数
  • テスト間でリークするモック状態(vi.fn() / jest.fn() がクリアされていない)
  • 復元されない環境変数の変更
  • クリーンアップされていないファイルシステムまたはデータベースの状態

カテゴリ C: テスト分離

症状:

  • --testPathPattern=<single-file> では成功するが、全スイートでは失敗する
  • 特定の他のテストがその前に実行されるとテストが失敗する

診断: ランダムな順序でテストを実行して確認:

# Vitest (順次 + ランダム)
npx vitest --sequence=sequential --reporter=json 2>/dev/null
npx vitest --sequence=random --reporter=json 2>/dev/null

探すべき点:

  • beforeEach / afterEach によるクリーンアップの欠如
  • DOMやグローバルを復元せずに変更するテスト
  • テストごとに分離されていないデータベース/シードデータ
  • リークするモック実装(vi.restoreAllMocks() / jest.restoreAllMocks() の欠如)

カテゴリ D: 環境依存

症状:

  • CIでのみ失敗する(ローカルでは決して失敗しない)
  • 特定のOS/ブラウザの組み合わせで失敗する
  • 特定の時間に失敗する(タイムゾーン、日付依存)

診断: 探すべき点:

  • ハードコードされた時刻/日付の値
  • ロケール固有のフォーマット
  • タイムゾーン依存のアサーション
  • 画面解像度、ビューポートサイズの前提
  • Node.js/Pythonバージョン固有の動作
  • ネットワーク依存のテスト(API呼び出し、レート制限)

カテゴリ E: 競合状態

症状:

  • 同時操作、Web Worker、または並列リクエストが関与する失敗
  • Promise.all、Promise.race、遅延0msの setTimeout
  • 共有エミッター上のイベントリスナー

診断:


フェーズ 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('flaky file', () => { ... })

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 "=== RUN $i ==="
  npx vitest --reporter=json 2>/dev/null | tee ".flaky-verify-$i.json"
done

実行結果を比較:

  • フレーキーテストゼロ — 成功、修正数を報告
  • 残りのフレーキーテスト — フェーズ3に戻り、より深い分析を実施

FLAKY_REPORT.md の生成

修正後、サマリーレポートを生成:

# フレーキーテストレポート

| テスト | ランナー | カテゴリ | ステータス | 適用された修正 |
|------|--------|----------|--------|-------------|
| `auth.test.ts` | Vitest | 非同期タイミング | 修正済み | `setTimeout` を `waitFor` に置き換え |
| `api.test.ts` | Jest | 共有状態 | 修正済み | `beforeEach` クリーンアップを追加 |
| `login.spec.ts` | Playwright | 環境 | 隔離中 | APIモックのセットアップが必要 |

**安定率:** 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 の場合: モジュールレベルの認証トークンがテスト間でリークしている
  6. beforeEach(() => localStorage.clear()) を追加 — 安定
  7. vitest.config.ts でCIリトライ = 2 を設定
  8. 検証: 以前フレーキーだった4つのテストがすべて一貫して成功
  9. レポートを表示

ユーザー: 「PlaywrightのE2Eテストが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. playwright.config.ts でCI用に retries: 2 を設定
  5. user-profile.spec.ts も検出 — 環境依存(タイムゾーン)
  6. テストセットアップでタイムゾーンをモック化
  7. 検証: 両方のテストが3/3回成功

関連スキル