test(setup): 자식 프로세스 시험 timeout을 잰 값으로 정하고 흔들리던 시험 둘을 고친다 #22

Merged
donghyeon.kang merged 4 commits from fix/child-process-test-timeouts into main 2026-11-12 04:13:12 +00:00
Owner

무엇을, 왜

부하가 높은 desktop에서 시험이 가끔 떨어진다. 총괄 지시로 두 가지를 고치고, 검증 중 찾은 하나를 더 고친다.

  • 자식 프로세스 시험 timeout. tests/unit/documentation-readiness.test.ts가 FE-GATE-020 drill 사본에서 기본 timeout 10초를 넘겼다. 평소 0.4~1.2초인 시험이 10.6초 걸렸다. 같은 모양의 시험을 repo 전체에서 찾았다. 그 결과 자식 프로세스를 띄우면서 기본 10초에 기대는 Vitest 시험이 91개(24파일) 나왔다. 가장 위험한 tests/architecture/app-build-input.test.ts는 평소에도 5.7초까지 걸렸다. 문서 시험 자체에는 PR #15가 이미 60초를 줬다.
  • guardian lease. tests/integration/provider-guardian-transaction.test.ts에서 guardian이 lease 만료로 스스로 SIGKILL한다. FE-GATE-007·020에서 났고 FE-B 실행에서는 load 28에 2건 났다. 다시 돌리면 통과한다.
  • artifacts 복사 경합. 이 PR의 첫 최종 실행에서 FE-GATE-007이 실패했다. tests/integration/security-followup-archive.test.ts가 artifacts/를 복사하는 동안, 다른 시험이 쓰던 임시 파일이 rename되어 ENOENT가 났다.

고른 방법과 버린 대안

커밋 넷이다. 커밋마다 desktop에서 test:unit·check:types·check:ci·lint·verify:documentation을 돌렸다(아래 검증).

  1. 91962e24 자식 프로세스 시험이 잰 시간으로 timeout을 정한다.
    • 무엇을 고칠지는 계측으로 정했다.
      • desktop에서 test:coverage 묶음(maxWorkers=4)과 test:unit을 세 번씩 돌렸다.
      • 시험마다 띄운 자식 프로세스는 child_process 함수를 감싸 기록했고, 소요 시간은 JSON reporter로 받았다.
      • 실제 timeout은 task.timeout으로 받았다.
      • 자식 프로세스를 띄우는 시험 140개 중 88개가 기본값이었다.
      • tests/system은 아래 검사가 잡은 셋을 따로 세 번 쟀다.
    • tests/helpers/child-process-timeout.ts의 childProcessTimeout(<잰 최대 ms>)가 timeout을 정한다.
      • 잰 최대의 15배를 30초 단위로 올린 값이다.
      • 15배는 위 문서 시험의 0.7초 → 10.6초에서 왔다.
      • 시험마다 자기가 잰 값을 인자로 적어서, 근거가 호출 자리에 남는다.
    • describe 안의 기본값 시험이 모두 자식 프로세스를 띄우면 describe에, 일부만 띄우면 그 시험에 준다. 프로세스 안에서 도는 시험의 hang을 늦게 잡지 않으려는 것이다.
    • tests/setup.ts가 child_process 함수를 감싼다.
      • 기본 timeout인 시험이 자식 프로세스를 띄우면 그 호출에서 실패시키고, helper 이름을 알린다.
      • 시험이 import한 helper나 스크립트가 띄워도 잡는다.
      • util.promisify가 읽는 속성은 원래 함수에서 옮긴다.
      • 이 검사의 시험은 tests/unit/child-process-timeout.test.ts다.
    • docs/work/reference/testing.md 2절에 값 정하는 법과 이 검사를 적었다.
    • 버린 것:
      • 전역 testTimeout 올리기: 프로세스 안 시험의 hang을 늦게 잡는다.
      • 시험마다 손으로 정한 숫자: 근거가 남지 않는다. 이미 있던 60_000·120_000에도 근거가 없었다.
      • 자식 프로세스 없이 검사하게 바꾸기: 검사 스크립트를 CLI 그대로 시험하는 것이 이 시험들의 목적이라 범위가 커진다.
      • 파일에 timeout 선언이 있는지만 보는 정적 검사: helper가 띄우는 경우와, 같은 파일의 다른 시험을 놓친다.
  2. 77c01b03 guardian 시험의 lease가 시험 대상이 아니면 시험 timeout만큼 준다.
    • 원인은 두 가지다.
      • startProviderGuardian은 guardian을 띄우자마자 절대 deadline을 찍는다. 그래서 client 경로 시험의 2~3초 lease가 node 시작 시간까지 낸다.
      • 직접 프로토콜 시험은 guardian이 load를 마친 뒤 가드를 보낸다(c8620042). 그래도 가드 → READY 처리는 실제 시계로 돈다. desktop CPU 25% 제한에서 이 구간이 17ms에서 334ms로 늘었다. 350ms lease로 만료를 보는 시험은 여유가 거의 없다.
    • lease가 시험 대상이 아닌 15곳(client 경로 10, 직접 경로 5)은 LEASE_NOT_UNDER_TEST_MS다.
      • 값은 시험 timeout과 같다.
      • 그래서 lease가 시험보다 먼저 끝날 수 없고, guardian이 멈추면 시험 timeout이 잡는다.
    • lease를 보는 두 시험은 잰 값으로 정했다.
      • 만료 시험은 350ms → 2초다. 가드 → READY의 CPU 25% 최대 334ms의 여섯 배다.
      • near-deadline 시험은 직접 프로토콜로 옮겨 node 시작 시간이 lease에서 빠진다.
      • sendGuard가 보낸 deadline을 돌려준다.
      • near-deadline 시험은 lease 4초의 마지막 2초 안에 publish·commit을 보내고, 그 구간에 있었는지 단언한다.
      • 2초는 publish·commit의 CPU 25% 최대 104ms의 약 스무 배다.
      • client의 publish·commit은 「owns raw and sealed publication」이 그대로 본다.
    • 버린 것:
      • guardian에 가짜 시계 주입: 운영 스크립트에 시험용 훅을 넣어야 한다.
      • client가 guardian load 뒤에 deadline을 찍게 바꾸기: 운영 프로토콜에 준비 신호를 더해야 한다.
      • 모든 lease를 늘리기: 만료와 near-deadline 시험은 lease가 대상이다.
  3. db4c632d archive 시험이 다른 시험이 쓰는 중인 임시 파일을 복사하지 않는다.
    • 같은 integration 실행에서 tests/integration/http-scenario-catalog.test.ts가 artifacts/tests/http-scenario-executions.json을 임시 파일에 쓰고 rename한다.
    • 복사 filter가 원자적 쓰기의 임시 파일(.<이름>.<무작위>.tmp)을 건너뛴다. fs.cp는 filter를 stat보다 먼저 부르므로, 건너뛴 파일은 사라져도 오류가 없다.
    • 버린 것: 필요한 증거 경로만 복사하기(공급망 생성이 artifacts의 .gitkeep까지 추적 파일을 모두 lstat하고 build가 읽는 증거가 여러 곳이라 목록을 따로 관리해야 한다), 두 시험을 직렬로 돌리기(integration 층 전체가 느려진다).
  4. a593feb2 CHANGELOG 정리 단계 절: 범위, 먼저 할 일 17, 옮긴 뒤 확인 1, 계약 표 한 줄, 그 밖의 수정 두 줄.

