telegram-bot-workers/TESTING_INSTALLATION.md

테스트 인프라 설치 가이드

개요

이 문서는 deposit-agent.ts에 대한 포괄적인 단위 테스트를 위한 Vitest + Miniflare 환경 설정 가이드입니다.

생성된 파일

telegram-bot-workers/
├── vitest.config.ts           # Vitest 설정 (Miniflare 환경)
├── tests/
│   ├── setup.ts              # D1 Database 초기화 및 헬퍼 함수
│   ├── deposit-agent.test.ts # 예치금 시스템 테스트 (50+ cases)
│   └── README.md             # 테스트 가이드
├── package.json              # 업데이트됨 (vitest, miniflare 추가)
├── README.md                 # 업데이트됨 (테스트 섹션 추가)
├── CLAUDE.md                 # 업데이트됨 (테스트 명령어 추가)
└── TESTING_INSTALLATION.md   # 이 파일

설치 단계

1. 의존성 설치

npm install

새로 추가된 패키지:

• vitest@^1.2.0 - 테스트 러너
• miniflare@^3.20231030.0 - Cloudflare Workers 시뮬레이터
• @cloudflare/vitest-pool-workers@^0.1.0 - Vitest Workers 통합
• @vitest/coverage-v8@^1.2.0 - 커버리지 리포트

2. 테스트 실행

# 모든 테스트 실행
npm test

# Watch 모드 (개발 중)
npm run test:watch

# 커버리지 리포트
npm run test:coverage

3. 예상 출력

✓ tests/deposit-agent.test.ts (50+)
  ✓ executeDepositFunction
    ✓ get_balance (2)
    ✓ get_account_info (1)
    ✓ request_deposit - Negative Amount Validation (4)
    ✓ request_deposit - 7-Character Prefix Matching (4)
    ✓ request_deposit - Pending Transaction (2)
    ✓ request_deposit - Batch Failure Handling (1)
    ✓ get_transactions (5)
    ✓ cancel_transaction (5)
    ✓ Admin Functions - Permission Checks (3)
    ✓ Admin Functions - get_pending_list (2)
    ✓ Admin Functions - confirm_deposit (3)
    ✓ Admin Functions - reject_deposit (2)
    ✓ Concurrency Safety (2)
    ✓ Edge Cases (4)
    ✓ Unknown Function (1)

Test Files  1 passed (1)
     Tests  50+ passed (50+)
   Duration  < 10s

테스트 범위

금융 작업 안전성

✅ 음수 금액 거부

• 음수 입금 시도 → 에러 반환
• 0원 입금 시도 → 에러 반환
• 누락된 금액/입금자명 → 에러 반환

✅ 동시성 처리 안전성

• 동일 사용자의 동시 입금 요청
• Race condition 시뮬레이션
• 3개 동시 요청 처리 검증

✅ 부분 배치 실패 처리

• db.batch() 일부 실패 시뮬레이션
• allSuccessful 검증 로직
• 에러 throw 및 로깅 확인

✅ 입금자명 7글자 매칭

• "홍길동아버지님" (8글자) → "홍길동아버지" (7글자) 자동 매칭
• depositor_name_prefix 컬럼 활용
• 금액/이름 불일치 시나리오

✅ 관리자 권한 검증

• 비관리자의 get_pending_list 차단
• 비관리자의 confirm_deposit 차단
• 비관리자의 reject_deposit 차단

✅ 거래 상태 검증

• confirmed 거래 취소 차단
• pending 거래만 확인/거절 허용
• 다른 사용자 거래 취소 차단

✅ Edge Cases

• 999,999,999원 (매우 큰 금액)
• "홍길동(주)" (특수문자)
• "김" (1글자 이름)
• "1234567" (정확히 7글자)

Mock 전략

D1 Database

Miniflare가 자동으로 in-memory SQLite 제공:

• schema.sql 자동 로드 (beforeAll)
• 각 테스트 후 데이터 정리 (afterEach)
• 실제 SQL 쿼리 실행 가능

환경 변수

vitest.config.ts에서 바인딩:

bindings: {
  BOT_TOKEN: 'test-bot-token',
  WEBHOOK_SECRET: 'test-webhook-secret',
  OPENAI_API_KEY: 'test-openai-key',
  DEPOSIT_ADMIN_ID: '999999999',
}

헬퍼 함수

tests/setup.ts:

createTestUser(telegramId, username)        // 사용자 생성
createBankNotification(depositorName, amount) // 은행 알림 생성
createDepositTransaction(userId, amount, status) // 거래 생성
getTestDB()                                  // DB 바인딩

디버깅

실패한 테스트 확인

npm test -- --reporter=verbose

특정 테스트만 실행

# 파일명 필터링
npm test deposit-agent

# 테스트 설명 필터링
npm test -- -t "should reject negative amounts"

로그 출력

it('debugging test', async () => {
  const result = await executeDepositFunction(...);
  console.log('Result:', result); // 출력됨
  expect(result).toBeDefined();
});

커버리지 리포트

npm run test:coverage

출력:

• coverage/ 디렉토리에 HTML 리포트 생성
• 브라우저로 coverage/index.html 열기

문제 해결

"Cannot find module" 에러

rm -rf node_modules package-lock.json
npm install

Miniflare 버전 충돌

package.json 확인:

{
  "miniflare": "^3.20231030.0",
  "@cloudflare/vitest-pool-workers": "^0.1.0"
}

D1 스키마 초기화 실패

tests/setup.ts에서 경로 확인:

const schemaPath = join(__dirname, '../schema.sql');

테스트 타임아웃

vitest.config.ts 수정:

test: {
  testTimeout: 10000, // 기본 5초 → 10초
}

다음 단계

추가 테스트 작성

1. openai-service.ts

   • Function Calling 도구 테스트
   • AI 응답 생성 테스트

2. summary-service.ts

   • 프로필 업데이트 로직
   • 3개 요약 통합 테스트

3. Integration Tests

   • Webhook → AI → DB 전체 플로우
   • Email Handler 파싱 테스트

CI/CD 통합

GitHub Actions (.github/workflows/test.yml):

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm install
      - run: npm test
      - run: npm run test:coverage
      - uses: codecov/codecov-action@v3

참고 자료

• Vitest 공식 문서
• Miniflare 공식 문서
• Cloudflare Workers Testing Guide
• Project README - 프로젝트 개요 및 기능
• Developer Guide - 개발 환경 설정
• Tests README - 테스트 상세 가이드

완료 체크리스트

• vitest.config.ts 생성
• tests/setup.ts 생성 (D1 초기화)
• tests/deposit-agent.test.ts 생성 (50+ test cases)
• package.json 업데이트 (의존성 추가)
• README.md 업데이트 (테스트 섹션)
• CLAUDE.md 업데이트 (명령어 추가)
• tests/README.md 생성 (가이드)
• .gitignore 확인 (coverage/ 제외)

성공 기준

✅ 모든 테스트 통과 (npm test) ✅ 커버리지 리포트 생성 가능 (npm run test:coverage) ✅ 플래키 테스트 없음 (결정론적 결과) ✅ 테스트 실행 시간 <10초 ✅ 명확한 테스트 설명 및 에러 메시지