clean-architecture-backend-template/docs/testing/TESTING_STRATEGY.md

# 테스트 전략 — 레벨 정의와 소스셋 매핑 (SSOT)

- 기준 일자: 2026-09-07
- 상태: **활성 문서.** 아래 §3 표는 사람이 유지한다. `verifyTestSourceSetRegistry` 가 이 문서의 §3 표와 실제 Gradle 소스셋 선언의
  불일치를 빌드 실패로 만든다.
- 근거 리뷰: `docs/reviews/2026-09-07-app-bootstrap-module-code-review.md` (BOOT-014, BOOT-015,
  BOOT-016)

## 1. 이 문서가 존재하는 이유

이 저장소는 이미 테스트 레벨 계약을 **기계로** 강제하고 있었다 —
`TestTaxonomyArchitectureTest` 가 contract/architecture 트리의 Testcontainers 의존을 금지하고,
slice 애노테이션 혼합을 막고, fixture 유출을 잡는다. 없던 것은 **사람이 읽을 수 있는 정의**였다.

그 결과 계약은 "패키지 이름"에만 걸려 있었고 "어느 소스셋이 컴파일하는가"에는 걸려 있지 않았다.
Testcontainers 를 쓰는 통합 테스트 9개가 `app-bootstrap/src/test` 안에 있었고, `@Testcontainers` 5개
중 가드가 있는 것은 하나뿐이었다. 즉 `./gradlew :app-bootstrap:test` — 이 저장소가 leaf 별 기본
명령으로 권장하는 바로 그 명령 — 이 Docker 데몬을 요구했다 (BOOT-014).

그래서 규칙을 두 가지 방식으로 동시에 고정한다. 사람은 이 문서를 읽고, 빌드는 §3 표를 읽는다.

## 2. 레벨 정의

레벨은 **이름이 아니라 "어디까지 실제로 붙여서 검증하는가"**로 정의한다. `smoke`, `regression`,
`acceptance` 같은 말은 범위가 아니라 목적이라 레벨이 될 수 없다 — 하나의 E2E 테스트가 동시에
smoke 이고 regression 일 수 있다.

| 레벨 | 무엇을 검증 | 외부 시스템 | 소스셋 |
| --- | --- | --- | --- |
| **unit** | 클래스·함수·도메인 규칙 | 없음 | `src/test` |
| **slice** | 프레임워크 한 계층 | 인메모리/모의 | `src/test` |
| **contract** | 모듈 경계의 형태와 약속 | 없음 | `src/test` |
| **architecture** | 코드 의존 관계, 테스트 분류 자체 | 없음 | `src/test` |
| **integration** | 실제 인프라와의 연결 | 실제 DB/브로커/스토리지 | `src/integrationTest` 또는 leaf 전용 레인 |
| **qualification** | 벤더·프로토콜·배포 형상 | 실제 벤더 런타임 | leaf 전용 레인 |
| **build-qualification** | 빌드·조립 계약 자체 | 없음 (별도 클래스패스) | leaf 전용 레인 |
| **performance** | 지연·처리량 | 실제에 가까움 | leaf 전용 레인 |

### 2.1 소스셋을 나누는 기준은 하나다

> **테스트 코드는 production 패키지 구조를 그대로 미러링한다. 별도 소스셋으로 분리하는 것은
> 실행 환경·의존성·클래스패스가 달라지는 경우뿐이다.**

`unit/`, `service/`, `repository/`, `regression/` 같은 폴더는 만들지 않는다. 서로 다른 분류 축을
한 디렉터리에 섞으면 `UserServiceTest` 가 어디에 속하는지 아무도 답할 수 없게 된다. 이 저장소의
`src/test` 는 이미 production 패키지를 미러링하고 있으며 그 상태를 유지한다.

### 2.2 build-qualification 은 폴더 취향이 아니다

`app-bootstrap` 의 세 레인은 "테스트를 분류하려고" 나눈 것이 아니라 **하나의 소스셋으로 표현할 수
없는 클래스패스 차이** 때문에 존재한다. 합치면 검증 자체가 성립하지 않는다.

- `sampleOffTest` — `src/test` 와 **같은 소스 파일**을 `sample-portfolio` 없는 클래스패스로 다시
  컴파일한다. "샘플을 지워도 템플릿이 성립하는가"의 증명이며, 같은 파일을 두 클래스패스로 컴파일하는
  것이 그 정의다.