위험과 영향

  • 다운스트림: 자기 Vitest 시험이 기본 timeout으로 자식 프로세스를 띄우면 test:unit 등이 실패한다. 메시지가 helper를 알린다(CHANGELOG 먼저 할 일 17).
  • 검사가 보지 않는 곳:
    • hook(beforeAll 등)에서 띄우는 프로세스는 보지 않는다. 계측에서 hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다.
    • Playwright spec은 tests/setup.ts를 쓰지 않는다.
    • 같은 파일 안에서 it.concurrent로 도는 시험이 섞이면 어느 시험의 timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다.
  • guardian 시험이 실패하면 guardian이 lease 끝까지(최대 30초) 남을 수 있다. 전에는 2~3초였다.
  • near-deadline 시험에는 실제 시계 구간이 남는다. publish·commit이 2초를 넘으면 실패한다.
  • 운영 client가 lease에 node 시작 시간을 포함하는 것은 그대로다. 운영 lease는 분 단위다.
  • archive 시험: 임시 파일이 아닌 파일을 다른 시험이 지우는 경합은 남는다. 지금 artifacts/ 아래에서 그렇게 하는 시험은 찾지 못했다.
  • 시험 파일 24개를 건드려 W2-FE 브랜치와 겹칠 수 있다. W2-FE에 D를 여기서 고쳤다고 알렸다.

검증

모두 desktop에서 돌렸다. workflow env(CI=true, 40자리 VITE_COMMIT_SHA, VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE digest)를 썼고, job마다 깨끗한 트리에서 설치를 한 번 하고 게이트를 차례로 corepack pnpm ci:gate <ID>로 돌렸다. 로그는 desktop /tmp/claude-gates/ 아래에 있다. 계측은 fea-m1·fea-m2·fea-m3·fea-gp, 재현은 fea-t2·fea-gg·fea-gg2·fea-ar2, 최종은 fea-f3이다.

판정(docs/work/reference/gates.md 3절): merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약(user namespace)이라 판정에서 뺌(뒤 명령 결과 첨부, 모두 rc=0). FE-GATE-005·020은 깨끗한 트리에서 3회 연속 통과했다.

커밋별(fea-f3, 2026-11-12 11:49~11:55)

다섯 검사(test:unit, check:types, check:ci, lint, verify:documentation)가 네 커밋 모두 rc=0이다.

커밋 test:unit check:types check:ci lint verify:documentation
91962e24 0 (47s) 0 0 0 0
77c01b03 0 (65s) 0 0 0 0
db4c632d 0 (48s) 0 0 0 0
a593feb2 0 (71s) 0 0 0 0

