Community연구 & 데이터 분석github.com

sametcelikbicak/flaky-test-detector

모든 테스트 러너에서 불안정한 테스트(flakey test)를 탐지, 분석 및 제거합니다. 비결정적 테스트 실패를 식별하고, 근본 원인을 분류하며, 맞춤형 수정을 적용하는 AI 에이전트 스킬입니다.

flaky-test-detector란 무엇인가요?

이 스킬은 개발자가 CI/CD 파이프라인에서 가장 골칫거리인 불안정한 테스트(flakey test)를 체계적으로 식별하고 해결할 수 있도록 설계된 AI 에이전트 스킬입니다. Vitest, Jest, Playwright, Cypress, Mocha, AVA 등 널리 사용되는 모든 테스트 러너를 지원하며, 프로젝트 설정 파일을 자동으로 감지하여 적절한 명령어를 사용합니다. 스킬은 6단계 파이프라인으로 구성됩니다: 1) 테스트 러너 감지, 2) 반복 실행을 통한 후보 수집, 3) 실패 패턴 분석(비동기 타이밍, 공유 가변 상태, 테스트 격리 부족, 환경 민감성, 경쟁 조건으로 분류), 4) 근본 원인별 입증된 수정 전략 적용, 5) 재시도 설정 추가, 6) 수정 검증. 각 분석 단계는 특정 증상과 진단 명령어를 제공하며, 실제 diff 형식의 수정 예제를 포함하여 AI 에이전트가 바로 실행 가능한 지침을 제공합니다. 최종적으로 FLAKY_REPORT.md 형식의 보고서를 생성하여 팀과 결과를 공유할 수 있습니다.

지원 대상✓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

불안정한 테스트(flakey test)를 식별, 진단 및 제거합니다. 테스트 스위트를 여러 번 실행하고, 비결정적 실패를 격리하며, 근본 원인을 분류하고, 맞춤형 수정을 적용합니다.

파이프라인

  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에서 실패 (느린 환경)
  • 실패가 timeout, setTimeout, setInterval, requestAnimationFrame을 언급
  • 브라우저 테스트에서 DOM 단언이 간헐적으로 실패

진단:

# 테스트 파일에서 비동기 패턴 검색
grep -n "setTimeout\|setInterval\|waitFor\|delay\|sleep\|requestAnimationFrame\|transition\|animation" <test-file>

찾을 것:

  • 폴링/재시도 대신 고정 타임아웃 사용
  • Vitest에서 waitFor 또는 expect.poll 누락
  • Testing Library에서 waitFor / findBy* 누락
  • 비동기 작업 완료 전 단언 실행

범주 B: 공유 가변 상태

증상:

  • 실패가 테스트 순서에 의존 (--shard 또는 --bail 1 실행 시 결과 변화)
  • 테스트가 단독 실행 시 통과하지만 전체 스위트에서 실패
  • 모듈 수준 변수, 싱글톤, 전역 변수

진단:

# 공유 상태 패턴 확인
grep -n "let [a-z]* = \|var [a-z]* = \|const [a-z]* = \|global\." <test-file> | head -20

찾을 것:

  • 테스트 간 초기화되지 않은 테스트 수준 변수
  • 테스트 간 누출되는 목 상태 (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
  • 공유 이미터의 이벤트 리스너

진단:

grep -n "Promise\.all\|Promise\.race\|Promise\.any\|Promise\.allSettled\|setTimeout\|setImmediate\|process\.nextTick" <test-file>

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

실행 간 결과 비교:

  • 불안정 테스트 0개 — 성공, 수정된 개수 보고
  • 남은 불안정 테스트 — 더 깊은 분석을 위해 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에 retries: 2 설정 (CI용)
  5. 또한 user-profile.spec.ts 감지 — 환경 민감성 (시간대)
  6. 테스트 설정에서 시간대 모킹
  7. 검증: 두 테스트 모두 3/3 실행 통과

관련 스킬