API 테스트 계약표 표준 원칙 7이 색을 넷으로 늘리면서 이렇게 적었다.
노랑이 이 표준의 핵심이다. “계약에는 적었는데 테스트가 없는 칸” — 그게 처음의 불안이었고, 이제 사람의 성실함이 아니라 기계가 잡는다.
그런데 기계가 잡기만 한다. 노랑이 떠도 빌드는 초록이고, 표는 build/ 아래 HTML로 떨어질 뿐이다. 열린 항목 장부에 이 질문이 그대로 남아 있었다 — “노랑이 뜨면 CI를 막을 것인가.”
막는 쪽으로 가려고 실제 프로젝트를 열어보니, 그 전에 답해야 할 것이 둘 있었다.
먼저: 이미 정해져 있어 다시 고르지 않은 것
계약의 모양과 색의 뜻은 끝났다. 아래 원칙 번호는 모두 API 테스트 계약표 표준의 것이다. 계약은 저장소의 {도메인}Contract enum이 소유하고(계약표 표준 원칙 9), 테스트는 계약 enum 안에 중첩한 Verify(enum 값)으로 잇고(계약표 표준 원칙 8), 색은 초록·빨강·노랑·회색 넷이다(계약표 표준 원칙 7 — 이 글 원칙 3에서 파랑이 갈라져 다섯이 된다). 이 글은 그 색 하나(노랑)를 무엇으로 계산하고, 떴을 때 무엇을 할지만 다룬다.
표를 손으로 칠하지 않는다는 것도 끝났다. 계약표 표준 원칙 7이 이미 정했다. 그래서 아래 원칙 3에서 표를 고칠 때도 색칠 규칙만 바꾸고 사람이 개입할 자리를 만들지 않는다.
원칙 1. 노랑은 실행 결과가 아니라 정적 스캔으로 센다
막기로 정하기 전에, 지금 노랑이 무엇으로 계산되는지를 먼저 봐야 했다.
// ContractReportListener — 테스트가 끝날 때마다 결과를 모은다
executionFinished(...) → results.put(contract, status)
// 색칠할 때
backgroundOf(null) → UNTESTED // 기록이 없으면 노랑
한 줄씩 따라가기 — ContractReportListener는 테스트 하나가 끝날 때마다(executionFinished) 그 테스트가 가리키는 계약(contract)과 결과(status)를 표(results)에 적어 넣는 감시자다. 표를 색칠할 때는 그 표에서 어떤 계약을 찾아본다 — 기록이 아예 없으면(backgroundOf(null)) 그 칸을 노랑(UNTESTED)으로 칠한다.
노랑은 “테스트가 없다”가 아니라 “이번 실행에서 그 계약을 가리킨 테스트가 안 끝났다”였다. 리스너는 실행을 관찰하는 물건이라 그것 말고는 알 수가 없다.
그래서 --tests로 일부만 돌리면 안 돌린 계약이 전부 노랑으로 찍힌다. results.isEmpty()면 표를 안 쓰는 방어가 하나 있지만, 그건 계약 테스트를 하나도 안 돌렸을 때만 걸린다. 하나라도 걸치면 나머지가 통째로 노랑이 된다.
무엇을 돌렸느냐에 따라 답이 바뀌는 것은 게이트가 아니다. 개발자가 테스트 하나만 돌려보는 순간 빌드가 빨개지면, 그 게이트는 하루 만에 꺼진다.
안 A — 실행 결과를 쓰되 “전체 실행일 때만” 게이트를 켠다. 얻는 것은 리스너를 안 고쳐도 된다는 점이다. 버린 이유는 “전체 실행”을 판별할 방법이 미덥지 않다는 것이다. 태그로 거르거나 클래스 하나만 돌리는 것도 전부 정당한 실행인데, 그 각각이 전체인지 아닌지를 리스너가 알 방법이 없다. 결국 CI에서만 켜는 환경 변수로 가게 되고, 그러면 로컬에서는 아무도 안 보는 검사가 된다.
골랐다 — 안 B, 클래스패스를 훑어 계약을 가리키는 애노테이션이 붙은 메서드를 센다.
// 실행과 무관하다. 어느 테스트를 돌렸든 답이 같다.
Set<ContractTable> tested = ContractCoverage.testedContracts();
한 줄씩 보면 — ContractCoverage.testedContracts()는 클래스패스의 테스트 클래스를 훑어, 계약을 가리키는 애노테이션이 붙은 메서드가 있는 계약을 모아 돌려준다. 돌려받는 Set<ContractTable>은 모든 도메인의 계약표가 공통으로 구현하는 ContractTable 타입의 묶음이다. 이 글을 처음 쓸 때는 경쟁사 계약표 하나뿐이라 Set<CompetitorContract>였고, 한 프로젝트가 2026-08-20에 계약표 기계를 도메인에서 떼어 냈고 그 모양을 2026-10-21에 표준으로 올리면서 바뀌었다(계약표 표준 원칙 12). 그래서 스캔은 애노테이션의 타입을 박지 않고 「value()가 계약표의 상수를 돌려주는 애노테이션」이면 무엇이든 센다 — 도메인마다 CompetitorContract.Verify, CareContractContract.Verify처럼 따로 있기 때문이다.
안 A가 못 지켜주는 것은 답의 안정성이다. 정적 스캔은 “테스트가 존재하는가”를 묻고, 그 답은 무엇을 돌렸는지와 상관없다.
클래스를 전부 로드하지 않는다. ASM(클래스 파일을 직접 읽어 그 안에 어떤 메서드·애너테이션이 있는지 코드를 실행하지 않고 뽑아내는 바이트코드 분석 라이브러리) 기반 메타데이터로 계약을 가리키는 애노테이션을 단 메서드가 있는 클래스만 먼저 거른 뒤, 그 몇 개만 리플렉션으로 읽는다. 애노테이션 값이 enum이라 값을 타입 그대로 얻으려면 결국 로드가 필요한데, 전부 로드하면 테스트와 무관한 클래스의 초기화까지 끌고 온다.
대가는 스캔이 컴파일된 결과를 본다는 것이다. 소스에 Verify를 적어도 컴파일 전에는 안 보인다. 실무에서 테스트를 돌리는 시점에는 이미 컴파일이 끝나 있으므로 문제가 되지 않았다.
원칙 2. 못 짜는 계약은 이유를 적어 유예하고, 이유 없는 노랑은 빌드를 막는다
정의를 고치고 세어보니 16개 중 8개가 노랑이었다. 그런데 그 8개를 들여다보니 전부 이미 문서화돼 있었다.
여기서 검증할 수 없는 계약이 둘 있다. 401 계약은 standalone MockMvc에 Security 필터가 붙지 않아 인증을 거치지 않는다. 삭제된 경쟁사 계약은 없는 번호와 실패 경로가 같아 UseCase를 스텁으로 두면 둘을 가를 수 없다. 표에서 노랑으로 남는다.
—
CompetitorContractTestJavadoc
Javadoc의 「둘」은 계약 두 개가 아니라 두 종류다. 그때 경쟁사 계약 16개 중 401 계약이 다섯(목록 · 조회 · 생성 · 수정 · 삭제마다 하나), 삭제된 경쟁사 계약이 셋(조회 · 수정 · 삭제)이라 합쳐 8개였다(그 프로젝트의 커밋 c5b3fe1 직전의 CompetitorContract).
(여기서 MockMvc는 스프링 서버를 띄우지 않고 Controller만 떼어 테스트하는 도구인데, “standalone”은 그중에서도 Security 설정까지 포함한 전체 스프링 설정을 올리지 않고 Controller 객체 하나만 두고 테스트하는 방식이다. 이 방식에서는 Security 필터 자체가 없으므로 401을 내야 하는 상황이 와도 필터가 막아주지 않는다. 그리고 “삭제된 경쟁사 계약”은 테스트에서 진짜 UseCase 대신 가짜 응답을 미리 정해둔 스텁으로 바꿔 끼우면, “그런 번호가 원래 없다”와 “있었는데 삭제됐다”가 똑같이 “실패”로만 돌아와 서로 구분이 안 된다는 뜻이다.)
노랑 8개는 잊은 것이 아니라 정한 것이었다. 그대로 막으면 의도적으로 남긴 8개 때문에 빌드가 즉시 빨개진다.
여기서 노랑이 실은 두 종류였다는 게 드러난다.
| 노랑 | 대응 |
|---|---|
| 잊어서 안 짠 것 | 막아야 한다 |
| 지금 하네스로 못 짜는 것 | 막으면 개발이 멈춘다 |
둘은 대응이 정반대인데 색이 같다. 계약표 표준 원칙 7이 초록·빨강만으로는 부족하다며 노랑을 만든 것과 똑같은 모양이 노랑 안에서 한 겹 더 나온 것이다.
안 A — 하네스를 고쳐 8개를 다 짜고 게이트를 켠다. 얻는 것은 유예라는 개념 자체가 필요 없다는 점이다. 버린 이유는 이 항목이 묻는 질문이 아니라는 것이다. 장부의 질문은 “막을 것인가”이지 “어떻게 테스트할 것인가”가 아니다. 하네스 개선을 게이트의 선행 조건으로 묶으면 둘 다 안 끝난다. 그리고 하네스를 고쳐도 다음에 또 못 짜는 계약이 나오면 같은 자리에서 다시 막힌다 — 구조가 아니라 이번 8개만 푸는 것이다.
안 B — 게이트에 면제 목록(baseline)을 둔다. 지금 노랑인 것들을 파일에 적어두고 그것만 빼준다. 얻는 것은 도입이 즉시 가능하다는 점이다. 버린 이유는 짝을 손으로 적는 곳이 생긴다는 것이다. 이 저장소가 standards-pairing.rb에서 매핑 테이블 안을 버린 것과 같은 판단이고, 무엇보다 목록에는 왜 면제인지가 안 남는다.
골랐다 — 안 C, 계약 옆에 유예 표시를 달고 이유를 필수로 받는다.
@Pending("standalone MockMvc에 Security 필터가 붙지 않아 인증을 거치지 않는다")
S401_LIST_ANONYMOUS_ANY("GET /api/v1/admin/competitors", Actor.비로그인, CompetitorState.무관, 401),
한 줄씩 따라가면 — 괄호 안 넷은 차례로 endpoint · actor · state · expect다. endpoint의 "GET /api/v1/admin/competitors"는 “경쟁사 목록을 가져와라”는 요청을 가리키는 주소이고, actor의 Actor.비로그인은 그 요청을 보내는 사람이 로그인하지 않은 상태라는 뜻이고, state의 CompetitorState.무관은 목록 조회라 대상 경쟁사의 상태를 가리지 않는다는 뜻이다. expect의 401은 그 요청이 401로 거절돼야 정상이라는 뜻이다. @Pending은 지금은 이 계약을 검증할 수 없다는 표시이고, 괄호 안 문자열이 그 이유다.
안 B가 못 지켜주는 것은 이유가 계약 옆에 붙어 있다는 것이다. 별도 목록은 계약과 떨어져 살아서 한쪽만 고치면 어긋나는데, 표시는 계약 상수에 붙어 있으므로 계약을 지우면 같이 사라진다.
그리고 이 결정은 원래 있던 것을 옮긴 것이기도 하다. “못 짠다”는 판단은 이미 Javadoc 산문에 있었는데, 산문이라 기계가 못 읽어서 게이트가 볼 수 없었다. 계약표 표준 원칙 1이 검증하지 않기로 한 칸에 −를 적게 한 것과 같은 모양이다 — 잊은 것과 정한 것을 가르려면 정한 것을 적을 자리가 있어야 한다.
이유를 필수로 받는 이유는 표시가 면제권이 되지 않게 하려는 것이다. 이유 없이 달 수 있으면 테스트를 짜기 싫을 때마다 붙게 되고, 그 순간 이 표시는 노랑을 숨기는 도구가 된다. 애노테이션 값에 기본값을 주지 않는 것만으로 컴파일러가 이걸 강제한다.
대가는 유예가 늘어나는 것을 기계가 못 막는다는 것이다. 이유를 적기만 하면 통과하므로, 이유가 성의 없어지는 것은 리뷰가 봐야 한다. 그래도 이유 없는 면제 목록보다 나은 이유는 리뷰가 볼 것이 코드에 남기 때문이다.
유예가 낡으면 그것도 실패다
유예를 빼주기만 하면 표시가 영원히 남는다. 하네스가 좋아져 테스트를 짤 수 있게 돼도 아무도 떼지 않고, 그러면 결국 노랑을 쌓아두는 것과 같아진다.
그래서 게이트는 양방향이다.
| 상태 | 결과 |
|---|---|
| 테스트 있음 | 통과 |
| 테스트 없음 + 유예 있음 | 통과 |
| 테스트 없음 + 유예 없음 | 실패 — 짜거나, 못 짜는 이유를 적는다 |
| 테스트 있음 + 유예 남음 | 실패 — 유예를 뗀다 |
라우트-계약 정합성 표준에서 양방향을 본 것과 같은 이유다. 한 방향만 보면 반대쪽이 조용히 쌓인다.
원칙 3. 게이트와 표는 같은 정의를 쓴다
노랑의 정의를 바꿨으면 표도 같이 바뀌어야 한다. 게이트는 정적 스캔으로 판정하는데 표는 실행 결과로 칠하면, 같은 칸을 두고 둘이 다른 말을 한다.
그래서 리스너의 노랑도 정적 스캔이 정하게 바꿨고, 그러자 자리 하나가 비었다 — 테스트는 있는데 이번 실행에서 안 돈 계약이다. 예전에는 이것도 노랑이었지만 이제 노랑은 “테스트가 없다”만 뜻한다.
| 색 | 뜻 |
|---|---|
| 초록 | 테스트 있고 통과 |
| 빨강 | 테스트 있고 실패 |
| 노랑 | 테스트가 없다 (유예면 이유가 함께 찍힌다) |
| 파랑 | 테스트는 있는데 이번 실행에서 안 돌렸다 |
| 회색 | 그 칸에 계약 자체가 없다 |
색이 하나 늘었지만 늘어난 게 아니라 갈라진 것이다. 예전 노랑이 두 가지를 뜻하고 있었고, 그걸 못 가른 것이 애초에 게이트를 못 만든 이유였다. (원칙 5의 「설정 — 배포 때 확인」 계약을 이 표에서 어떻게 보일지는 아직 정하지 않았다 — 원칙 5 끝에 적었다.)
빌드를 막는 것은 표가 아니라 테스트다. 표는 사람이 보는 것이라 안 보면 그만이고, 리스너는 리포트를 쓸 뿐 종료 코드에 영향을 주지 않는다. 종료 코드는 프로그램이 끝나면서 남기는 숫자 하나인데, 빌드 도구는 이 숫자가 0이 아니면 “실패했다”고 판단해서 빌드를 멈춘다. 리스너가 표를 그려도 이 숫자를 안 건드리면 빌드 입장에서는 아무 일도 없었던 것과 같다. 게이트는 별도의 테스트 클래스가 맡는다 — 그래야 Gradle로 테스트를 돌리는 명령인 gradlew test가 그냥 실패한다.
원칙 4. 400 행과 요청 DTO의 검증 어노테이션도 양방향으로 대조한다
계약표 표준 원칙 5가 2026-10-21에 입력 형식 계약(400)을 바꿨다. 어노테이션에서 행을 생성하지 않고, 사람이 계약 enum에 400 행을 손으로 쓴다. 왜 생성하지 않는지(어노테이션을 베낀 테스트는 어노테이션이 틀리면 같이 틀린다)는 그쪽에 있다. 여기서 정할 것은 게이트가 그 행을 어떻게 지키느냐다.
사람이 쓰는 행은 빠뜨릴 수 있다. 요청 DTO의 필드에 붙이는 @Size(max = 200) 같은 것이 검증 어노테이션이다 — 요청 값이 그 조건을 어기면 스프링이 컨트롤러 코드에 닿기 전에 400으로 거절한다. 이것을 새로 붙이고 400 행을 안 적어도, 지금 게이트는 「있는 계약에 테스트가 있는가」만 보므로 아무 말도 안 한다. 반대로 어노테이션을 지웠는데 400 행이 남으면, 그 행의 테스트가 어쩌다 다른 이유로 400을 받아 초록으로 남을 수 있다.
그래서 게이트가 두 방향을 더 본다.
| 상태 | 결과 |
|---|---|
| 검증 어노테이션 있음 + 400 행 있음 | 통과 |
| 검증 어노테이션 있음 + 400 행 없음 | 실패 — 행을 빠뜨렸다 |
| 400 행 있음 + 검증 어노테이션 없음 | 실패 — 어노테이션이 사라졌거나 행이 틀렸다 |
원칙 2의 낡은 유예 검사, 라우트-계약 정합성 표준의 양방향 검사와 같은 모양이다. 어노테이션과 행이 따로 진술되고 기계가 둘을 맞대어 보기 때문에, 한쪽만 바뀌면 빌드가 멈춘다.
이 대조를 하려면 게이트가 「이 400 행은 serviceHours의 @NotBlank를 가리킨다」를 읽을 수 있어야 한다. 상황 이름 CareContractState.서비스_시간이_빔만으로는 못 읽는다. 그래서 400 행만 생성자 다섯째 인자로 Violation.of("serviceHours", NotBlank.class)(필드 이름, 제약 어노테이션 타입)를 받아 Cell에 담기로 했다(2026-10-21). Cell은 계약 상수 하나가 표의 어느 칸인지(엔드포인트 · 부르는 사람 · 상황 · 기대 응답)를 담는 값 객체다(계약표 표준 원칙 12). NotBlank.class는 @NotBlank라는 어노테이션 타입 자체를 값으로 넘긴다는 뜻이다.
게이트는 반대쪽 재료를 이렇게 얻는다 — 엔드포인트를 처리하는 컨트롤러 메서드의 매개변수 중 @Valid @RequestBody가 붙은 것의 타입(요청 DTO)을 리플렉션으로 열어, 필드마다 붙은 검증 어노테이션을 읽어 (필드, 제약 타입) 묶음을 만든다. 그 묶음과 그 엔드포인트 400 행들의 Violation 묶음을 양방향으로 맞대어, 어느 쪽이든 남으면 실패시킨다.
대가는 아직 아무 데도 구현되지 않았다는 것이다. 그 프로젝트의 400 행에도 Violation 인자가 없고, 대조하는 게이트도 없다. 표기와 방법을 정한 약속일 뿐이라, 구현되기 전까지는 빠뜨린 400 행을 여전히 아무도 잡지 못한다.
원칙 5. 누가 고쳐야만 깨지는 설정 계약은 「설정 — 배포 때 확인」으로 표시하고, 게이트는 세지 않는다
그 프로젝트의 로그 파일 롤링 이슈는 계약 여섯이 전부 설정이었다 — 로그가 컨테이너 밖에 남는다(컴포즈 볼륨), 크기 · 날짜로 나뉜다(logback-spring.xml), 운영은 INFO로 찍는다, 배포해도 안 지워진다(Jenkinsfile) 같은 것들이다. 계약 번호마다 테스트를 대응시켰더니 테스트 코드가 1,058줄 나왔고, 그 대부분은 검증이 아니라 설정 파일을 다시 읽어 해석하는 기계였다. 「운영에서 로그가 남는다」가 아니라 「설정 파일에 그렇게 적혀 있다」를 본 것이다.
설정 계약을 테스트할지 말지는 테스트 층위 선택 표준이 정한다. 이 글이 정할 것은 그 결과 — 짜지 않기로 한 계약을 게이트가 어떻게 다루는가다. 지금 게이트에는 칸이 둘뿐이다. 테스트가 있거나, 없으면 @Pending으로 유예하거나.
안 A — 설정 계약은 이슈에 아예 안 쓴다. 얻는 것은 게이트를 안 고쳐도 된다는 점이다. 버린 이유는 기획이 무엇을 정했는지가 사라진다는 것이다. 「운영 로그는 INFO」는 정한 계약이고, 안 적으면 다음 사람은 그 결정이 있었는지조차 모른다.
안 B — @Pending으로 유예한다. 얻는 것은 표시를 새로 만들 필요가 없다는 점이다. 버린 이유는 뜻이 정반대라는 것이다. 유예는 「지금 하네스로 못 짜서 미룬 것」이라 하네스가 좋아지면 떼야 하고, 테스트가 생겼는데 남아 있으면 원칙 2가 실패로 잡는다. 설정 계약은 「짜지 않기로 한 것」이라 뗄 날이 오지 않는다. 둘을 한 표시에 섞으면 유예 목록을 볼 때 「언젠가 짤 것」과 「영원히 안 짤 것」이 구별되지 않는다 — 원칙 2가 노랑을 둘로 가른 것과 같은 실수를 유예 안에서 다시 하게 된다.
골랐다 — 안 C, 「설정 — 배포 때 확인」이라는 별도 표시를 단다. 계약은 이슈에 그대로 적고, 이 표시가 붙은 계약은 게이트가 세지 않는다. 안 A가 못 지켜주는 것은 결정이 기록에 남는다는 것, 안 B가 못 지켜주는 것은 「못 짠 것」과 「안 짜기로 한 것」이 갈린다는 것이다.
대가는 둘이다. 표시가 면제권이 될 수 있다 — 동작이 있는 계약에 이 표시를 달면 노랑이 사라진다. @Pending과 같이 사람이 리뷰로 봐야 한다. 그리고 이 표시를 코드에 어떤 모양으로 두는지(애노테이션 이름 등)는 아직 정하지 않았다. 결과 표에서 이 칸을 어떻게 보일지도 마찬가지다 — 지금 리스너 그대로면 테스트가 없으니 노랑으로 칠해지는데, 노랑은 「채워야 할 칸」이라는 뜻이라 이 계약에 맞지 않는다. 표시를 정하는 일은 남아 있다.
원칙 6. 테스트 실행이 끝나면 전체 스위트 소요 시간을 한 줄 남기고, 예산 숫자는 아직 박지 않는다
이 게이트는 테스트를 늘리는 방향으로만 당긴다. 계약이 늘면 칸이 늘고, 칸을 안 채우면 빌드가 멈춘다. Meszaros는 『xUnit Test Patterns』에서 Too Many Tests(256쪽)를 느린 테스트의 원인 중 하나로 이름까지 붙여 두었고, 느림이 「테스트를 덜 돌린다 → 버그가 운영에 샌다」로 이어진다고 그렸다. 그런데 표준 어디에도 테스트 속도에 대한 줄이 없었다.
먼저 쟀다. 처음 잰 것은 2026-08-24이고, 2026-10-21에 두 번 더 쟀다(그 프로젝트의 build/test-results). 두 번째와 세 번째는 같은 날 같은 테스트를 다시 돌린 것이다.
측정일 테스트 수 걸린 시간 테스트당 가장 큰 단일 항목
2026-08-24 501개 87초 (컴파일 포함) 약 0.17초 PcsApplicationTests 16초
2026-10-21 1,214개 벽시계 약 4분 50초 · 클래스별 합 283초 약 0.24초 PcsApplicationTests 56초 (합의 약 20%)
2026-10-21 1,214개 벽시계 약 6분 33초 · 클래스별 합 381초 약 0.32초 PcsApplicationTests 112초 (합의 약 29%)
테스트당 시간은 벽시계 시간을 테스트 수로 나눈 값이다(87 ÷ 501, 290 ÷ 1,214, 393 ÷ 1,214).
시간은 테스트 수와 함께 늘고 있다. 테스트가 약 2.4배가 되는 동안 걸린 시간은 3배 넘게 늘었고, 테스트당 시간도 약 0.17초에서 0.24초로 올랐다. 87초는 컴파일까지 포함한 값이라 조건이 꼭 같지는 않지만, 컴파일을 빼면 앞쪽 숫자가 더 작아질 뿐이라 늘었다는 결론은 그대로다.
가장 큰 단일 항목은 스프링 기동이다. 맨 먼저 도는 PcsApplicationTests가 스프링 컨텍스트와 DB 컨테이너를 띄우는 비용을 혼자 물고, 뒤의 테스트는 그것을 재사용한다. 그래도 합의 20~29%다 — 나머지는 테스트 하나하나가 쌓은 시간이다. 그리고 같은 테스트를 같은 날 두 번 돌려도 합이 283초와 381초로 흔들렸다.
DB는 지금처럼 Testcontainers로 띄운 실물을 쓰고, 이 원칙에서 바꾸지 않는다. Khorikov가 『Unit Testing: Principles, Practices, and Patterns』 8.2절(190쪽)에서 「DB는 실물로 테스트한다」고 한 쪽이다. 가짜 DB로 바꾸면 얼마나 줄어드는지는 재지 않았다.
정해야 했던 건 이거였다 — 그러면 표준에 무엇을 적는가.
안 A — 시간 예산을 숫자로 박는다. 「전체 스위트 N분을 넘으면 실패」 같은 것이다. 얻는 것은 느려지는 순간 빌드가 알려 준다는 점이다. 버린 이유는 그 숫자의 근거가 없다는 것이다. 실측은 세 번뿐이고, 같은 날 같은 테스트를 두 번 돌린 값마저 283초와 381초로 흔들렸다. 이 흔들림을 모르고 박은 선은 테스트가 하나도 안 늘어도 넘었다 안 넘었다 한다. 근거 없이 박은 숫자는 계약표 표준 원칙 1이 버린 「계약은 최소 다섯 개」처럼 지어낸 값이 된다.
안 B — 아무것도 안 남긴다. 지금은 느리지 않으니 할 일이 없다는 쪽이다. 버린 이유는 느려지는 것을 아무도 못 본다는 것이다. 이번 측정도 누가 이슈를 열고 일부러 재서야 나왔다.
골랐다 — 안 C, 실행이 끝날 때마다 전체 스위트 소요 시간을 한 줄 남기고, 다시 볼 조건만 적는다. 결과 표 리스너가 찍는다 — 리스너는 테스트 계획 전체가 끝나는 순간을 아는 자리이고, 게이트 테스트는 스위트 중간에 도는 테스트 하나라 전체 시간을 모른다. 이 한 줄은 아직 구현 전이다. 그 프로젝트의 ContractReportListener는 지금 표만 쓰고 시간은 남기지 않으며, 한 줄을 어디에 남길지도 구현할 때 정한다. 안 A가 못 지켜주는 것은 근거 없는 숫자를 안 만든다는 것, 안 B가 못 지켜주는 것은 추세가 매번 눈에 보인다는 것이다. 그 한 줄이 쌓이면 나중에 예산을 정할 근거가 된다.
다시 열 조건은 「10분을 넘으면」이다 — 지금(약 5~6분 반)의 1.5~2배쯤이다. 그때 먼저 볼 것은 둘이다. 하나는 컨텍스트 캐시(한 번 띄운 스프링 컨텍스트를 다음 테스트 클래스가 재사용하는 것)가 깨져 기동이 여러 번 일어났는가다 — 가장 큰 단일 항목이 기동이기 때문이다. 다른 하나는 테스트 수가 늘어난 추세다 — 시간이 테스트 수와 함께 늘고 있기 때문이다.
대가는 한 줄은 아무것도 막지 않는다는 것이다. 10분을 넘어도 빌드는 초록이고, 그 줄을 보는 사람이 있어야 조건이 작동한다.
판단 기준 정리
| 질문 | 답 | 왜 |
|---|---|---|
| 노랑을 무엇으로 세나 | 클래스패스 정적 스캔 | 실행 결과로 세면 무엇을 돌렸느냐에 따라 답이 바뀐다 |
| 노랑이 뜨면 | 빌드를 막는다 | 안 막으면 표를 안 보는 순간 쌓인 채 잊힌다 |
| 못 짜는 계약은 | 이유를 적어 유예한다 | 잊은 노랑과 정한 노랑은 대응이 정반대다 |
| 유예에 이유가 필수인가 | 그렇다 | 이유 없이 달 수 있으면 노랑을 숨기는 도구가 된다 |
| 면제 목록 파일은 | 안 쓴다 | 계약과 떨어져 살면 어긋나고, 왜 면제인지가 안 남는다 |
| 유예가 낡으면 | 그것도 실패다 | 안 그러면 표시가 영원히 남아 노랑을 쌓는다 |
| 표와 게이트의 관계 | 같은 정의를 쓴다 | 다르면 같은 칸을 두고 둘이 다른 말을 한다 |
| 막는 주체는 | 표가 아니라 테스트 | 리포트는 종료 코드에 영향을 주지 않는다 |
| 400 행은 | Violation(필드, 제약 타입)을 요청 DTO의 검증 어노테이션과 양방향 대조(아직 구현 전) |
사람이 쓰는 행은 빠뜨릴 수 있고, 어노테이션이 사라져도 행이 남는다 |
| 설정만 바꾸는 계약은 | 「설정 — 배포 때 확인」으로 표시하고 세지 않는다 | 안 쓰면 결정이 사라지고, 유예에 섞으면 「못 짠 것」과 「안 짜기로 한 것」이 갈리지 않는다 |
| 스위트 시간은 | 실행 끝에 한 줄 남긴다(아직 구현 전). 예산 숫자는 아직 없다 | 측정이 세 번뿐이고 같은 날 두 번 잰 값도 흔들렸다. 10분을 넘으면 컨텍스트 기동 횟수와 테스트 수 추세부터 본다 |
이 표준을 정하기까지
시작은 장부에 남아 있던 항목 하나였다. “노랑이 뜨면 CI를 막을 것인가.” 바로 앞에 라우트-계약 정합성 표준에서 “어긋나면 빌드를 막는다”를 정한 참이라, 같은 판단을 여기도 적용하면 끝나는 줄 알았다.
먼저 물은 것이 “지금 노랑을 어떻게 측정하고 있나”였다. 막는 것을 정하기 전에 무엇을 막을지부터 봐야 했는데, 이게 이 표준의 방향을 통째로 바꿨다. 리스너 코드를 읽어보니 노랑은 “테스트가 없다”가 아니라 “이번 실행에서 안 돌았다”였다. 리스너는 실행을 관찰하는 물건이라 그것밖에 알 수 없었던 것이다. 그 신호로는 막을 수 없다는 게 분명해졌고, “막을 것인가”를 답하기 전에 “노랑이 무엇인가”를 다시 정해야 한다는 순서가 나왔다.
정의를 고치고 세어보니 두 번째 발견이 나왔다. 노랑이 8개인데, 그 8개가 전부 CompetitorContractTest의 Javadoc에 이유와 함께 적혀 있었다. 잊은 게 아니라 정한 것이었다. 그대로 막으면 의도적으로 남긴 것 때문에 빌드가 빨개진다는 뜻이라, 여기서 “막는다/안 막는다”의 이분법이 깨졌다.
그 순간 노랑 안에서 색이 한 겹 더 갈렸다. 계약표 표준 원칙 7이 초록·빨강만으로는 “계약 있는데 테스트 없음”이 안 보인다며 노랑을 만들었는데, 똑같은 논리가 노랑 안에서 반복된 것이다 — 잊은 노랑과 못 짜는 노랑은 대응이 정반대인데 색이 같았다. 같은 실수를 같은 글이 한 겹 아래에서 다시 하고 있었다.
해법도 같은 글에 이미 있었다. 계약표 표준 원칙 1이 검증하지 않기로 한 칸에 −를 적게 한 것 — “다 채우는 것이 목표가 아니다. −는 안 본다는 결정이고, 그 결정을 적을 자리가 생기는 것이 이 표의 값이다.” 유예 표시는 그것과 같은 장치를 노랑에 적용한 것이다. 그리고 실제로 적을 내용은 이미 있었다 — Javadoc 산문에 있던 것을 기계가 읽는 자리로 옮긴 것뿐이다.
면제 목록 파일 안은 빨리 버려졌다. standards-pairing.rb를 만들면서 매핑 테이블을 버린 것과 같은 근거였고, 여기엔 이유가 하나 더 있었다 — 목록에는 왜 면제인지가 안 남는다. 이유가 남지 않으면 6개월 뒤에 그 줄이 아직 유효한지 판단할 수 없고, 그러면 아무도 못 지우는 줄이 된다.
낡은 유예를 실패로 잡는 규칙은 바로 앞 표준에서 배운 것이다. 유예를 빼주기만 하면 표시가 영원히 남는다는 걸 라우트-계약 정합성의 양방향 검사가 이미 가르쳐줬다. 한 방향만 보면 반대쪽이 조용히 쌓인다.
그다음 게이트가 진짜 우는지 확인했다. 계약표 표준 원칙 6(“상태 코드만 보는 테스트는 무엇을 망가뜨려도 울지 않는다”)을 게이트 자신에게 적용한 것이다. 유예를 하나 떼보고, 테스트가 있는 계약에 유예를 달아보고, 둘 다 실패하는 것과 원복하면 통과하는 것을 확인했다. 검사를 만들었으면 그 검사도 뮤테이션을 통과해야 한다 — 안 그러면 초록을 보고 안심하는 자리가 하나 더 생길 뿐이다. 운영 코드를 망가뜨려 계약 칸이 죽는지 보는 것은 이것과 다른 일이고, 계약표 표준 원칙 14가 맡는다.
계약표 기계가 도메인에서 떨어지자 게이트도 따라 바뀌었다(2026-10-21). 이 글을 쓸 때 게이트는 CompetitorContract를 직접 알았다. 그 프로젝트가 계약표를 ContractTable 인터페이스로 묶으면서 게이트는 그 인터페이스를 구현한 enum을 찾아 전부 돌게 됐고, 계약을 가리키는 애노테이션도 타입을 박지 않고 「value()가 계약표인 것」으로 찾게 됐다. 계약표가 28개로 늘었는데 게이트 코드는 한 줄도 늘지 않았다.
같은 날 원칙이 셋 늘었다 — 게이트가 새로 지킬 것이 둘, 리스너가 새로 남길 것이 하나다. 계약표 표준이 400 행을 사람이 쓰게 바꾸자, 빠뜨린 행을 잡을 자리가 필요해져 검증 어노테이션과의 양방향 대조가 붙었다(원칙 4). 설정만 바꾸는 이슈에서 1,058줄짜리 테스트가 나온 것을 보고, 짜지 않기로 한 계약을 유예와 다른 표시로 갈랐다(원칙 5) — 원칙 2에서 노랑을 둘로 가른 것과 같은 일이 유예 안에서 한 번 더 일어난 것이다. 그리고 「이 게이트가 테스트를 늘리기만 한다」는 지적에 실제로 재 보니, 시간은 테스트 수와 함께 늘고 있었고 가장 큰 단일 항목은 스프링 기동이었다. 그런데 같은 날 두 번 잰 값마저 흔들려 막는 선을 그을 근거는 없었다. 그래서 막는 숫자 대신 매번 보이는 한 줄을 결과 표 리스너가 남기게 했다(원칙 6, 아직 구현 전).
정리
- 노랑은 실행 결과가 아니라 정적 스캔으로 센다. 무엇을 돌렸느냐에 따라 답이 바뀌면 게이트가 아니다
- 이유 없는 노랑은 빌드를 막는다. 안 막으면 표를 안 보는 순간 쌓인 채 잊힌다
- 못 짜는 계약은 이유를 적어 유예한다. 잊은 노랑과 정한 노랑은 대응이 정반대다
- 유예의 이유는 필수다. 이유 없이 달 수 있으면 노랑을 숨기는 도구가 된다
- 면제 목록 파일을 두지 않는다. 계약과 떨어져 살면 어긋나고, 왜 면제인지가 안 남는다
- 유예가 낡으면 그것도 실패다. 안 그러면 표시가 영원히 남는다
- 표와 게이트는 같은 정의를 쓴다. 다르면 같은 칸을 두고 둘이 다른 말을 한다
- 게이트도 뮤테이션을 통과해야 한다. 안 우는 검사는 초록을 보고 안심하는 자리를 하나 더 만든다
- 400 행과 검증 어노테이션은 양방향으로 대조한다. 사람이 쓰는 행은 빠뜨릴 수 있다 — 행에
Violation.of(필드, 제약 타입)을 적어 맞대고, 이 대조는 아직 구현 전이다 - 설정만 바꾸는 계약은 「설정 — 배포 때 확인」으로 표시하고 세지 않는다. 「못 짠 것」(
@Pending)과 「안 짜기로 한 것」은 표시가 다르다 - 실행 끝에 스위트 소요 시간을 한 줄 남긴다. 예산 숫자는 아직 없고, 10분을 넘으면 스프링 기동 횟수와 테스트 수 추세부터 본다
자신만의 철학을 만들어가는 중입니다.
댓글남기기