- `conditionalTransportTest` — GraphQL/gRPC/WebSocket 을 **테스트 전용으로만** 클래스패스에 올린다.
  이 의존을 `testImplementation` 으로 옮기면 "기본 클래스패스에는 없다"는 증명 대상 명제가 그 순간
  거짓이 된다.
- `functionalTest` — Gradle TestKit 이 별도 Gradle 빌드를 띄운다.

## 3. 소스셋 레지스트리 (기계 검증 대상)

이 표를 읽어 실제 `sourceSets` 선언과 대조하던 `verifyTestSourceSetRegistry` 는 2026-09에 삭제했다
(Markdown 표 파서였고, `<!-- registry:begin -->` 마커가 사라지면 계약이 산문으로 되돌아가는 것을
막으려고 마커 존재 자체까지 검사했다). 레인을 추가하면 이 표도 같이 고친다. 아래 옛 설명은 표를
어떻게 읽어야 하는지에 대한 기준으로 남긴다: 표에 없는 소스셋을
추가하거나 표에 있는 소스셋을 지우면 빌드가 실패한다.

<!-- registry:begin -->
| Gradle 경로 | 소스셋 | 레벨 |
| --- | --- | --- |
| `:adapter:inbound:graphql` | `testFixtures` | fixtures |
| `:adapter:inbound:web` | `jettyCompatTest` | qualification |
| `:adapter:inbound:web` | `nginxProxyTest` | qualification |
| `:adapter:inbound:web` | `testFixtures` | fixtures |
| `:adapter:inbound:web` | `webfluxContractTest` | qualification |
| `:adapter:inbound:websocket` | `jettyWebSocketTest` | qualification |
| `:adapter:inbound:websocket` | `nginxWebSocketTest` | qualification |
| `:adapter:inbound:websocket` | `testFixtures` | fixtures |
| `:adapter:outbound:httpclient` | `httpClientPerformanceTest` | performance |
| `:adapter:outbound:httpclient` | `jmh` | performance |
| `:adapter:outbound:httpclient` | `testFixtures` | fixtures |
| `:adapter:outbound:objectstorage` | `objectStorageAwsQualificationTest` | qualification |
| `:adapter:outbound:objectstorage` | `objectStorageMinioContractTest` | integration |
| `:adapter:outbound:objectstorage` | `objectStorageMinioFaultTest` | integration |
| `:adapter:outbound:persistence-jpa` | `jpaPlatformPerformanceTest` | performance |
| `:adapter:outbound:persistence-jpa` | `postgresqlIntegrationTest` | integration |
| `:adapter:outbound:persistence-jpa` | `testFixtures` | fixtures |
| `:adapter:outbound:persistence-mongo` | `mongoPerformanceTest` | performance |
| `:adapter:outbound:persistence-mongo` | `testFixtures` | fixtures |
| `:app-bootstrap` | `conditionalTransportTest` | build-qualification |
| `:app-bootstrap` | `functionalTest` | build-qualification |
| `:app-bootstrap` | `integrationTest` | integration |
| `:app-bootstrap` | `sampleOffTest` | build-qualification |
| `:messaging:messaging-kafka` | `jmh` | performance |
| `:messaging:messaging-rabbit` | `jmh` | performance |
| `:messaging:messaging-testkit` | `jmh` | performance |
| `:sample-portfolio` | `posterImageMigrationTest` | qualification |
| `:shared-contract` | `edgeRateLimitContractTest` | contract |
<!-- registry:end -->

`src/test` 는 모든 leaf 가 갖는 기본 소스셋이므로 표에 적지 않는다.

## 4. 판단표 — 새 테스트를 어디에 쓰는가

대상 코드가 정해지면 위치와 방식이 기계적으로 결정되어야 한다.

| 대상 | 레벨 | 협력자 | 위치 |
| --- | --- | --- | --- |
| 도메인 엔티티·값 객체 | unit | 없음 | 해당 leaf `src/test` |
| 유스케이스 | unit | 손으로 만든 Fake (Mockito 아님) | `application-core/src/test` |
| 시작 검증기 (`*Validator`) | unit | `MockEnvironment` | `app-bootstrap/src/test` |
| `@Configuration` 조립 | slice | `ApplicationContextRunner` | `app-bootstrap/src/test` |
| 컨트롤러 | slice | `@WebMvcTest` + 모의 유스케이스 | `adapter/inbound/web/src/test` |
| JPA 리포지토리 매핑 | integration | Testcontainers PostgreSQL | `postgresqlIntegrationTest` |
| 아웃박스·멱등성 행 수명주기 | integration | Testcontainers PostgreSQL | `app-bootstrap/src/integrationTest` |
| 브로커 발행/수신 | integration | 실제 브로커 | leaf 전용 레인 |
| 에러 응답 스키마 | contract | 없음 (스냅샷) | `app-bootstrap/src/test/.../contract` |
| 의존 방향·패키지 경계 | architecture | 없음 (ArchUnit) | `app-bootstrap/src/test/.../architecture` |

