core2026/docs/integration-tests.md

통합 테스트

실행 명령

외부 서비스 없이 실행 가능한 integration:

pnpm test:integration

전용 PostgreSQL·Redis를 사용하는 조건부 suite:

pnpm test:integration:conditional

조건부 runner는 환경 변수 존재 여부만으로 안전성을 보장하지 않습니다. 대상 host, port, database와 Redis prefix가 해당 worktree 전용인지 확인해 주세요. Runner는 실행 ID가 포함된 game schema를 생성하고 성공, 테스트 실패, HUP, INT, TERM 종료에서 자신이 생성한 schema만 삭제합니다. 사용자가 schema 환경 변수를 지정한 경우에도 이미 존재하는 schema는 거부합니다. HTTP transport fixture의 Redis key도 실행 ID를 profile namespace에 포함하고, runner 종료 시 그 실행 ID에 속한 key만 삭제합니다. 공유 Redis 전체에 FLUSHDB나 FLUSHALL을 실행하지 않습니다. SIGKILL은 cleanup trap을 실행할 수 없으므로 자동 정리를 보장하지 않습니다.

준비

상위 작업공간의 개발 stack을 사용할 수 있습니다.

cd ../docker_compose_files/development
./scripts/prepare-instance.sh docs-check 15443 16389 ../../core2026
./scripts/compose.sh docs-check up -d --wait

cd ../../core2026
pnpm install --frozen-lockfile
pnpm --filter @sammo-ts/infra prisma:generate
pnpm --filter @sammo-ts/common build
pnpm --filter @sammo-ts/logic build
pnpm test:integration:conditional

Instance 이름과 port는 다른 worktree와 겹치지 않게 정합니다. 생성된 .env, .env.ci, log와 DB volume은 Git에 추가하지 않습니다.

HTTP lifecycle fixture는 disposable profile에 localAccountGeneralCreationGraceDays를 명시하고 실제 profile 정책을 통과합니다. PM2 orchestrator fixture는 전용 PM2_HOME을 사용하며, 다섯 runtime role을 삭제하고 PID와 명령행 및 daemon 종료를 확인한 뒤에만 임시 디렉터리를 정리합니다. 운영자의 전역 PM2 daemon과 경로를 공유하지 않습니다.

범위

통합 suite는 다음 경계를 포함합니다.

• gateway/game Prisma 연결과 schema
• Redis session, queue와 pub/sub
• scenario initialization과 profile schema
• InputEvent 원자성, 재시도와 중복 request
• turn daemon lease, heartbeat, fencing과 takeover
• 예약 턴 revision/CAS와 API/daemon 경합
• auth header, role, sanction과 owner별 HTTP transport
• ref/core command snapshot, RNG trace와 persistence
• auction, tournament와 worker transaction
• 관리자 시간 가속·연기의 durable action, checkpoint, Redis 부분 재시도와 경매 timer race

실제 포함 suite는 tools/run-conditional-integration.sh, 각 package의 package.json, *.integration.test.ts를 기준으로 확인합니다. DB 조건부 환경 변수는 tools/conditional-integration-registry.tsv에서 명시적으로 관리합니다. 새 *_DATABASE_URL gate가 registry에 없거나 registry 항목이 더 이상 테스트에 존재하지 않으면 runner가 테스트 실행 전에 실패합니다.

관리자 시간 조정의 PostgreSQL 경계는 runtimeClockShiftPersistence.integration.test.ts, gateway action PARTIAL → APPLIED 경계는 gatewayRuntimeAction.integration.test.ts입니다. Runner는 후자에 GATEWAY_RUNTIME_ACTION_DATABASE_URL, 전자에 INPUT_EVENT_DATABASE_URL을 같은 격리 schema URL로 주입합니다. 장수 생성, 선택 pool, 즉시 장수 action처럼 별도 marker를 사용하는 테스트도 registry를 통해 포함합니다. DB와 Redis가 함께 필요한 파일은 DB group에서 한 번만 실행하고 Redis-only 파일만 별도 group에서 실행합니다.

안전 경계

• Test는 game schema table을 truncate할 수 있습니다.
• Redis key 또는 선택한 DB index를 정리할 수 있습니다.
• 운영·공유 DB URL을 사용하지 않습니다.
• Volume 삭제는 사용자가 데이터 폐기를 명시한 경우에만 수행합니다.
• Secret과 펼쳐진 docker compose config 출력은 report나 artifact에 넣지 않습니다.

결과 해석

환경이 없어 skip된 test는 실행되지 않은 것입니다. Mock connector test는 실제 PostgreSQL·Redis 경계를 증명하지 않습니다. Full suite 실패는 변경 worktree와 변경 없는 main에서 각각 재현해 회귀와 baseline을 구분합니다.

조건부 runner는 마지막 줄에 통과, skip, 실패한 test file 수를 출력하며, 하나라도 file 전체가 skip되면 성공으로 처리하지 않습니다. 실행이 중단된 경우도 이미 완료된 group의 집계와 schema cleanup 결과를 확인해 주세요.

Ref 호환성 판정은 차등 검증, UI는 프론트엔드 호환 검증을 함께 사용합니다.