게이트 — 끝 커밋 a593feb2(fea-f3, 11:5512:57, load 526)

job 게이트 결과
merge_static 001 · 002 · 003 · 010 · 011 · 012 모두 0 (4s · 24s · 15s · 67s · 12s · 7s)
merge_test 004 · 006 · 007 모두 0 (2s · 13s · 30s)
merge_test 013 1 (2s). 사전 점검이 user namespace 제한 하나만 댄다. 뒤 명령은 아래
merge_test, 1회 005 · 020 0 (162s) · 0 (902s)
깨끗한 트리 2회 005 · 020 0 (145s) · 0 (1,034s)
깨끗한 트리 3회 005 · 020 0 (171s) · 0 (1,009s)
main_gate 029 0 (34s)
— 017 0 (2s)
  • FE-GATE-005: 세 번 모두 test:unit 3,166개, coverage 4,102개 통과.
  • FE-GATE-020: 세 번 모두 제거 drill 다섯이 실패 0(browser-file-storage 7, feature-scaffold 38, optional-recipe 6, realtime 7, sample-removal 목록 비어 SKIP).
  • FE-GATE-013 뒤 명령: verify:reproducible-build·build:release-candidate·verify:local-evidence·check:browser-security 모두 0. tests/system은 115개 중 18개 실패, 97개 통과다. 실패는 모두 candidate archive and provider upload boundaries(bwrap)이고, 새 검사 위반은 0이다.
  • FE-GATE-008·009(Playwright)는 돌리지 않았다. 이 PR은 Playwright가 쓰는 파일을 바꾸지 않는다.

결정적 재현

무엇 조건 고치기 전 고친 뒤
1번 timeout CPU 10% 제한, app-build-input·registry-governance·hosting-probe·design-system-rules main 650d22fa: 11개 「Test timed out in 10000ms」 71개 통과, 가장 긴 시험 17.7초
2번 guardian CPU 20% 제한, guardian 파일 5회 main d2239c67: 5회 모두 1~6개 실패(가드 처리 중 deadline 지남 126, READY·PUBLISHED 대기 초과, EPIPE) 5회 모두 22개 통과
3번 archive 옆 프로세스가 artifacts/tests에 임시 파일 10개를 계속 만들고 rename main 6b4f703c: 3회 중 2회 FE-GATE-007과 같은 ENOENT(.tmp) 3회 모두 통과

guardian 파일은 고친 뒤 평소 상태로 30회(load 3.6~21), CPU 20% 제한으로 5회 더 돌려 모두 통과했다.

검사의 검출력(변이)

  • tests/setup.ts의 검사를 끄면 tests/unit/child-process-timeout.test.ts가 실패한다.
  • tests/unit/tracked-artifacts.test.ts describe의 timeout을 지우면 그 시험이 검사 메시지로 실패한다.
  • tests/system을 처음 돌렸을 때 검사가 기본 timeout으로 자식 프로세스를 띄우던 시험 셋(ci-evidence-freshness 둘, provider-process-group 하나)을 잡았다. 따로 세 번 재서 timeout을 줬다.

처음 최종 실행에서 고친 것

  • near-deadline 시험의 「마지막 2초 안」 단언이 남은 2,001ms로 실패했다(FE-GATE-007). 타이머가 Date.now()보다 1ms 일찍 깼다. 목표 시각에 닿을 때까지 다시 기다리게 고쳐 2번 커밋에 합쳤다.
  • 다음 실행에서 FE-GATE-007이 archive 시험의 ENOENT로 실패했다. 3번 커밋이다.

리뷰어가 볼 곳

  • tests/setup.ts의 검사와 tests/helpers/child-process-timeout.ts, tests/unit/child-process-timeout.test.ts.
  • tests/integration/provider-guardian-transaction.test.ts: lease 상수 셋, sendGuard의 반환값, near-deadline 시험.
  • tests/integration/security-followup-archive.test.ts의 복사 filter.
  • 나머지 시험 파일은 timeout 인자만 더했다. 인자의 ms는 desktop에서 잰 그 시험의 최대다.

관련

  • 총괄 지시(2026-11-12), PR #18(이 문제가 처음 보인 곳), PR #15(문서 시험의 60초)
  • .claude/rules/tests.md 9, docs/work/reference/testing.md 2·5절
