Files
clean-architecture-backend-…/docs/testing/TESTING_STRATEGY.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

180 lines
9.0 KiB
Markdown

# 테스트 전략 — TEST / INTEGRATION / SYSTEM / ARCHITECTURE / PERFORMANCE
- 기준 일자: 2026-09-18
- 상태: **활성 SSOT**
- 기계 기준: `build-logic/src/main/java/dev/caskeleton/buildlogic/strictlane/TestLaneCategory.java`
- 관련 리뷰: `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md` BOOT-014~016
- 후속 결정: `docs/superpowers/specs/2026-09-16-verification-surface-reduction-design.md`
## 1. 공식 테스트 분류는 다섯 개뿐이다
이 저장소의 실행 taxonomy는 다음 다섯 개다.
| Category | 의미 | 외부 인프라 |
| --- | --- | --- |
| **TEST** | 빠르고 결정적인 로컬 검증. unit, slice, hermetic contract를 포함한다. | 원칙적으로 없음 |
| **INTEGRATION** | 실제 DB·브로커·스토리지·프로세스 등 외부 경계와의 통합을 검증한다. | 허용 |
| **SYSTEM** | 여러 모듈이 조립된 애플리케이션/런타임 동작과 클래스패스 형상을 검증한다. | 필요에 따라 허용 |
| **ARCHITECTURE** | 의존 방향, 패키지 경계, 금지 API, 테스트 taxonomy 같은 구조 규칙을 검증한다. | 없음 |
| **PERFORMANCE** | 지연, 처리량, 자원 사용과 회귀를 측정한다. | 실제에 가까운 환경 허용 |
`StrictTestLaneSpec`의 기본 category는 `TEST`이며,
`test()`, `integration()`, `system()`,
`architecture()`, `performance()`가 각각 위 다섯 값을 선택한다.
### 1.1 unit / slice / contract는 별도 category가 아니다
다음 용어는 **TEST 안에서 무엇을 검증하는지 설명하는 스타일**이다.
- unit: 한 클래스·함수·도메인 규칙
- slice: Spring MVC/JPA 등 한 프레임워크 계층의 좁은 조립
- contract: 외부 인프라 없이 검증 가능한 모듈/API/직렬화 약속
예를 들어 `@WebMvcTest`는 slice이지만 category는 TEST다.
JSON snapshot 검증은 contract이지만 hermetic하면 category는 TEST다.
새로운 `SLICE`나 `CONTRACT` category를 만들지 않는다.
### 1.2 qualification은 테스트 종류가 아니다
`qualification`은 **CI/release 검증 gate**다. 여섯 번째 테스트 category가 아니다.
현재 루트 `qualificationCheck`는 full system composition과 auxiliary-source style 검증을
묶는다. 특정 provider certification workflow나 leaf task 이름에 qualification이 들어갈 수도 있지만,
그 안에서 실행되는 테스트 자체는 다섯 category 중 하나로 분류한다.
즉 다음 두 질문을 분리한다.
1. 이 테스트는 무엇을 검증하는가? → 다섯 category 중 하나.
2. 언제/어떤 gate가 이 테스트를 실행하는가? → CI, qualification, release 정책.
## 2. Category와 source set은 같은 개념이 아니다
source set 이름으로 category를 추론하지 않는다.
- 일반적인 `src/test`는 TEST의 기본 실행 위치다.
- 별도 runtime/classpath가 필요한 테스트는 auxiliary source set을 사용할 수 있다.
- strict lane은 자신이 사용할 source set과 category를 **각각 명시**한다.
- `postgresqlIntegrationTest`처럼 이름에 integration이 들어가더라도, 기계 기준은
이름이 아니라 lane의 `integration()` 선언이다.
source set 목록은 계속 변하는 구현 세부사항이다. 이 문서에 전체 목록을 복제하지 않는다.
2026-09-16 verification-surface 축소에서 `verifyTestSourceSetRegistry`를 삭제했다.
Markdown 표와 Gradle source set을 대조하는 parser는 current-state를 또 하나의 build contract로
복제했기 때문이다. **이 verifier를 다시 만들지 않는다.**
## 3. 어디에 어떤 테스트를 두는가
| 대상 | Category | 기본 방식 |
| --- | --- | --- |
| 도메인 엔티티·값 객체 | TEST | 순수 단위 테스트 |
| Application use case | TEST | fake/stub port, 필요 최소 mock |
| startup validator / settings validation | TEST | `MockEnvironment` 또는 순수 객체 |
| Spring `@Configuration` 한 조각 | TEST | `ApplicationContextRunner` |
| MVC controller 한 slice | TEST | framework slice test |
| hermetic serialization/API snapshot | TEST | contract assertion |
| JPA repository + 실제 PostgreSQL | INTEGRATION | Testcontainers/real DB |
| Kafka/Rabbit/Redis/Mongo와 실제 프로토콜 통신 | INTEGRATION | real service/container |
| 전체 Boot composition, optional classpath 조합 | SYSTEM | full application/runtime graph |
| sample 제거/transport 포함 여부 등 전체 조립 결과 | SYSTEM | 별도 classpath/source set 가능 |
| ArchUnit, module dependency rule, forbidden API | ARCHITECTURE | static/bytecode structure |
| JMH, throughput/latency regression | PERFORMANCE | benchmark/performance lane |
### 3.1 TEST에서 금지하는 것
기본 TEST가 개발자의 로컬 루프를 무겁게 만들면 taxonomy가 무너진다.
- 실제 Docker/DB/broker를 요구하지 않는다.
- 외부 SaaS/network를 호출하지 않는다.
- 전체 애플리케이션 graph가 필요하지 않은데 `@SpringBootTest`를 사용하지 않는다.
- production 패키지와 무관한 `unit/`, `service/`,
`regression/` 같은 별도 분류 폴더를 만들지 않는다.
taxonomy 자체를 검증하기 위한 negative fixture는 예외다. 예를 들어 Testcontainers import를 일부러
가진 fixture는 실제 컨테이너를 실행하려는 테스트가 아니라 ARCHITECTURE 규칙의 입력이다.
## 4. 배치 원칙
테스트 코드는 가능한 한 production package를 그대로 mirror한다. 위치는 **대상 코드의 소유권**으로
찾을 수 있어야 한다.
별도 source set은 다음 중 하나가 실제로 달라질 때만 만든다.
- runtime/classpath
- 외부 인프라 요구
- JVM 옵션/환경
- 실행 비용과 스케줄
- 독립적인 strict-lane evidence가 필요한 경우
단순히 이름을 예쁘게 나누기 위해 source set을 만들지 않는다.
## 5. 공용 테스트 지원 코드
공유 fixture의 publish 표준은 Gradle `java-test-fixtures`다.
- **다른 source set 또는 다른 leaf가 소비해야 하는** fixture/fake/assertion/container helper는
`src/testFixtures/java`에 둔다.
- 다른 leaf는 `testFixtures(project(':...'))`로 명시적으로 소비한다.
- auxiliary lane이 fixture를 쓰면 그 lane의 classpath에 testFixtures를 명시적으로 연결한다.
- 반대로 한 source set 안에서만 쓰는 helper는 그 source set 안에 둔다. 사용처가 하나의 test
classpath뿐인데 `testFixturesJar`를 만들 이유는 없다.
- `TestUtil`, `CommonUtil`처럼 역할이 드러나지 않는 bucket을 만들지 않는다.
과거 `testkit` custom source set / `ca.testkit-publisher` 방식은
`java-test-fixtures`로 이관됐으며 다시 도입하지 않는다.
fixture는 **지원 코드**다. TEST/INTEGRATION/SYSTEM/ARCHITECTURE/PERFORMANCE 중 하나의 category를
추가하지 않는다.
## 6. Gradle 실행 계층
### leaf
- `:<leaf>:check`: 그 leaf의 compile, 일반 테스트와 로컬 quality 검증.
- `:<leaf>:testLaneCheck`: 그 leaf가 선언한 TEST category strict lanes.
- `:<leaf>:integrationTestLaneCheck`: INTEGRATION strict lanes.
- `:<leaf>:systemTestLaneCheck`: SYSTEM strict lanes.
- `:<leaf>:architectureTestLaneCheck`: ARCHITECTURE strict lanes.
- `:<leaf>:performanceTestLaneCheck`: PERFORMANCE strict lanes.
모든 leaf가 모든 category lane을 가질 필요는 없다.
### repository
- `integrationCheck`: production leaf들의 INTEGRATION lanes.
- `systemTestCheck`: production leaf들의 SYSTEM lanes.
- `architectureCheck`: repository architecture rules + ARCHITECTURE lanes.
- `qualificationCheck`: SYSTEM composition + auxiliary-source style gate.
- `ci`: leaf checks + architecture/quality/config contract + qualification.
- `releaseCheck`: `ci` + release-only provenance/archive/public-path checks.
`integrationCheck`는 현재 `ci`에 암묵적으로 포함되지 않는다.
여러 integration lane이 container runtime을 요구하므로 별도 workflow/main/nightly에서 실행할 수 있다.
PERFORMANCE는 기본 로컬 `check`에 붙이지 않는다. 명시적 benchmark/performance task나
scheduled workflow가 실행한다.
## 7. 새 테스트를 추가할 때 판단 순서
1. 실제 외부 인프라가 필요한가?
- yes → INTEGRATION 후보.
2. 여러 모듈의 실제 application graph/classpath 조합이 검증 대상인가?
- yes → SYSTEM 후보.
3. 코드 구조/의존 관계 자체가 검증 대상인가?
- yes → ARCHITECTURE.
4. 성능 수치가 검증 대상인가?
- yes → PERFORMANCE.
5. 모두 아니면 TEST.
그 다음에야 어떤 source set과 fixture가 필요한지 결정한다.
## 8. SSOT 역할 분리
- **기계 SSOT:** `TestLaneCategory` + `StrictTestLaneSpec`
- **사람 SSOT:** 이 문서
- **실행 graph:** 각 leaf의 strict lane 선언과 root lifecycle task
- **qualification/release 정책:** CI/workflow 및 qualification task
문서와 build.gradle의 전체 현재 상태를 다시 파싱해 서로 맞는지 검사하는 별도 verifier는 두지 않는다.
불변조건은 코드와 convention plugin이 강제하고, 이 문서는 분류 기준과 의도를 설명한다.