core2026/docs/e2e-orchestrator-tests.md

Gateway orchestrator E2E

검증 대상

Gateway orchestrator는 PostgreSQL의 profile·operation 상태를 기준으로 commit worktree, build와 PM2 process를 조정합니다. 검증은 다음 경계를 나눕니다.

• app/gateway-api/test/orchestratorPlan.test.ts: profile 상태에서 필요한 process plan 계산
• orchestratorOperations.test.ts: operation claim, 상태 전이와 오류
• adminOperations.test.ts: 관리자 API와 operation 생성
• workspaceManager.test.ts: source commit과 worktree
• app/gateway-frontend/e2e/server-operations.spec.ts: 관리자 화면
• app/gateway-frontend/e2e/hwe-lifecycle.spec.ts: reset/build/seed/PM2와 두 사용자 게임 진입

Unit·mock test는 실제 Git, build, PM2, PostgreSQL, Redis와 브라우저를 모두 통과한 lifecycle을 증명하지 않습니다.

HWE lifecycle

hwe-lifecycle.spec.ts는 한 관리자와 독립된 두 사용자 browser context로 다음을 실행합니다.

1. 관리자가 gateway에 로그인합니다.
2. hwe:2 profile을 선택하고 full commit SHA로 reset operation을 요청합니다.
3. operation 완료와 HWE open 상태를 기다립니다.
4. 두 사용자가 각각 로그인하고 HWE로 이동합니다.
5. 각 사용자가 장수를 생성하고 game dashboard에 진입합니다.

비밀번호는 ignored secret directory의 파일에서 읽습니다.

SAMMO_LIFECYCLE_SECRET_ROOT/
├─ admin_password
├─ user_a_password
└─ user_b_password

Secret file은 mode 0600을 사용하고 값은 명령행·log·screenshot에 넣지 않습니다. SAMMO_LIFECYCLE_SOURCE_COMMIT에는 전체 commit SHA를 전달합니다.

Build 계약

Gateway frontend:

VITE_APP_BASE_PATH=/gateway \
VITE_GATEWAY_API_URL=/gateway/api/trpc \
VITE_GAME_API_URL_TEMPLATE='/{profile}/api/trpc' \
VITE_GAME_WEB_URL_TEMPLATE='/{profile}/' \
pnpm --filter @sammo-ts/gateway-frontend build

HWE frontend:

VITE_APP_BASE_PATH=/hwe \
VITE_GAME_API_URL=/hwe/api/trpc \
VITE_GAME_SSE_URL=/hwe/api/events \
pnpm --filter @sammo-ts/game-frontend build

Lifecycle suite는 PostgreSQL, Redis, gateway API, orchestrator, PM2와 두 frontend preview를 격리된 포트·schema·Redis prefix로 준비한 뒤 실행합니다.

SAMMO_LIFECYCLE_SECRET_ROOT=/path/to/ignored/secrets \
SAMMO_LIFECYCLE_SOURCE_COMMIT="$(git rev-parse HEAD)" \
pnpm --filter @sammo-ts/gateway-frontend test:e2e:hwe-lifecycle

Playwright용 prefix proxy는 app/gateway-frontend/e2e/prefix-proxy.mjs이며 기본 port는 15140입니다. 외부 Caddy를 통과하지 않으므로 suite 성공과 외부 HTTPS·host·firewall 검증을 구분합니다.

확인 항목

• operation의 requested/running/succeeded 또는 failed 상태
• resolved commit과 build workspace
• sammo:<profileName>:game-api, sammo:<profileName>:turn-daemon process
• game API와 daemon의 profile name 일치
• 관리자 capability와 일반 사용자 거부
• 두 사용자의 서로 분리된 session·장수 소유권
• 실패 시 secret이 없는 operation error와 PM2 log

Cleanup은 이 suite가 만든 process, worktree, schema와 Redis prefix만 대상으로 합니다. 공유 PM2 process, DB, Redis나 worktree를 이름 추정으로 삭제하지 않습니다.