Files
clean-architecture-backend-…/docs/adr/ADR-BUILD-001-one-convention-for-shared-test-code.md
T
DongHyeonka 74108497d4 docs(records): 기록과 ADR 맨 위에 한국어 머리 블록을 단다
문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시
없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는
거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다.

고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의
.md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일·
요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄
두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함).
- 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거).
- 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는
  설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」.
  capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」,
  2026-07-20 하네스 설계·계획과 production capability platform 설계는
  「대체됨」이다.
- 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신
  docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다.
docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와
코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록
충돌 가능성을 적었다.

버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이
파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는
안은 폴더와 같은 정보를 두 번 쓰게 한다.

위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지
아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을
끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다
(납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는
아직 머리 블록을 달지 않았다.

검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py
rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
2026-11-07 12:23:32 +09:00

7.6 KiB

결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.

  • 상태: 채택
  • 작성일: 2026-09-07
  • 요약: 공유 테스트 코드는 java-test-fixtures 한 가지 방식으로 둔다는 결정이다.
  • 현재 정본: src/build-logic/README.md

ADR-BUILD-001: java-test-fixtures is the standard for shared test code

  • Status: Accepted
  • Date: 2026-09-07
  • Scope: every leaf that publishes or consumes shared test code
  • Source: docs/reviews/2026-09-07-app-bootstrap-module-code-review.md BOOT-015

Context

Two conventions do the same job in this repository.

ca.testkit-publisher — a convention plugin — gives a leaf a testkit source set, wires its output onto the lanes that leaf names, and optionally publishes it as a consumable configuration. Five leaves use it: persistence-jpa (published as jpaTestkit), web (webTestkit), websocket (websocketTestkit), persistence-mongo and httpclient (both unpublished).

java-test-fixtures — Gradle's own plugin — gives a leaf a testFixtures source set, puts it on test's classpath automatically, and always publishes it as a variant consumers reach with testFixtures(project(':x')). One leaf uses it: graphql, which additionally fails its build when a fixture is written outside src/testFixtures/java.

Two conventions for one purpose is the defect. A contributor adding shared test code has to know which leaf they are in before they know where the file goes, and the two answers are not interchangeable: a consumer of the first writes project(path: ':x', configuration: 'jpaTestkit') and has to know the configuration's name, while a consumer of the second writes testFixtures(project(':x')) and does not.

Decision

java-test-fixtures is the standard. New shared test code goes in src/testFixtures/java, and a consumer depends on it with testFixtures(project(':x')).

Three reasons, in order of weight:

  1. The consumer side describes itself. testFixtures(project(':adapter:inbound:web')) says what it is. project(path: ':adapter:inbound:web', configuration: 'webTestkit') says where to look, and only after the reader has learned that webTestkit is a testkit rather than a lane.
  2. The enforcement already exists and is copyable. graphql's build fails when a fixture is declared in the wrong place. The same guard applies unchanged to any leaf that adopts the plugin.
  3. It is one fewer local concept. A convention plugin that reimplements a Gradle plugin has to be maintained against it.

What the local plugin does better, and how it is replaced

This is worth writing down, because the review that prompted this ADR recommended the migration before reading ca.testkit-publisher, and the plugin turns out to encode two deliberate decisions rather than being an oversight.

Publishing is opt-in. persistence-mongo and httpclient have a testkit and publish nothing; persistence-jpa publishes. The plugin's own comment names this as "a real difference in what each leaf offers rather than an oversight to normalise away". java-test-fixtures always creates the variant, so the distinction is lost — a leaf that never meant to offer its fixtures will offer them.

Replacement: none at the build level. The distinction moves to review: the fixtures of a leaf that nobody consumes are simply unconsumed. This is a real, accepted loss.

Lane consumption is declared. persistence-jpa says consumedBy 'test', 'postgresqlIntegrationTest'. java-test-fixtures puts fixtures on test only, so every other lane needs the output added explicitly.

Replacement: strictTestLanes' existing compilesAgainst expresses this unchanged — a lane declares compilesAgainst 'main', 'testFixtures'. The first draft of this ADR assumed the DSL would need a change, because sourceSet(name) creates what it is given and testFixtures already exists. The persistence-mongo migration showed otherwise: compilesAgainst only looks a source set up, so naming a plugin-created one works as-is. What the leaf drops is the sourceSet('testkit') declaration, not the lane's.

Migration: done, and what it cost

Five leaves, eleven lanes, two published testkits, all migrated leaf by leaf with the suite run between each. ca.testkit-publisher is deleted.

The order was chosen so a mistake would be cheap: unpublished leaves first, published ones last with their consumer in the same step.

  1. persistence-mongo — one leaf, two lanes, no cross-module consumer; the proof the path works. What it took, per leaf:
    • apply plugin: 'java-test-fixtures' at the top of the leaf build file;
    • git mv src/testkit src/testFixtures;
    • drop sourceSet('testkit') and the whole testkitPublisher block; keep every other lane's compilesAgainst, renaming 'testkit' to 'testFixtures';
    • rename testkitImplementation to testFixturesImplementation, and add what the old source set was inheriting silently. This is the one non-mechanical step: testkit* extended testImplementation, so the fixtures saw every test library the leaf declared. Mongo's needed four more lines (AssertJ, BSON, Spring Data commons, Toxiproxy) — none of which the leaf had ever stated the fixtures depended on;
    • regenerate the leaf's lock state.
  2. httpclient, then websocket — unpublished as well, more lanes.
  3. web and persistence-jpa with app-bootstrap's two consumer declarations, which became testImplementation(testFixtures(project(':…'))).
  4. ca.testkit-publisher deleted, along with its plugins {} entry and its application in the root build.

Two things the migration broke, and what they taught

Both were caught by tests that exist to catch exactly this, which is the argument for having them.

ArchUnit corpora went wrong in opposite directions. httpclient's boundary rules excluded build/classes/java/testkit; after the move the fixtures arrived as a …-test-fixtures.jar on the same classpath, so the exclusion missed them and 258 fixture-to-fixture calls were reported as production depending on the testkit. persistence-jpa's rules included only build/classes/java/main; applying java-test-fixtures makes the module's own test classpath carry the module as a jar rather than as a class directory, so its corpus became empty. The second is the dangerous one — an empty corpus makes every noClasses() rule pass — and it surfaced only because that suite asserts its corpus is non-empty before asserting anything about it.

Fixtures had invisible dependencies. testkit* configurations extended testImplementation, so the fixtures compiled against every test library their leaf declared without ever naming one. Making them explicit took roughly thirty testFixturesImplementation lines across the five leaves — Micrometer, Spring Web, Netty, logback, Jackson, JUnit, AssertJ, Spring Data. None of them were wrong; none of them were stated.

Consequences

  • docs/testing/TESTING_STRATEGY.md §5 records the standard; this ADR records why and at what cost.
  • Until step 5, two conventions remain visible. The strategy document says so explicitly, so a contributor reading it is not left to infer which one is current.
  • The opt-in-publishing distinction is given up. If it later proves load-bearing — a leaf whose fixtures genuinely must not be reachable — the answer is a separate module, not a third convention.