## 무엇을, 왜 부하가 높은 desktop에서 시험이 가끔 떨어진다. 총괄 지시로 두 가지를 고치고, 검증 중 찾은 하나를 더 고친다. - **자식 프로세스 시험 timeout.** `tests/unit/documentation-readiness.test.ts`가 FE-GATE-020 drill 사본에서 기본 timeout 10초를 넘겼다. 평소 0.4~1.2초인 시험이 10.6초 걸렸다. 같은 모양의 시험을 repo 전체에서 찾았다. 그 결과 자식 프로세스를 띄우면서 기본 10초에 기대는 Vitest 시험이 91개(24파일) 나왔다. 가장 위험한 `tests/architecture/app-build-input.test.ts`는 평소에도 5.7초까지 걸렸다. 문서 시험 자체에는 PR #15가 이미 60초를 줬다. - **guardian lease.** `tests/integration/provider-guardian-transaction.test.ts`에서 guardian이 lease 만료로 스스로 SIGKILL한다. FE-GATE-007·020에서 났고 FE-B 실행에서는 load 28에 2건 났다. 다시 돌리면 통과한다. - **artifacts 복사 경합.** 이 PR의 첫 최종 실행에서 FE-GATE-007이 실패했다. `tests/integration/security-followup-archive.test.ts`가 `artifacts/`를 복사하는 동안, 다른 시험이 쓰던 임시 파일이 rename되어 ENOENT가 났다. ## 고른 방법과 버린 대안 커밋 넷이다. 커밋마다 desktop에서 test:unit·check:types·check:ci·lint·verify:documentation을 돌렸다(아래 검증). 1. `91962e24` 자식 프로세스 시험이 잰 시간으로 timeout을 정한다. - 무엇을 고칠지는 계측으로 정했다. - desktop에서 test:coverage 묶음(maxWorkers=4)과 test:unit을 세 번씩 돌렸다. - 시험마다 띄운 자식 프로세스는 `child_process` 함수를 감싸 기록했고, 소요 시간은 JSON reporter로 받았다. - 실제 timeout은 `task.timeout`으로 받았다. - 자식 프로세스를 띄우는 시험 140개 중 88개가 기본값이었다. - tests/system은 아래 검사가 잡은 셋을 따로 세 번 쟀다. - `tests/helpers/child-process-timeout.ts`의 `childProcessTimeout(<잰 최대 ms>)`가 timeout을 정한다. - 잰 최대의 15배를 30초 단위로 올린 값이다. - 15배는 위 문서 시험의 0.7초 → 10.6초에서 왔다. - 시험마다 자기가 잰 값을 인자로 적어서, 근거가 호출 자리에 남는다. - describe 안의 기본값 시험이 모두 자식 프로세스를 띄우면 describe에, 일부만 띄우면 그 시험에 준다. 프로세스 안에서 도는 시험의 hang을 늦게 잡지 않으려는 것이다. - `tests/setup.ts`가 `child_process` 함수를 감싼다. - 기본 timeout인 시험이 자식 프로세스를 띄우면 그 호출에서 실패시키고, helper 이름을 알린다. - 시험이 import한 helper나 스크립트가 띄워도 잡는다. - `util.promisify`가 읽는 속성은 원래 함수에서 옮긴다. - 이 검사의 시험은 `tests/unit/child-process-timeout.test.ts`다. - `docs/work/reference/testing.md` 2절에 값 정하는 법과 이 검사를 적었다. - 버린 것: - 전역 testTimeout 올리기: 프로세스 안 시험의 hang을 늦게 잡는다. - 시험마다 손으로 정한 숫자: 근거가 남지 않는다. 이미 있던 60_000·120_000에도 근거가 없었다. - 자식 프로세스 없이 검사하게 바꾸기: 검사 스크립트를 CLI 그대로 시험하는 것이 이 시험들의 목적이라 범위가 커진다. - 파일에 timeout 선언이 있는지만 보는 정적 검사: helper가 띄우는 경우와, 같은 파일의 다른 시험을 놓친다. 2. `77c01b03` guardian 시험의 lease가 시험 대상이 아니면 시험 timeout만큼 준다. - 원인은 두 가지다. - `startProviderGuardian`은 guardian을 띄우자마자 절대 deadline을 찍는다. 그래서 client 경로 시험의 2~3초 lease가 node 시작 시간까지 낸다. - 직접 프로토콜 시험은 guardian이 load를 마친 뒤 가드를 보낸다(c8620042). 그래도 가드 → READY 처리는 실제 시계로 돈다. desktop CPU 25% 제한에서 이 구간이 17ms에서 334ms로 늘었다. 350ms lease로 만료를 보는 시험은 여유가 거의 없다. - lease가 시험 대상이 아닌 15곳(client 경로 10, 직접 경로 5)은 `LEASE_NOT_UNDER_TEST_MS`다. - 값은 시험 timeout과 같다. - 그래서 lease가 시험보다 먼저 끝날 수 없고, guardian이 멈추면 시험 timeout이 잡는다. - lease를 보는 두 시험은 잰 값으로 정했다. - 만료 시험은 350ms → 2초다. 가드 → READY의 CPU 25% 최대 334ms의 여섯 배다. - near-deadline 시험은 직접 프로토콜로 옮겨 node 시작 시간이 lease에서 빠진다. - `sendGuard`가 보낸 deadline을 돌려준다. - near-deadline 시험은 lease 4초의 마지막 2초 안에 publish·commit을 보내고, 그 구간에 있었는지 단언한다. - 2초는 publish·commit의 CPU 25% 최대 104ms의 약 스무 배다. - client의 publish·commit은 「owns raw and sealed publication」이 그대로 본다. - 버린 것: - guardian에 가짜 시계 주입: 운영 스크립트에 시험용 훅을 넣어야 한다. - client가 guardian load 뒤에 deadline을 찍게 바꾸기: 운영 프로토콜에 준비 신호를 더해야 한다. - 모든 lease를 늘리기: 만료와 near-deadline 시험은 lease가 대상이다. 3. `db4c632d` archive 시험이 다른 시험이 쓰는 중인 임시 파일을 복사하지 않는다. - 같은 integration 실행에서 `tests/integration/http-scenario-catalog.test.ts`가 `artifacts/tests/http-scenario-executions.json`을 임시 파일에 쓰고 rename한다. - 복사 filter가 원자적 쓰기의 임시 파일(`.<이름>.<무작위>.tmp`)을 건너뛴다. `fs.cp`는 filter를 stat보다 먼저 부르므로, 건너뛴 파일은 사라져도 오류가 없다. - 버린 것: 필요한 증거 경로만 복사하기(공급망 생성이 artifacts의 `.gitkeep`까지 추적 파일을 모두 lstat하고 build가 읽는 증거가 여러 곳이라 목록을 따로 관리해야 한다), 두 시험을 직렬로 돌리기(integration 층 전체가 느려진다). 4. `a593feb2` CHANGELOG 정리 단계 절: 범위, 먼저 할 일 17, 옮긴 뒤 확인 1, 계약 표 한 줄, 그 밖의 수정 두 줄. ## 위험과 영향 - 다운스트림: 자기 Vitest 시험이 기본 timeout으로 자식 프로세스를 띄우면 test:unit 등이 실패한다. 메시지가 helper를 알린다(CHANGELOG 먼저 할 일 17). - 검사가 보지 않는 곳: - hook(`beforeAll` 등)에서 띄우는 프로세스는 보지 않는다. 계측에서 hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다. - Playwright spec은 `tests/setup.ts`를 쓰지 않는다. - 같은 파일 안에서 `it.concurrent`로 도는 시험이 섞이면 어느 시험의 timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다. - guardian 시험이 실패하면 guardian이 lease 끝까지(최대 30초) 남을 수 있다. 전에는 2~3초였다. - near-deadline 시험에는 실제 시계 구간이 남는다. publish·commit이 2초를 넘으면 실패한다. - 운영 client가 lease에 node 시작 시간을 포함하는 것은 그대로다. 운영 lease는 분 단위다. - archive 시험: 임시 파일이 아닌 파일을 다른 시험이 지우는 경합은 남는다. 지금 `artifacts/` 아래에서 그렇게 하는 시험은 찾지 못했다. - 시험 파일 24개를 건드려 W2-FE 브랜치와 겹칠 수 있다. W2-FE에 D를 여기서 고쳤다고 알렸다. ## 검증 모두 desktop에서 돌렸다. workflow env(`CI=true`, 40자리 `VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest)를 썼고, job마다 깨끗한 트리에서 설치를 한 번 하고 게이트를 차례로 `corepack pnpm ci:gate <ID>`로 돌렸다. 로그는 desktop `/tmp/claude-gates/` 아래에 있다. 계측은 `fea-m1`·`fea-m2`·`fea-m3`·`fea-gp`, 재현은 `fea-t2`·`fea-gg`·`fea-gg2`·`fea-ar2`, 최종은 `fea-f3`이다. **판정**(`docs/work/reference/gates.md` 3절): merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약(user namespace)이라 판정에서 뺌(뒤 명령 결과 첨부, 모두 rc=0). FE-GATE-005·020은 깨끗한 트리에서 3회 연속 통과했다. ### 커밋별(fea-f3, 2026-11-12 11:49~11:55) 다섯 검사(test:unit, check:types, check:ci, lint, verify:documentation)가 네 커밋 모두 rc=0이다. | 커밋 | test:unit | check:types | check:ci | lint | verify:documentation | |---|---|---|---|---|---| | `91962e24` | 0 (47s) | 0 | 0 | 0 | 0 | | `77c01b03` | 0 (65s) | 0 | 0 | 0 | 0 | | `db4c632d` | 0 (48s) | 0 | 0 | 0 | 0 | | `a593feb2` | 0 (71s) | 0 | 0 | 0 | 0 | ### 게이트 — 끝 커밋 `a593feb2`(fea-f3, 11:55~12:57, load 5~26) | job | 게이트 | 결과 | |---|---|---| | merge_static | 001 · 002 · 003 · 010 · 011 · 012 | 모두 0 (4s · 24s · 15s · 67s · 12s · 7s) | | merge_test | 004 · 006 · 007 | 모두 0 (2s · 13s · 30s) | | merge_test | 013 | 1 (2s). 사전 점검이 user namespace 제한 하나만 댄다. 뒤 명령은 아래 | | merge_test, 1회 | 005 · 020 | 0 (162s) · 0 (902s) | | 깨끗한 트리 2회 | 005 · 020 | 0 (145s) · 0 (1,034s) | | 깨끗한 트리 3회 | 005 · 020 | 0 (171s) · 0 (1,009s) | | main_gate | 029 | 0 (34s) | | — | 017 | 0 (2s) | - FE-GATE-005: 세 번 모두 test:unit 3,166개, coverage 4,102개 통과. - FE-GATE-020: 세 번 모두 제거 drill 다섯이 실패 0(browser-file-storage 7, feature-scaffold 38, optional-recipe 6, realtime 7, sample-removal 목록 비어 SKIP). - FE-GATE-013 뒤 명령: `verify:reproducible-build`·`build:release-candidate`·`verify:local-evidence`·`check:browser-security` 모두 0. tests/system은 115개 중 18개 실패, 97개 통과다. 실패는 모두 `candidate archive and provider upload boundaries`(bwrap)이고, 새 검사 위반은 0이다. - FE-GATE-008·009(Playwright)는 돌리지 않았다. 이 PR은 Playwright가 쓰는 파일을 바꾸지 않는다. ### 결정적 재현 | 무엇 | 조건 | 고치기 전 | 고친 뒤 | |---|---|---|---| | 1번 timeout | CPU 10% 제한, app-build-input·registry-governance·hosting-probe·design-system-rules | main `650d22fa`: 11개 「Test timed out in 10000ms」 | 71개 통과, 가장 긴 시험 17.7초 | | 2번 guardian | CPU 20% 제한, guardian 파일 5회 | main `d2239c67`: 5회 모두 1~6개 실패(가드 처리 중 deadline 지남 126, READY·PUBLISHED 대기 초과, EPIPE) | 5회 모두 22개 통과 | | 3번 archive | 옆 프로세스가 `artifacts/tests`에 임시 파일 10개를 계속 만들고 rename | main `6b4f703c`: 3회 중 2회 FE-GATE-007과 같은 ENOENT(.tmp) | 3회 모두 통과 | guardian 파일은 고친 뒤 평소 상태로 30회(load 3.6~21), CPU 20% 제한으로 5회 더 돌려 모두 통과했다. ### 검사의 검출력(변이) - `tests/setup.ts`의 검사를 끄면 `tests/unit/child-process-timeout.test.ts`가 실패한다. - `tests/unit/tracked-artifacts.test.ts` describe의 timeout을 지우면 그 시험이 검사 메시지로 실패한다. - tests/system을 처음 돌렸을 때 검사가 기본 timeout으로 자식 프로세스를 띄우던 시험 셋(`ci-evidence-freshness` 둘, `provider-process-group` 하나)을 잡았다. 따로 세 번 재서 timeout을 줬다. ### 처음 최종 실행에서 고친 것 - near-deadline 시험의 「마지막 2초 안」 단언이 남은 2,001ms로 실패했다(FE-GATE-007). 타이머가 `Date.now()`보다 1ms 일찍 깼다. 목표 시각에 닿을 때까지 다시 기다리게 고쳐 2번 커밋에 합쳤다. - 다음 실행에서 FE-GATE-007이 archive 시험의 ENOENT로 실패했다. 3번 커밋이다. ## 리뷰어가 볼 곳 - `tests/setup.ts`의 검사와 `tests/helpers/child-process-timeout.ts`, `tests/unit/child-process-timeout.test.ts`. - `tests/integration/provider-guardian-transaction.test.ts`: lease 상수 셋, `sendGuard`의 반환값, near-deadline 시험. - `tests/integration/security-followup-archive.test.ts`의 복사 filter. - 나머지 시험 파일은 timeout 인자만 더했다. 인자의 ms는 desktop에서 잰 그 시험의 최대다. ## 관련 - 총괄 지시(2026-11-12), PR #18(이 문제가 처음 보인 곳), PR #15(문서 시험의 60초) - `.claude/rules/tests.md` 9, `docs/work/reference/testing.md` 2·5절
donghyeon.kang added 4 commits 2026-11-12 04:00:31 +00:00
자식 프로세스를 띄우는 Vitest 시험 91개(24파일)가 기본 timeout 10초에
기대고 있었다. 셋은 FE-GATE-013에서만 도는 tests/system 시험이다.
기본값은 프로세스 안에서 도는 시험에 맞춘 값이다. 부하가 높은
desktop에서는 자식 프로세스 시험이 평소보다 크게 느려진다.
FE-GATE-020 drill 사본에서 평소 0.4~1.2초인 문서 시험이 10.6초 걸려
실패했다(2026-11-12). 가장 위험한 것은 tests/architecture/app-build-input
.test.ts로, desktop에서 이미 5.7초까지 걸렸다.

