문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때 기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰 기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가 가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰 문서 여러 곳에 흩어져 있다. 방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은 다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md, TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다. 정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함 정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션 분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에 「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와 docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다. 버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용 가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접 쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다). 위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지 않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소 밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드 표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로 넣기)는 [제안]으로 표시했다. 검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절 번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖 가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는 DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로 둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
11 KiB
05. 테스트 구조 기준
핵심
테스트는 이름이 말한 것을 증명해야 한다. 통과하는 테스트가 지키겠다고 한 동작을 실제로 지키지 못하면, 그 테스트는 초록색 거짓말이다. 지난 리뷰에서 그런 테스트가 반복해서 나왔다(부록 A6).
정본은 셋이다. 이 장은 그 셋을 가리키고, 개선 작업에서 테스트를 평가·수정할 때의 기준을 더한다.
| 무엇 | 정본 |
|---|---|
테스트 작성 규칙 6개(이름·@DisplayName·GWT·@Nested·단언·fake) |
AGENTS.md 「테스트 전략」 |
| 테스트 분류 5개(TEST·INTEGRATION·SYSTEM·ARCHITECTURE·PERFORMANCE), 배치, source set, 공용 지원 코드 | docs/testing/TESTING_STRATEGY.md, 기계 기준 src/build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TestLaneCategory.java |
| 새 기능의 테스트 배치(포트 → fake → 계약 → adapter 계약) | docs/manual/08-testing.md |
1. lane과 단계
lane은 테스트 묶음 하나다. 분류(category)·source set·태그를 선언하고, 그 분류에 따라 어느 단계(PR·main·integration·
performance)에서 돌지가 정해진다. 선언은 leaf build.gradle의 strictTestLanes { lane(...) { ... } }이다.
lane 선언(leaf build.gradle)
└─ category ── test() ── leaf check ────────────────────────> ci (PR)
├─ architecture() ── architectureCheck ───────────> ci (PR)
├─ mainStage()(document-contract 등) ─────────────> mainCheck (main)
├─ integration() ─────────────────────────────────> integrationCheck
├─ system() ──────────────────────────────────────> systemTestCheck(mainCheck 안)
├─ performance() ─────────────────────────────────> performanceCheck
└─ explicitOnly(reason) ── 어떤 집계에도 없음, 실행하면 이유를 출력
예외 하나: app-bootstrap의 전체 기동 lane은 그 leaf의 check에 들어 있어 ci에서 돈다. 조립이 뜨지 않으면 병합을
막아야 하기 때문이다(src/build.gradle systemTestCheck 위 주석).
단계 표의 정본은 docs/manual/08-testing.md 「lane과 단계」와 src/build.gradle 라이프사이클이다. 개선 작업에서 지킬 것:
- 새 lane은 반드시 어떤 단계에 속한다. 어떤 workflow도 돌리지 않는 lane 14개가 있었다(
1101/08-01). 이제verifyStrictLaneStages --dry-run(PR)이 단계 없는 lane에서 실패한다. workflow를 고치지 않고 집계 태스크로 붙인다. - 반드시 돌아야 하는 테스트는 이름을 박는다.
requires(클래스)+rejectSkipped. 이름이 바뀌거나 지워지면 lane이 실패한다(docs/manual/08-testing.md「판단: 새 테스트를 어느 lane에」). - lane 정책 값은 캐시 입력이다.
rejectSkipped를 바꿨는데 옛 결과가 캐시에서 통과하던 것을 고쳤다(1103/RR-06-02). lane 정책을 새로 더하면 Test 입력으로 선언한다. - 저장소 파일을 읽는 테스트는 태그가 있다. 문서와 대조하면
document-contract(mainStage()), 빌드 스크립트·workflow· compose를 읽으면repository-contract. 저장소 루트는 이 두 lane에만 준다. 태그 없이 저장소를 읽으면test에서 실패한다 (AGENTS.md「Gradle 정책 권위」,1101/08-03). - hermetic lane이 파일을 읽으면 그 파일을 입력으로 선언한다. 그래야 캐시가 거짓 통과를 내지 않는다(
AGENTS.md「Gradle 정책 권위」 strict lane 캐시).
2. 포트당 fake와 공유 계약
규칙의 정본은 AGENTS.md 테스트 작성 규칙 6이다: 포트마다 hand-rolled fake 하나를 포트 소유 leaf의 testFixtures에 두고,
adapter가 있는 포트는 fake와 adapter가 같은 추상 계약(XxxContract)을 통과한다.
포트 (소유 leaf)
├─ testFixtures: InMemoryX (fake, 하나)
├─ testFixtures: XContract (abstract — 약속 목록)
├─ test: InMemoryXContractTest extends XContract → ci
└─ adapter leaf: RealXContractTest extends XContract → integrationCheck (실 vendor)
fake가 실제와 다르게 동작하면 그 fake 위의 유스케이스 테스트가 모두 거짓 초록이 된다(docs/testing/TESTING_STRATEGY.md 9절).
개선 작업에서 지킬 것:
- 계약 밖 fake를 만들지 않는다. 테스트 안 private fake는 실제와 갈라진다(
docs/manual/08-testing.md「판단: fake가 어디 사나」,1101/01-05). - 소비자 없는 fake도 만들지 않는다. 쓰는 유스케이스 테스트가 없는 fake는 두 번째 복사본이 된다(
1101README 15절 04-14 결정). - fake의 동작을 바꾸면 계약 케이스를 같이 바꾼다. 계약에 없는 동작을 fake에만 넣지 않는다. fake가 실제와 달랐던 예:
쿼터 fake(
1103/RR-01-04), in-memory fake가 fingerprint 검사 전에 기록을 넘겨줌(1103README 17절 r10-02). - 계약과 겹친 adapter 손 사본 테스트는 지운다. 같은 약속을 두 번 쓰면 둘 중 하나만 고쳐진다(
1103README 17절 r10-02, 20건 삭제). - skip 수를 본다. 계약 케이스가 skip되면 그 약속은 검증되지 않았다. command fake 위 계약이 시계를 움직일 수 있는데도
시간 케이스 17개를 skip했다(
1103/RR6-02-02→ 0). 남긴 skip은 설계 이유를 적는다(1103README 17.2절 "in-memory fake 계약의 skip 19는 시간 케이스(설계)"). - 현황표를 갱신한다. 포트를 더하거나 계약을 옮기면
docs/testing/TESTING_STRATEGY.md9절 표를 고친다(1101README 16절 r3-h "TESTING_STRATEGY 9절 표를 오케스트레이터가 갱신").
3. 이름·GWT
규칙은 AGENTS.md 테스트 작성 규칙 1~5가 정본이다. 요약하지 않고 개선 작업의 적용 방법만 적는다.
- 테스트를 고칠 때 그 테스트에 규칙을 적용한다. 기존 영어
@DisplayName은 고칠 때 한국어로 바꾼다(결정 5,AGENTS.md규칙 2). - 이름을 바꾸면 이름이 말한 성질을 단언하는지 다시 본다. 이름과 설명이 다른 계약 테스트가 남은 적이 있다
(
1101README 13절 05-01 "WorkerCrashRecoveryContractTest 이름/설명 불일치"). - GWT 주석을 검사하는 자동 게이트는 만들지 않는다. 주석은 bytecode에 없고, 실질적인 강제 수단은 공유 계약 상속이다
(
AGENTS.md「테스트 전략」).
4. RED 확인
RED는 고치기 전 코드에서 새 테스트가 실패하는 것을 실행으로 본 기록이다. 수정의 완료 기준이다(01장 2절).
하는 법
- 테스트만 먼저 쓰고 지금 코드에서 돌린다. 실패 메시지를 기록한다.
- 이미 수정과 테스트를 함께 썼다면, 기준 커밋에 테스트만 얹은 임시 worktree에서 돌린다. 예: desktop 임시 worktree에
45d2a478+ 새 fixture 7개만 얹어 예상한 6건 실패를 확인했다(1103README 17.2절). - 또는 수정 커밋에서 production 변경만 되돌려 돌린다. 예: TRANSITION 시작 revision 검사만 되돌리자 command fake 계약과
실 Redis 계약이 같은 2건으로 실패했다(
1103README 17.2절). - 실험한 worktree와 되돌린 변경은 지운다.
RED가 증거가 되려면
- 실패 메시지가 그 결함을 말한다. 예:
expected NOT_OWNER but was ALREADY_STARTED_SAME_OPERATION(1103README 17.2절). 컴파일 오류·준비 실패로 인한 실패는 RED가 아니다. - 환경에 따라 통과하지 않는다. watchdog RED 테스트가 공용 풀 병렬도 1인 머신에서는 옛 코드도 통과시켰다
(
1103/RR4-03-01→ 병렬도와 무관하게 고침,1103README 16절 r9-b). - 실 vendor가 필요한 결함은 실 vendor에서 RED를 본다. 단위 테스트 RED로 대신했으면 그렇게 적는다(
1101README 14절 r2-04 "새 실 PG 테스트 3개는 수정 전 실패를 실 PG로 확인 안 함"). - 기록 형식: 테스트 이름 + 실패 수(예: "RED 실 PG 5·실 Redis 6·fake 2" —
1103README 15절 r8-a).
5. 테스트가 증명해야 하는 것 — 리뷰 점검표
| 점검 | 결함 모양 | 지난 예 |
|---|---|---|
| 이름이 말한 성질을 단언하나 | 이름은 "carrier를 남기지 않는다"인데 준비는 다른 예외 | 1103/RR6-01-08(aClientSideCarrierIsNotLogged가 IllegalArgumentException을 넣음) |
| 부재 단언이 null과 "키 없음"을 구분하나 | doesNotExist가 null 필드도 통과 |
1101/02-02 |
| 지키려는 코드를 지우면 실패하나(변이) | 소유자 검사를 지워도 전부 통과 | 1101/05-08, 1101 README 3절(변이 대부분은 잡음) |
| 시간 제한 대기의 반환값을 단언하나 | CountDownLatch.await(timeout) 결과를 버려 시간 초과에도 다음 단계로 |
1103 README 14절(7건) |
| skip이 0이거나 설계 이유가 있나 | 계약 케이스가 조용히 skip | 1103/RR6-02-02 |
| 규칙 테스트가 위반·허용 fixture를 둘 다 가지나 | 위반 fixture만 있어 거짓 양성(허용해야 할 것을 거부)을 못 봄 | 1103/RR6-01-03, 1103 README 17절 r10-01(A1·A2 위반, A5 허용 fixture) |
한 테스트에 // when이 하나인가 |
두 동작을 한 테스트가 봄 | AGENTS.md 규칙 3 |
| 테스트 코드도 정적 분석을 통과하나 | 게이트 밖에서 53개 태스크가 실패한 채 방치 | 1103 README 14절 → testQualityCheck |
| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언 | 1103 README 16.1절(ClientRuntimeRegistryTest) |
ArchUnit 규칙의 fixture는 src/app-bootstrap/src/architectureTest/의 ArchitectureViolationFixtureTest가 모은다. 규칙을
더하거나 넓히면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 같은 변경에 넣는다.
6. 테스트를 옮기거나 나눌 때
- 옮기기 전과 뒤의 테스트 수를 lane별로 비교한다. 보고는 테스트 수로 한다(예:
jpaPlatformContractTest407 —1103README 17.2절). - lane을 바꾸면 그 lane이 단계에 속하는지
verifyStrictLaneStages --dry-run으로 본다. - 공유 테스트 코드는
testFixtures로 옮긴다(docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md). 한 source set에서만 쓰면 그 source set에 둔다(docs/testing/TESTING_STRATEGY.md5절). - 아무도 쓰지 않는 테스트 helper는 지운다(
1103README 14절 — web-fileserver helper 2개).
지금 이해하면 되는 것
- 테스트는 이름이 말한 것을 증명한다. 변이로 확인한다.
- fake는 포트당 하나, 계약을 fake와 adapter가 함께 상속한다. skip 수를 본다.
- 수정은 RED(그 결함을 말하는 실패 메시지)를 실행으로 본 뒤에 끝난다.