문제: High·P1을 고친 뒤에도 P2·P3 약 90건이 남았다. 연결·구독·메시지 크기 상한이 없는 전송(WebSocket·gRPC·GraphQL deadline), 낙관적 충돌의 500, upsert 경쟁, Mongo 무제한 timeout, 샘플 목록 N+1, 갈라진 복사본 (TenantId 3벌, 이벤트 ID 문법 5곳, SQLState 표 2벌), 문서를 읽는 PR 테스트와 캐시를 막는 lane 설정 등이다. 새 기능을 어디에 어떤 순서로 만드는지 알려 주는 문서와 도구가 없었다. MinIO 공식 이미지가 사라져 객체 저장소 lane이 돌지 않았다. 방법: 영역별 묶음으로 실패 테스트를 먼저 쓰고 고쳤다. 고치는 중에 찾은 결함도 함께 고쳤다(durable operation id가 UUIDv4라 이벤트가 전부 DEAD, S3 어댑터 생성·작은 chunk 읽기 실패, Redis 조건부 기록의 EVALSHA 권한). MinIO는 pgsty/minio를 digest로 고정했다(Chainguard는 태그·실행 사용자· mc 이미지 문제로 버림). docs/manual/에 작업 순서와 판단 지점을 쓰고, scripts/new-feature.sh가 5개 leaf에 뼈대를 만든다. 생성→빌드→통과 왕복을 verifyFeatureScaffold가 mainCheck에서 본다. 묶음별 결과와 결정은 리뷰 README 14절에 있다. 위험·한계: 파생 서비스 동작이 바뀐다. JDBC batch 50 기본, 운영 jar에서 H2 제거, 트랜잭션 30초 제한, 격리 수준을 Hikari에서 고정, gRPC· WebSocket·GraphQL 새 한도, correlation ID 규칙 밖이면 서버가 교체, 샘플 키 오류 코드 IDEMPOTENCY_KEY_INVALID. 새 leaf 두 개 (composition:durable-operation, adapter:inbound:messaging)와 새 마이그레이션(postgresql V20·V21, notification V11·V12, sample V8_1, grpc-ledger V002)이 생긴다. V21 유일 인덱스는 기존 중복이 있으면 실패한다(runbook에 확인 쿼리). 검증: ci, mainCheck(생성 명령 왕복 포함), integrationCheck(MinIO 포함 전 컨테이너 lane), -p optional-platforms ci integrationCheck 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14절 BREAKING CHANGE: JDBC batch 기본 켜짐, H2 운영 의존 제거, 트랜잭션 기본 제한 30초, gRPC·WebSocket·GraphQL 서버 한도 기본값 추가, 샘플 Idempotency-Key 오류 코드 변경.
81 lines
4.9 KiB
Markdown
81 lines
4.9 KiB
Markdown
# 08. 테스트 작성 규칙
|
|
|
|
## 핵심
|
|
|
|
테스트 규칙의 정본은 `AGENTS.md` 「테스트 전략」이다. 이 장은 새 기능을 만들 때 그 규칙이 **어떤
|
|
파일 배치가 되는지**와 **어느 단계(PR/main/integration)에서 도는지**를 적는다.
|
|
|
|
```text
|
|
포트 XRepository (domain-core)
|
|
├─ testFixtures: InMemoryXRepository (fake, 포트당 하나)
|
|
├─ testFixtures: XRepositoryContract (abstract, 약속 목록)
|
|
├─ test: InMemoryXRepositoryContractTest extends XRepositoryContract → ci (leaf test)
|
|
└─ 저장 adapter leaf integrationTest:
|
|
JpaXRepositoryContractTest extends XRepositoryContract → integrationCheck (실 PostgreSQL)
|
|
|
|
유스케이스 테스트 = 실제 유스케이스 + InMemoryXRepository + DirectTransactionPort
|
|
```
|
|
|
|
fake와 실제 adapter가 **같은 계약**을 통과해야 fake 위의 유스케이스 테스트가 거짓 녹색이 되지 않는다.
|
|
생성 명령은 이 배치를 그대로 만든다(01장).
|
|
|
|
## 계층별 테스트
|
|
|
|
| 계층 | 테스트 | 쓰는 대역 | 예 (생성 결과) |
|
|
| --- | --- | --- | --- |
|
|
| domain | 순수 JUnit. 불변식·id 문법 | 없음 | `<F>Test`, `<F>IdTest` |
|
|
| domain 포트 | 공유 계약 | fake | `InMemory<F>RepositoryContractTest` |
|
|
| application | 유스케이스 흐름·트랜잭션 경계·오류 코드 | 포트 소유자 testFixtures의 fake, `DirectTransactionPort` | `Create<F>UseCaseTest` |
|
|
| outbound adapter | 같은 공유 계약을 실제 저장소로 | Testcontainers(strict lane) | 04장 4번 |
|
|
| inbound | HTTP status·Envelope·오류 코드 | 실제 유스케이스 + fake, standalone MockMvc | `<F>ControllerTest` |
|
|
| bootstrap | 조립 조건(있을 때 켜짐, 없을 때 없음), imports 등록 | fake bean | `<F>ConfigTest` |
|
|
|
|
## 작성 규칙 요약 (정본은 AGENTS.md)
|
|
|
|
1. 이름은 lowerCamelCase 행동 문장. 이름이 말한 성질을 단언한다. 예: 이름에 "트랜잭션 전에"를 넣었으면
|
|
트랜잭션이 없었다는 것도 단언하거나, 이름에서 뺀다.
|
|
2. `@DisplayName`은 메서드 이름으로 못 쓰는 내용(숫자, 기호, 이유)이 있을 때만, **한국어**로
|
|
(소유자 결정 5). 예: `@DisplayName("이름이 NAME_MAX_LENGTH + 1자이면 거절한다")`.
|
|
3. 본문 3문장 이상이면 `// given` `// when` `// then`. `// when`은 하나. 예외는 `catchThrowable`로 분리.
|
|
4. then은 when의 결과 하나만. 예외는 타입과 reason/code를 함께.
|
|
5. 포트 대역은 hand-rolled fake 하나, **포트 소유 leaf의 testFixtures**에. Mockito는 프레임워크 경계와
|
|
장애 주입만.
|
|
|
|
### 판단: fake가 어디 사나
|
|
|
|
- **고르는 기준**: 포트 인터페이스가 어느 leaf에 있나.
|
|
- **기본값**: 그 leaf의 `src/testFixtures/java/.../<f>/testkit/`. domain 포트면 domain-core,
|
|
application 포트면 application-core. 소비 leaf는 `testImplementation testFixtures(project(':<owner>'))`.
|
|
- **예외**: 없다. 테스트 안 private fake는 계약 밖에 있어 실제와 갈라진다(리뷰 01-05의 lock fake).
|
|
|
|
## lane과 단계
|
|
|
|
`ci`(PR)의 leaf `test`는 Docker 없이 빠르게 끝나야 한다. 실 DB·실 서버가 필요한 테스트는 strict
|
|
lane으로 선언하고 단계를 지정한다. 선언은 `ca.strict-test-lane`(`src/build-logic/README.md`).
|
|
|
|
| lane 종류 | 선언 | 도는 단계 |
|
|
| --- | --- | --- |
|
|
| 단위·slice | 기본 `test` | `ci` |
|
|
| 문서 대조·느린 계약 | 태그 lane + `mainStage()` | `mainCheck` |
|
|
| 실 DB·컨테이너 | `integration()` + 자기 sourceSet(예: `integrationTest`) | `integrationCheck` |
|
|
| 성능·부하 | performance 범주 | `performanceCheck` |
|
|
| 외부 입력 필요(자격증명 등) | `explicitOnly(reason)` | 어떤 집계에도 안 들어가고 이유가 출력된다 |
|
|
|
|
예: `src/sample-portfolio/build.gradle`의 `strictTestLanes { lane('integrationTest') { integration() … } }`,
|
|
`src/app-bootstrap/build.gradle`의 `publicPathSnapshotTest`(`mainStage()`).
|
|
|
|
### 판단: 새 테스트를 어느 lane에
|
|
|
|
- **고르는 기준**: Docker·네트워크·실 서버가 필요한가, 몇 초 넘게 걸리는가.
|
|
- **기본값**: 필요 없으면 `test`(ci). 필요하면 integration lane.
|
|
- **예외**: 반드시 실행돼야 하는 소수 테스트(계약 자격 검사)는 `requires(클래스)` + `rejectSkipped = true`로
|
|
이름을 박는다. 이름이 바뀌거나 지워지면 lane이 실패한다.
|
|
- 새 lane이 어떤 단계에도 속하지 않으면 PR 게이트의 `verifyStrictLaneStages --dry-run`이 실패한다
|
|
(1라운드 08-01). 단계는 집계 태스크(`integrationCheck` 등)를 통해 붙고, workflow 파일을 고치지 않는다.
|
|
|
|
## 지금 이해하면 되는 것
|
|
|
|
- fake와 계약은 포트 주인 testFixtures에, adapter는 같은 계약을 실제 저장소로.
|
|
- `@DisplayName`은 꼭 필요할 때만, 한국어로.
|
|
- Docker가 필요한 테스트는 strict lane + 단계 지정. 단계 없는 lane은 PR에서 막힌다.
|