docs(ledger): 흔들린 시험을 장부에 남기고 시간·순서 단언 규칙을 리뷰 기준에 건다 #40
@@ -24,3 +24,4 @@ gradlew.bat text eol=crlf
|
||||
|
||||
# Ledger lines are only appended; a union merge keeps both branches' new lines (docs/ledger/README.md).
|
||||
docs/ledger/estimates.jsonl merge=union
|
||||
docs/ledger/flaky-tests.jsonl merge=union
|
||||
|
||||
+10
-2
@@ -1,4 +1,13 @@
|
||||
# 예측·실측 장부
|
||||
# 장부
|
||||
|
||||
이 폴더에는 줄을 더하기만 하는 JSON Lines 장부가 둘 있다.
|
||||
|
||||
- `estimates.jsonl`: 작업의 예측·실측(아래 절).
|
||||
- `flaky-tests.jsonl`: 흔들린 시험. 흔들림 하나가 한 줄이다. 칸(`date`·`test`·`category`·`first_run`·`verdict`·`quarantined_until`·`fixed_by`)과 범주의 정본은 design-docs `ci/manual.md` 8.5절이고, 판정·처리 절차는 그 문서 8.3절이다. 고친 PR이 병합되면 그 줄의 `fixed_by`를 채운다.
|
||||
|
||||
두 파일 모두 `.gitattributes`가 `merge=union`을 준다. 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않는다.
|
||||
|
||||
## 예측·실측 장부
|
||||
|
||||
작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)를 고칠 곳을 찾는 것이 목적이다. 질타가 아니라 측정이다(소유자 결정 2026-11-07).
|
||||
|
||||
@@ -9,7 +18,6 @@
|
||||
```
|
||||
|
||||
- 파일은 `docs/ledger/estimates.jsonl` 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 `task`로 `"correction": true` 줄을 더한다.
|
||||
- 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 `.gitattributes`가 이 파일에 `merge=union`을 준다.
|
||||
- p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다.
|
||||
- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(바꿀 파일 수, 검증 대기)가 있을 때만 쓴다.
|
||||
- 위임 대조용 장부(design-docs `delegation-loop/ledger.jsonl`)는 그대로 둔다. 그 줄의 예측·실측 칸은 이 파일의 `task`를 가리킨다.
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
{"date": "2026-11-12", "test": "compose smoke local-messaging (scripts/run-compose-runtime-smoke.sh)", "category": "concurrency-order", "first_run": "100", "verdict": "runner nightly 구성 1회 실패: 앱이 기반 서비스가 healthy가 되기 전에 떴다. 고친 뒤 desktop matrix 18/18 통과", "quarantined_until": "", "fixed_by": "백엔드 #13"}
|
||||
{"date": "2026-11-13", "test": "GrpcP1BoundaryWireTest#aSlowCallWithoutAClientDeadlineEndsAtTheServerDefaultDeadline", "category": "fixed-time", "first_run": "221", "verdict": "runner main push 4회 중 1회 실패(152·164·183 통과). desktop 1코어 고정 15회, CPU 부하 아래 24회 통과", "quarantined_until": "", "fixed_by": "백엔드 #34"}
|
||||
{"date": "2026-11-13", "test": "FailureInjectionContractTest#aSlowDripThroughToxiproxyEndsAtTheTotalDeadline[JDK]", "category": "fixed-time", "first_run": "228", "verdict": "runner 1회 실패(1.92초, 상한 1.5초). desktop 부하 6.5~8에서 10회 통과(호출 1,010~1,021ms)", "quarantined_until": "", "fixed_by": "백엔드 #34"}
|
||||
{"date": "2026-11-13", "test": "LiveEventLogContractTest#concurrentWritersAllocateDistinctPositions", "category": "concurrency-order", "first_run": "260", "verdict": "replay 순서를 writer 제출 순서로 단언했다. 둘째 writer를 먼저 돌린 탐침에서 재현. 고침 PR 백엔드 #39(열림)", "quarantined_until": "", "fixed_by": ""}
|
||||
{"date": "2026-11-13", "test": "JettyAttemptDeadlineTest#aSlowDripExchangeIsAbortedAtTheAttemptDeadline", "category": "fixed-time", "first_run": "desktop ~/w2-reloc-logs/w2-reloc-a.log (main c7a18ec7, prCheck, 시작 부하 11~15)", "verdict": "desktop 1회 실패(1.68초, 상한 1.5초). PR 단계 test라 runner PR run에서도 날 수 있다", "quarantined_until": "", "fixed_by": ""}
|
||||
@@ -149,7 +149,7 @@ for k in tests skipped failures errors; do cat $(find "$x" -name 'TEST-*.xml') |
|
||||
|
||||
**smoke 이미지가 이 트리에서 만들어졌음을 보이기.** smoke·compose lane은 Docker 레이어 캐시를 쓴다. 이미지 생성 시각은 runtime 레이어가 캐시에서 오면 증거가 못 된다. 앱 jar를 복사하는 단계가 smoke 로그의 build 출력에서 `CACHED`가 아닌지 본다. 앱 jar가 이 트리에서 새로 만들어졌으면 그 단계는 캐시가 될 수 없다. 결과 표 「실제 실행」 칸에 그 줄과 이미지 id를 적는다.
|
||||
|
||||
**원래 있던 실패 가리기.** 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 `--tests <클래스> --rerun`으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 `nproc`개의 `yes > /dev/null &`를 띄웠다가 끝나면 끈다. 실패한 반복 수를 적는다.
|
||||
**원래 있던 실패 가리기.** 시간·자원에 기대는 실패(OOM, 시간 초과, 순서 의존)는 기준 커밋과 이번 트리에서 같은 명령을 각각 세 번 돌린다. 기준에서 한 번이라도 같은 원인(같은 테스트, 로그의 같은 OOM·시간 초과)으로 실패하면 이전부터의 실패로 적는다. 기준에서 세 번 다 통과하고 이번 트리에서만 실패하면 이번 변경 몫이다. 순서 의존을 재현하려면 그 테스트 클래스를 `--tests <클래스> --rerun`으로 열 번 돌리고, 부하가 필요하면 잠금을 쥔 채 `nproc`개의 `yes > /dev/null &`를 띄웠다가 끝나면 끈다. 실패한 반복 수와 각 반복을 시작할 때의 부하(`uptime`)를 적는다. runner에서 실패했으면 그 job이 돈 시각에 desktop에서 잠금 아래 돈 실행도 적는다(runner는 잠금 밖이다). 흔들림으로 판정하면 `docs/ledger/flaky-tests.jsonl`에 한 줄을 더하고, 상한을 늘리거나 재시도를 붙이지 않고 design-docs `ci/manual.md` 8.4절대로 고친다.
|
||||
|
||||
**공유 잠금 기다리기.** 순서는 `flock`이 정한다(먼저 잡은 쪽). 따로 순번을 정하지 않는다. 기다리는 명령은 background로 두고 다른 일을 하며, 대기는 완료나 첫 실패에서 끝나는 것 하나로 둔다. 30분 넘게 못 잡으면 `ps -o pid,etime,args -C flock`으로 쥔 쪽을 보고 맡긴 쪽에 알린다([operate.md](../operate.md) 7절).
|
||||
|
||||
|
||||
@@ -159,7 +159,7 @@
|
||||
| 규칙 테스트가 위반·허용 fixture를 둘 다 가지나 | 위반 fixture만 있어 거짓 양성을 못 봄 |
|
||||
| `// when`이 하나인가 | 두 동작을 한 테스트가 봄 |
|
||||
| 테스트 코드도 정적 분석을 통과하나 | 게이트 밖에서 실패한 채 방치 |
|
||||
| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언 |
|
||||
| 타이밍에 기대지 않나 | 부하가 높으면 실패하는 "스레드 없음" 단언, PR·main 단계 시험의 벽시계 상한(「1.5초 안에」) 단언, 스레드 시작 순서를 결과 순서로 보는 단언. 시계 주입·조건 대기·결과 단언으로 쓴다(design-docs `ci/manual.md` 8.4절) |
|
||||
|
||||
fake와 공유 계약: 포트마다 hand-rolled fake 하나를 포트 소유 leaf의 `testFixtures`에 두고, fake와 실제 adapter가 같은 추상 계약(`XxxContract`)을 상속한다. 계약 밖 fake, 소비자 없는 fake, 계약과 겹친 adapter 손 사본 테스트는 만들지 않는다. fake 동작을 바꾸면 계약 케이스를 같이 바꾼다. 포트를 더하거나 계약을 옮기면 `docs/testing/TESTING_STRATEGY.md`의 현황표를 고친다.
|
||||
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
"""docs/ledger/estimates.jsonl의 줄이 docs/ledger/README.md 형식인지 본다.
|
||||
"""docs/ledger/의 장부 두 파일이 정해진 형식인지 본다(estimates.jsonl은 docs/ledger/README.md,
|
||||
flaky-tests.jsonl은 design-docs ci/manual.md 8.5절).
|
||||
|
||||
python3 -m unittest discover -s scripts/tests
|
||||
"""
|
||||
@@ -7,7 +8,7 @@ from __future__ import annotations
|
||||
|
||||
import json
|
||||
import unittest
|
||||
from datetime import datetime
|
||||
from datetime import date, datetime
|
||||
from pathlib import Path
|
||||
|
||||
REPO = Path(__file__).resolve().parent.parent.parent
|
||||
@@ -15,6 +16,9 @@ LEDGER = REPO / "docs/ledger/estimates.jsonl"
|
||||
KINDS = {"estimate", "actual", "retro"}
|
||||
COMMON = ("schema", "kind", "task", "recorded_at")
|
||||
RANGES = ("minutes", "calls", "output_tokens")
|
||||
FLAKY = REPO / "docs/ledger/flaky-tests.jsonl"
|
||||
FLAKY_FIELDS = {"date", "test", "category", "first_run", "verdict", "quarantined_until", "fixed_by"}
|
||||
FLAKY_CATEGORIES = {"fixed-time", "concurrency-order", "resource-io", "test-order", "external"}
|
||||
|
||||
|
||||
def lines() -> list[dict]:
|
||||
@@ -49,5 +53,19 @@ class LedgerTest(unittest.TestCase):
|
||||
self.assertEqual(entry["within"], expected, entry["task"])
|
||||
|
||||
|
||||
class FlakyLedgerTest(unittest.TestCase):
|
||||
def test_every_flaky_line_has_exactly_the_manual_fields_and_a_known_category(self) -> None:
|
||||
for number, line in enumerate(FLAKY.read_text(encoding="utf-8").splitlines(), start=1):
|
||||
if not line.strip():
|
||||
continue
|
||||
entry = json.loads(line)
|
||||
self.assertEqual(entry.keys(), FLAKY_FIELDS, f"line {number}")
|
||||
self.assertIn(entry["category"], FLAKY_CATEGORIES, f"line {number}")
|
||||
date.fromisoformat(entry["date"])
|
||||
if entry["quarantined_until"]:
|
||||
date.fromisoformat(entry["quarantined_until"])
|
||||
self.assertTrue(entry["test"].strip() and entry["verdict"].strip(), f"line {number}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
Reference in New Issue
Block a user