core2026/docs/testing-policy.md

테스트 정책

원칙

• 변경한 계약과 가장 가까운 test부터 실행하고 범위를 넓힙니다.
• deterministic clock, seed와 fixture를 사용합니다.
• ref 호환성은 결과, 순서, RNG, 저장 상태와 출력으로 검증합니다.
• 인증·권한은 session actor, 소유권, role, sanction과 redaction을 포함합니다.
• DB 코드는 실제 PostgreSQL transaction과 reload 경로를 검증합니다.
• UI는 실제 Chromium에서 geometry, computed style과 interaction을 비교합니다.
• skip, baseline failure와 환경 미검증을 pass와 분리합니다.

기본 검증

CI=1 pnpm typecheck
pnpm lint
pnpm test
pnpm build

문서만 변경한 경우에도 Markdown link, Prettier, 생성 문서 일치와 pnpm docs:build를 확인합니다. 제품 코드 동작을 바꾸지 않은 문서 작업은 typecheck·unit·Chromium 검증을 실행한 것으로 설명하지 않습니다.

새 worktree 준비

Playwright 설정의 webServer는 frontend package의 dev 또는 vue-tsc && vite build를 직접 실행합니다. 이 경로는 root Turbo task가 보장하는 Prisma 생성과 upstream package build를 거치지 않으므로, 새 worktree에서 브라우저 test를 먼저 실행하면 제품 코드와 무관한 module/type 오류가 발생할 수 있습니다.

Node 24 환경을 활성화한 뒤 저장소 root에서 다음 한 명령으로 준비합니다.

fnm use
pnpm test:bootstrap

현재 호스트는 fnm use가 .nvmrc를 읽습니다. nvm 환경에서는 nvm use로 같은 Node 24 계약을 적용합니다.

test:bootstrap은 다음 순서를 고정합니다.

1. pnpm install --offline --frozen-lockfile
2. game/Gateway Prisma client 생성
3. common → logic → infra → game-engine → game-api → gateway-api build

로컬 pnpm store에 필요한 package가 없는 호스트에서만 network 사용 가능 여부를 확인한 뒤 pnpm install --frozen-lockfile과 pnpm test:prepare를 나누어 실행합니다. 이미 install된 worktree에서는 schema, package source 또는 branch가 바뀐 뒤 다음 준비 명령만 다시 실행합니다.

pnpm test:prepare

Chromium executable이 없다는 Playwright 안내가 나온 경우에만 다음을 실행합니다. 이는 package/Prisma 준비와 별도이며 browser cache를 변경합니다.

pnpm exec playwright install chromium

Browser test 실행

Game frontend fixture의 예시는 다음과 같습니다. Ref 룩앤필 근거가 필요한 UI 변경은 PLAYWRIGHT_FRONTEND_MODE=production을 사용해 production bundle을 검증합니다.

PLAYWRIGHT_FRONTEND_PORT=15241 \
PLAYWRIGHT_FRONTEND_MODE=production \
pnpm --filter @sammo-ts/game-frontend exec playwright test \
  inGameMenus.spec.ts --config e2e/playwright.config.mjs --grep '대상 이름'

Gateway fixture는 별도의 port 환경 변수를 사용합니다.

PLAYWRIGHT_GATEWAY_FRONTEND_PORT=15242 \
pnpm --filter @sammo-ts/gateway-frontend exec playwright test \
  public-map-tabs.spec.ts --config e2e/playwright.config.mjs --grep '대상 이름'

Ref/Core 공통 fixture는 root script를 사용하며, 다른 worktree와 port가 겹치면 설정을 편집하지 않고 환경 변수로 격리합니다.

FRONTEND_PARITY_GATEWAY_PORT=15243 \
FRONTEND_PARITY_GAME_PORT=15244 \
pnpm test:e2e:frontend-legacy

같은 game frontend dist를 쓰는 CHE/HWE production build와 Playwright run은 동시에 실행하지 않습니다. 각 profile을 직렬로 실행하고 해당 run의 base path, profile, viewport와 fixture를 결과에 기록합니다.

준비 실패와 제품 실패 구분