무엇을 고칠지는 desktop 계측으로 정했다.
- test:coverage 묶음(maxWorkers=4)과 test:unit을 세 번씩 돌렸다. 시험마다
  띄운 자식 프로세스는 child_process 함수를 감싸 기록했고, 소요 시간은
  JSON reporter로 받았다.
- 시험마다 실제 timeout은 task.timeout으로 기록했다.
- 자식 프로세스를 띄우는 시험 140개 중 88개가 기본값이었다. tests/system은
  그 묶음에 없어서, 아래 검사가 잡은 셋을 따로 세 번 쟀다.

고친 것:
- tests/helpers/child-process-timeout.ts의 childProcessTimeout(<잰 최대
  ms>)는 그 15배를 30초 단위로 올린 값이다. 15배는 위 0.7초 → 10.6초에서
  왔다. 시험마다 자기가 잰 최대값을 인자로 적어 근거가 호출 자리에 남는다.
- describe 안의 기본값 시험이 모두 자식 프로세스를 띄우면 describe에,
  일부만 띄우면 그 시험에 준다. 프로세스 안에서 도는 시험의 hang을 늦게
  잡지 않으려는 것이다.
- tests/setup.ts가 child_process 함수를 감싼다. 기본 timeout인 시험이
  자식 프로세스를 띄우면 그 호출에서 실패시키고, helper 이름을 알린다.
  helper나 시험이 import한 스크립트가 띄워도 잡는다. util.promisify가
  읽는 속성은 원래 함수에서 옮긴다.
