Flaky Test Detector
불안정한 테스트(flakey test)를 식별, 진단 및 제거합니다. 테스트 스위트를 여러 번 실행하고, 비결정적 실패를 격리하며, 근본 원인을 분류하고, 맞춤형 수정을 적용합니다.
파이프라인
- 감지 러너 및 구성
- 수집 반복 실행을 통한 불안정 후보
- 분석 실패 패턴을 분석하여 근본 원인 식별
- 수정 각 불안정 유형에 대한 입증된 전략 적용
- 검증 감지 루프를 재실행하여 수정 확인
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에서 실패 (느린 환경)
- 실패가 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를 사용합니다"
에이전트 작업:
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에retries: 2설정 (CI용)- 또한
user-profile.spec.ts감지 — 환경 민감성 (시간대) - 테스트 설정에서 시간대 모킹
- 검증: 두 테스트 모두 3/3 실행 통과