5.4 KiB
kind, slug, title, topic, project, status, sourceRevision, rootTreeNode, evidenceCapturedOn, assets, evidence, source
| kind | slug | title | topic | project | status | sourceRevision | rootTreeNode | evidenceCapturedOn | assets | evidence | source | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| CASE | doc-contract-test-boundary-predicted-the-drift | 문서 계약 테스트의 단언 경계 밖에 발견된 드리프트 세 건이 전부 있었다 | what-a-gate-does-not-prove | clean-architecture-backend-template | 게시 전 | 21234e38cdb9a926cbc92bb97a2aee2e4a7d2916 | case:doc-contract-test-boundary-predicted-the-drift | 2026-09-01 |
|
|
|
문서 계약 테스트의 단언 경계 밖에 발견된 드리프트 세 건이 전부 있었다
지원 문서가 코드와 어긋나는 것을 잡는 테스트가 있고 잘 작동한다. 이 분석이 찾은 문서 드리프트 세 건은 그 테스트의 단언 여덟 개가 닿지 않는 곳에만 있었다.
관계
- 문서와 상수가 서로 일치하는 것으로는 아무것도 증명되지 않는다 이 사례와 짝을 이루는 규칙이다.
- 빠뜨림이 통과가 되는 게이트는 게이트가 아니다 같은 계열의 상위 규칙이다.
문제
MessagingDocumentationContractTest 가 존재하고, 클래스 javadoc 이 목적을 정확히 적는다.
문서는 조용히 썩는다. 어댑터를 Stable 이라고 적은 지원 매트릭스는 누군가 그것을 강등한 날보다 오래 살아남고, 아무것도 실패하지 않는다. 테스트는 통과하고 빌드는 초록이며 유일한 신호는 몇 달 전에 사실이 아니게 된 페이지를 보고 결정을 내리는 운영자다.
단언은 의도적으로 좁다. 읽는 사람이 행동의 근거로 삼을 주장만 검사하고 산문은 검사하지 않는다. 표현을 단언하면 모든 편집이 테스트 실패가 되고 그 검사는 삭제될 것이기 때문이다.
좁은 단언을 택한 의도는 분명하다. 다만 테스트가 검증하는 항목과 검증하지 않는 항목을 문서나 테스트 이름에서 구분하지 않아 통과 의미가 실제 범위보다 넓게 읽힌다.
결론
단언 여덟 개는 이렇다.
- 지원 매트릭스가 약속하는 문서 아홉 개의 존재
- STABLE 어댑터 이름의 정확한 일치
- EXPERIMENTAL 어댑터가 Stable로 적히지 않음
- 문서화된 Kafka 버전 문자열의 일치
- 존재하지 않는 상수 두 개가 미지원 목록에 여전히 있음
- 그 두 상수가 코드에 실제로 없음
- 실험 정책 문서가 기본값 꺼짐을 명시하는지
- 각 문서가 500자를 넘는지
앞의 여섯은 정확하고 강하다. 뒤의 둘은 문자열 포함과 길이 검사라서 약하다.
경계 밖에 있는 것은 셋이다.
능력 표. 어댑터 다섯 곱하기 플래그 열둘로 60칸이다 런타임 멤버십 문장 브로커 등급 표의 제한 칸
이 분석이 찾은 문서 드리프트 세 건이 정확히 그 셋 안에 하나씩 있었다. 우연이 아니다. 테스트가 붙드는 항목인 등급 이름과 버전 문자열과 존재하지 않는 상수는 전부 옳았고, 붙들지 않는 항목만 틀렸다.
이것이 이 테스트를 결함으로 만들지는 않는다. 좁게 만든 것은 의도이고 그 이유도 타당하다.
현재 테스트 이름과 문서는 검증 범위를 명시하지 않는다. 그래서 전체 문서가 코드와 일치한다고 읽힐 수 있지만 실제 단언은 여덟 항목에 한정된다.
검증 환경
OpenJDK : 21.0.12 Gradle : 9.0.0 확인 방식 : 테스트 메서드 열거와 문서 대조 소스 수정 : x
재현 조건
원문은 final/evidence/raw/261-messaging-documentation-contract-test-coverage.txt 와 255-messaging-capability-doc-vs-code-drift.txt 에 있다.
- MessagingDocumentationContractTest 의 테스트 메서드를 열거한다. 여덟 개다.
- 각 메서드가 무엇을 단언하는지 확인한다.
- 지원 문서에서 그 여덟 개가 닿지 않는 영역을 식별한다.
- 그 영역을 코드와 대조한다.
본문
doc rot를 막기 위해 존재하는 계약 테스트의 단언 여덟 개가 붙드는 것은 전부 정확하다 — 등급 이름·Kafka 버전 문자열·존재하지 않는 두 enum 상수.
계약 테스트의 단언 여덟 개
:::evidence key="doc-contract-test-boundary-predicted-the-drift" alt="분석 문서 final/document.md 에서 이 기록의 근거 절을 그대로 잘라낸 18줄. 코드베이스를 측정한 것이 아니라 원본 판정이 무엇을 적었는지를 보여 준다." caption="final/document.md 발췌 — 18줄" zoom="true" :::
붙들지 않는 것에 드리프트 세 건이 전부 있다
capability 표 60칸·runtime membership 문장·브로커 등급표의 "제한" 칸이다. 테스트 javadoc은 좁은 단언을 고른 이유까지 옳게 적는다.
테스트가 검증하는 범위를 문서에 명시해야 한다
좁게 고른 것이 결함이 아니다.
확인하지 못한 것
세 건의 드리프트 각각에 대해 그것을 잡는 단언을 실제로 추가해 보지 않았다. 능력 표 60칸을 코드와 대조하는 단언이 유지 가능한 형태인지는 별도 판단이 필요하다.
없음 — 단언 목록과 문서를 전수 대조했다