- docs/work/reference/testing.md 2절에 값 정하는 법과 이 검사를 적었다.

버린 것:
- 전역 testTimeout 올리기: 프로세스 안 시험의 hang을 늦게 잡는다.
- 시험마다 손으로 정한 숫자: 근거가 남지 않고, 이미 있는 값도
  60_000·120_000처럼 근거가 없었다.
- 자식 프로세스를 띄우지 않게 바꾸기: 검사 스크립트를 CLI 그대로 시험하는
  것이 이 시험들의 목적이라 범위가 커진다.
- 파일에 timeout 선언이 있는지만 보는 정적 검사: helper가 띄우는 경우와
  같은 파일의 다른 시험을 놓친다.

위험:
- hook(beforeAll 등)에서 띄우는 프로세스는 검사하지 않는다. 계측에서
  hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다.
- 같은 파일 안에서 it.concurrent로 도는 시험이 섞이면 어느 시험의
  timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다.
- 다운스트림 시험이 기본값으로 자식 프로세스를 띄우면 test:unit 등이
  실패한다. 메시지가 helper를 알린다.

검증(desktop):
- 다섯 검사(test:unit·check:types·check:ci·lint·verify:documentation)
  rc=0.
- 자식 프로세스를 띄우는 시험 파일 40개와 tests/scale: rc=0, 검사 위반 0.
- tests/system: 115개 중 18개 실패. 모두 bwrap 호스트 제약이고 검사
  위반은 0이다.