증상	먼저 확인할 항목	처리
pnpm: command not found	.nvmrc의 Node 24가 활성화됐는지	현재 호스트는 fnm use; nvm 환경은 nvm use; shim이 없으면 corepack enable 후 재실행
Corepack 하위 실행에서 pnpm version mismatch	package script 안에서 다른 Corepack pnpm이 재호출됐는지	Node 24 적용 후 직접 pnpm test:bootstrap 실행; corepack pnpm test:bootstrap 중첩 금지
Cannot find module '../prisma/generated/...' 또는 새 Prisma field 부재	generated client가 현재 checkout schema와 같은지	pnpm test:prepare
Failed to resolve import '@sammo-ts/common', @sammo-ts/logic 또는 TS6305	upstream dist가 현재 checkout source로 build됐는지	pnpm test:prepare; 계속되면 실패 package의 build를 단독 실행해 실제 오류 확인
Process from config.webServer was not able to start	위 준비 오류와 frontend build의 숨겨진 stderr	준비 후 pnpm --filter <frontend> build를 단독 실행
EADDRINUSE 또는 server timeout	다른 worktree의 151xx listener	해당 Playwright port 환경 변수로 고유 port 지정; config 임시 수정 금지
browser executable 부재	Playwright가 표시한 cache path	pnpm exec playwright install chromium
node_modules/.modules.yaml EACCES	기존 checkout의 소유권이 다른 작업에서 바뀌었는지	소유권을 임의 변경하지 말고 같은 commit의 깨끗한 worktree에서 준비·검증

준비 명령이 성공한 뒤 발생한 assertion, browser console, request 또는 geometry 차이만 제품/fixture 분석 대상으로 올립니다. 넓은 suite 실패는 변경 없는 동일 commit에서도 재현하여 baseline과 회귀를 구분하고, skip은 pass로 세지 않습니다.

테스트 계층

Unit

packages/common, packages/logic, 각 app의 test/가 순수 계산, parser, constraint, lifecycle과 service를 검증합니다. Gameplay 계산에는 fixed seed와 정확한 state/log 기대값을 사용합니다.

Integration

tools/integration-tests와 *.integration.test.ts가 PostgreSQL, Redis, Fastify transport, Prisma transaction, lease와 worker 경계를 검증합니다.

pnpm test:integration
pnpm test:integration:conditional

조건부 suite는 worktree별 PostgreSQL·Redis instance를 준비합니다. Test가 schema truncate와 Redis 정리를 수행하므로 공유 개발 instance를 사용하지 않습니다.

Differential

pnpm check:legacy:general
pnpm check:legacy:nation

실제 ref runner와 canonical snapshot 계약은 차등 검증을 따릅니다.

Browser

pnpm typecheck:e2e:frontend-legacy
pnpm test:e2e:frontend-legacy
pnpm test:e2e:main-front-status-live
pnpm test:e2e:main-records-live

같은 Chromium, viewport, device scale, zoom, locale, font, image, 로그인과 test data를 사용합니다. Screenshot과 함께 getBoundingClientRect()와 getComputedStyle()을 수집하고 hover, focus, pointer down/up, checked/selected/disabled, dropdown, modal과 transition을 확인합니다.

권한 matrix

API 변경은 최소한 다음 행위자를 구분합니다.

• 무인증
• 인증됐지만 장수가 없는 사용자
• 자기 장수
• 같은 국가의 다른 장수
• 외국 장수
• NPC
• 직책·서비스 role별 사용자
• sanction 대상 사용자

거부 경로는 DB·queue·Redis side effect가 없어야 합니다. Public DTO는 숨겨야 할 field가 빠졌는지 확인하고, role 이름만 비교하지 말고 실제 capability와 resource relation을 검증합니다.

DB와 migration

Schema 변경은 빈 DB 전체 migration, 기존 DB 증분 migration, 두 번째 deploy의 no-op, unique/FK/index, runtime query와 reload를 확인합니다. 기존 migration 파일과 checksum은 수정하지 않습니다. prisma db push는 격리 fixture의 일시적 schema 준비에만 사용합니다.

결과 기록

Report에는 실행 명령, commit, 서비스와 fixture, pass/fail/skip 수, baseline failure, 미검증 경계와 artifact 위치를 기록합니다. Screenshot과 log에는 token, password, 개인정보를 포함하지 않습니다.