### 4.1 금지

- `src/test` 안에서 `org.testcontainers` 의존 — `TestTaxonomyArchitectureTest` 가 막는다 (BOOT-014).
- 필요 없는 `@SpringBootTest`. 조립을 검증할 것이 아니면 `ApplicationContextRunner` 나 순수 단위
  테스트로 충분하다.
- slice 애노테이션 혼합 (`@WebMvcTest` + `@DataJpaTest`) — Spring 이 지원하지 않는다.
- production 코드가 test fixture 에 의존하는 것.
- 픽스처를 `TestUtil`·`CommonUtil` 같은 이름으로 묶는 것. 역할을 드러내는 이름
  (`fixture/`, `fake/`, `container/`, `assertion/`) 을 쓴다.

## 5. 공용 테스트 지원 코드 — `testFixtures`

**표준은 `java-test-fixtures` 하나다 (ADR-BUILD-001).** 공용 테스트 지원 코드는
`src/testFixtures/java` 에 두고, 다른 leaf 는 `testFixtures(project(':x'))` 로 소비한다.

두 관례가 공존하던 상태(BOOT-015)는 해소됐다. `ca.testkit-publisher` 컨벤션 플러그인과 그것을 쓰던
`testkit` 소스셋 5개는 모두 이관됐고, 플러그인 자체도 제거됐다. 이관하면서 드러난 사실 하나는 기록해
둘 값어치가 있다: `testkit*` 구성이 `testImplementation` 을 상속했기 때문에 fixture 들은 각 leaf 가
선언한 모든 테스트 라이브러리를 **말없이** 보고 있었다. `testFixturesImplementation` 으로 옮기면서
그 표면이 드러났고, 다섯 leaf 에서 도합 30개가 넘는 의존을 명시적으로 적어야 했다.

`test` 가 아닌 lane 은 fixture 를 소비한다고 선언해야 한다 — `java-test-fixtures` 는 `test` 만
자동으로 배선한다:

```groovy
strictTestLanes {
    sourceSet('postgresqlIntegrationTest') { compilesAgainst 'main', 'testFixtures' }
}
```

디렉터리는 역할을 드러내는 형태를 권고한다 (`fixture/`, `fake/`, `container/`, `assertion/`).
`TestUtil`·`CommonUtil` 같은 무의미한 이름 묶음은 금지한다.

## 6. CI 단계 매핑

폴더만 나누고 CI 에서 한꺼번에 돌리면 분리의 의미가 없다.

```
커밋 / IDE          →  unit · slice · contract · architecture   (`test`)
Pull Request        →  + integration                            (integration 레인)
머지 / 스테이징      →  + build-qualification                    (functionalTest, sampleOffTest,
                                                                 conditionalTransportTest)
야간 / 스케줄        →  + qualification · performance
```

`check` 에는 인프라 레인을 붙이지 않는다. 이것은 이 저장소가 이미 따르고 있는 관례이며
(`persistence-jpa` 의 `postgresqlIntegrationTest` 도 `check` 에 붙어 있지 않다), Docker 없는
환경에서 `check` 가 실패하지 않게 하는 유일한 방법이다.

## 7. LLM 에이전트에게 적용할 때

이 저장소는 에이전트 협업을 전제로 설계되어 있다. 테스트 생성을 맡길 때는 다음 순서를 강제한다.

1. 이 테스트가 §2 의 어느 레벨인지 판정하고 근거를 적는다.
2. §3 표에서 해당 소스셋을 찾는다.
3. 이미 존재하는 fixture 를 먼저 검색한다.
4. 테스트를 작성한다.
5. 판정한 레벨보다 큰 레벨로 작성하지 않았는지 확인한다 (`@SpringBootTest` 를 썼다면 왜 필요한지
   설명할 수 있어야 한다).