Flaky Test Detector
フレーキーテストを特定、診断、排除します。テストスイートを複数回実行し、非決定的な失敗を分離し、根本原因を分類し、的を絞った修正を適用します。
パイプライン
- 検出: ランナーと設定を検出
- 収集: 繰り返し実行によりフレーキー候補を収集
- 分析: 失敗パターンを分析して根本原因を特定
- 修正: 各フレーキーカテゴリに対して実証済みの戦略を適用
- 検証: 検出ループを再実行して修正を確認
フェーズ 1: ランナーと設定の検出
プロジェクトのセットアップを読み取ります:
cat package.json
テストランナーを特定します:
| 指標 | ランナー | 基本コマンド |
|---|---|---|
"vitest" in devDependencies | Vitest | npx vitest |
"jest" in devDependencies | Jest | npx jest |
"react-scripts" in devDependencies | react-scripts | npx react-scripts test |
"@playwright/test" in devDependencies | Playwright | npx playwright test |
"cypress" in devDependencies | Cypress | npx cypress run |
"mocha" in devDependencies | Mocha | npx mocha |
"ava" in 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 "=== 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を使っています」
エージェントのアクション:
npx vitest --reporter=jsonをループで3回実行- 4つのテストが実行ごとに成功/失敗が一貫していないことを検出
auth.test.tsの場合: grepでsetTimeout(500)がアサーションの前にあることを確認waitForに置き換え —auth.test.tsが3回の実行で一貫するようになるapi.test.tsの場合: モジュールレベルの認証トークンがテスト間でリークしているbeforeEach(() => localStorage.clear())を追加 — 安定vitest.config.tsでCIリトライ = 2 を設定- 検証: 以前フレーキーだった4つのテストがすべて一貫して成功
- レポートを表示
ユーザー: 「PlaywrightのE2EテストがCIでフレーキーです」
エージェントのアクション:
npx playwright test --reporter=jsonを3回実行し、login.spec.tsがフレーキーであることを特定- 分析:
page.waitForTimeout(3000)を使用 — 非同期タイミングの問題 await expect(page.locator('.dashboard')).toBeVisible({ timeout: 15000 })に置き換えplaywright.config.tsでCI用にretries: 2を設定user-profile.spec.tsも検出 — 環境依存(タイムゾーン)- テストセットアップでタイムゾーンをモック化
- 検証: 両方のテストが3/3回成功