- 변이: 검사를 끄면 tests/unit/child-process-timeout.test.ts가 실패한다.
  tracked-artifacts describe의 timeout을 지우면 그 시험이 검사 메시지로
  실패한다.
- 재현: CPU 10% 제한에서 app-build-input·registry-governance·hosting-probe
  ·design-system-rules를 돌렸다. main 650d22fa는 11개가 10초 timeout으로
  실패했다. 이 커밋은 71개 모두 통과했고, 가장 긴 시험은 17.7초였다.
tests/integration/provider-guardian-transaction.test.ts가 부하 때 lease
만료로 실패한다. guardian이 스스로 SIGKILL한 것이다. desktop 기록 둘:
- FE-GATE-007: 「still publishes near the lease deadline」
- FE-GATE-020 drill: 「owns raw and sealed publication through the
  authenticated client lease」
FE-B 실행에서도 load 28에 같은 실패가 2건 났다. 다시 돌리면 통과한다.

원인은 두 가지다.
- startProviderGuardian은 guardian을 띄우자마자 절대 deadline
  (Date.now() + leaseMs)을 찍는다. 그래서 client 경로 시험의 2~3초
  lease가 node 시작 시간까지 낸다. 부하 때 시작에는 상한이 없다.
- 직접 프로토콜 시험은 guardian이 load를 마친 뒤 가드를 보낸다
  (c8620042). 그래도 가드 → READY 처리는 실제 시계로 돈다. desktop에서
  CPU 25%로 제한하면 이 구간이 17ms에서 334ms로 늘어나, 350ms lease로
  만료를 보는 시험의 여유가 거의 없다.

lease가 시험 대상인지로 나눠 고쳤다.
- lease가 대상이 아닌 15곳(client 경로 10, 직접 경로 5)은
  LEASE_NOT_UNDER_TEST_MS다. 값은 시험 timeout과 같아서, lease가 시험보다
  먼저 끝날 수 없다. guardian이 멈추면 시험 timeout이 잡는다.
- lease 만료를 보는 시험은 350ms → 2초다. 가드 → READY의 CPU 25% 최대
  334ms의 여섯 배다.
- near-deadline 시험은 client 경로에서 직접 프로토콜로 옮겼다.
  - deadline이 guardian load 뒤에 시작해서 시작 시간이 빠진다.
  - sendGuard가 보낸 deadline을 돌려준다.
  - 시험은 lease 4초의 마지막 2초 안에 publish·commit을 보내고, 그
    구간에 있었는지 단언한다.
  - 2초는 publish·commit의 CPU 25% 최대 104ms의 약 스무 배다.
  - client의 publish·commit은 「owns raw and sealed publication」이 그대로
    본다.

버린 것:
- guardian에 가짜 시계 주입: 운영 스크립트에 시험용 훅을 넣어야 한다
  (c8620042와 같은 이유).
- client가 guardian load 뒤에 deadline을 찍게 바꾸기: 운영 프로토콜에
  준비 신호를 더해야 한다. 이 PR 범위를 넘는다.
- 모든 lease를 늘리기: 만료와 near-deadline 시험은 lease가 대상이라
  늘리면 보는 것이 흐려진다.

위험:
- 시험이 실패하면 guardian이 lease 끝까지(최대 30초) 남을 수 있다.
  전에는 2~3초였다.
- near-deadline 시험에는 실제 시계 구간이 남는다. publish·commit이 2초를
  넘으면 실패한다. 잰 최대의 약 스무 배다.
- 운영 client가 lease에 node 시작 시간을 포함하는 것은 그대로다. 운영
  lease는 분 단위라 시험만큼 빠듯하지 않다.

검증(desktop):
- 이 파일을 10회 돌려 22개 모두 통과했다(load 3~4).
- CPU 20% 제한에서 main d2239c67은 5회 모두 1~6개 실패했다. 원인은 가드
  처리 중 deadline 지남(126), READY·PUBLISHED 대기 시간 초과, EPIPE였다.
  같은 조건에서 이 커밋은 5회 모두 통과했다.
- 시험 timeout은 잰 최대로 고쳤다. near-deadline 3.2초, 만료 2.1초.
- 첫 최종 실행에서 FE-GATE-007이 near-deadline 시험의 「마지막 2초 안」
  단언으로 실패했다(남은 2,001ms). 타이머가 Date.now()보다 1ms 일찍 깼다.
  목표 시각에 닿을 때까지 다시 기다리게 고쳤다. 고친 뒤 이
  파일을 30회(load 3.6~21), CPU 20% 제한으로 5회 돌려 모두 통과했다.
tests/integration/security-followup-archive.test.ts는 후보 빌드에 쓸
증거를 얻으려고 checkout의 artifacts/를 통째로 사본에 복사한다. 같은
integration 실행에서 tests/integration/http-scenario-catalog.test.ts가
artifacts/tests/http-scenario-executions.json을 임시 파일에 쓰고
rename한다. 복사가 목록을 읽은 뒤 그 임시 파일이 rename되면 ENOENT로
실패한다. desktop FE-GATE-007(2026-11-12, load 9)에서 났다.

복사 filter가 원자적 쓰기의 임시 파일(.<이름>.<무작위>.tmp)을 건너뛴다.
그런 파일은 쓰는 중이라 증거가 아니다. fs.cp는 filter를 stat보다 먼저
부르므로, 건너뛴 파일은 사라져도 오류가 없다.

버린 것:
- 필요한 증거 경로만 복사: 공급망 생성이 추적 파일(artifacts의 .gitkeep
  포함)을 모두 lstat하고 build가 읽는 증거가 여러 곳이라, 목록을 따로
  관리해야 한다.
- 두 시험을 같이 돌지 않게 하기: integration 층 전체를 직렬로 돌려야 한다.

위험: 임시 파일이 아닌 파일을 다른 시험이 지우는 경합은 남는다. 지금
artifacts/ 아래에서 그렇게 하는 시험은 찾지 못했다.

검증(desktop):
- 다른 프로세스가 artifacts/tests에 임시 파일 10개를 계속 만들고
  rename하는 동안 이 시험을 돌렸다. main 6b4f703c는 3회 중 2회가 같은
  ENOENT(.tmp)로 실패했고, 이 커밋은 3회 모두 통과했다.
- test:unit, check:types, check:ci, lint, verify:documentation.
docs(changelog): 자식 프로세스 시험 timeout과 흔들리던 시험 둘의 고침을 적는다
frontend-quality-gates / merge / static checks (pull_request) Successful in 2m37s
frontend-quality-gates / merge / tests (pull_request) Failing after 13m15s
frontend-quality-gates / merge / browser tests (pull_request) Failing after 7m3s
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
a593feb252
정리 단계 절에 이 브랜치의 범위를 넣었다. 먼저 할 일 17을 더했다:
기본 timeout인 Vitest 시험이 자식 프로세스를 띄우면 실패하니,
다운스트림은 자기 시험에 childProcessTimeout(<잰 ms>)을 준다. 옮긴 뒤
확인 1에는 test:integration과 17단계를 더했다. 계약 표 한 줄과, 그 밖의
수정에 guardian lease 고침과 archive 시험의 임시 파일 경합 고침을
한 줄씩 적었다.

검증(desktop): verify:documentation, test:unit.
donghyeon.kang merged commit 5250ff950e into main 2026-11-12 04:13:12 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/clean-architecture-frontend-template#22