iop/agent-ops/rules/project/domain/testing/rules.md

domain	last_rule_review_commit	last_rule_updated_at
testing	7ca329ac9e	2026-07-14

testing

목적 / 책임

작업 완료 후 어떤 테스트와 full-cycle 실제 구동 검증을 거쳐야 하는지 정리한다. 테스트 파일을 바꿨는지가 아니라, 변경 작업이 어떤 사용자 실행 파이프라인에 닿았는지를 기준으로 검증 범위를 정한다. 대상 host에서 사용자가 복사해 실행하는 bootstrap/install command의 기본 UX 기준도 이 도메인에서 다룬다.

포함 경로

• Makefile — 공식 test target, proto generation, 보조 smoke target을 선언하는 위치이다.
• scripts/dev/edge.sh — repo 내부 edge console/server 개발 진단 helper이다.
• scripts/dev/node.sh — repo 내부 node 연결 개발 진단 helper이다. field 사용자 기본 경로로 안내하지 않는다.
• scripts/dev/web.sh — repo 내부 Flutter Web client 개발 진단 helper이다. field 배포 기본 경로로 안내하지 않는다.
• scripts/e2e-smoke.sh — mock/real profile 기반 보조 edge-node smoke 검증이다.
• scripts/e2e-openai-cli-workspace.sh — OpenAI-compatible /v1/responses CLI workspace isolation 보조 smoke 검증이다.
• scripts/e2e-openai-ollama.sh — OpenAI-compatible Ollama 입력 표면 보조 smoke 검증이다.
• scripts/e2e-openai-vllm.sh — OpenAI-compatible vLLM/SGLang류 provider 입력 표면 보조 smoke 검증이다.
• scripts/e2e-openai-lemonade.sh — OpenAI-compatible Lemonade/provider API 입력 표면 보조 smoke 검증이다.
• scripts/e2e-long-context-admission-smoke.sh — live provider pool long-context admission/capacity 보조 smoke 검증이다.
• scripts/e2e-control-plane-edge-wire.sh — Control Plane-Edge wire hello/disconnect 보조 smoke 검증이다.
• scripts/fixtures/ — E2E smoke 입력 fixture 위치이다.
• docker-compose.yml — local dev용 Control Plane, datastore, Flutter Web client stack 조립 표면이다.

제외 경로

• apps/node/ — node 실행 구현의 소유자는 node 도메인이다. testing 도메인은 작업 후 검증 기준만 정의한다.
• apps/edge/ — edge 실행 구현의 소유자는 edge 도메인이다. testing 도메인은 작업 후 검증 기준만 정의한다.
• apps/control-plane/ — Control Plane 구현의 소유자는 control-plane 도메인이다. testing 도메인은 작업 후 검증 기준만 정의한다.
• apps/client/ — Flutter client 구현과 client test 파일의 소유자는 client 도메인이다. testing 도메인은 작업 후 검증 기준만 정의한다.
• packages/go/ 및 proto/ — 공통 계약의 소유자는 platform-common 도메인이다. testing 도메인은 해당 변경 후 필요한 검증 기준만 정의한다.

주요 구성 요소

• 대상 패키지 테스트 — 변경한 패키지와 인접한 패키지의 빠른 회귀 검증이다.
• go test ./... — 저장소 전체 Go 테스트 회귀 검증이다.
• flutter test / make client-test — Flutter client 단위/widget/wire 테스트 검증이다.
• make client-build-web — Flutter Web build와 --dart-define 설정 주입 검증이다.
• edge-node 개발 진단 흐름 검증 — scripts/dev/edge.sh와 scripts/dev/node.sh를 각각 실행하고, edge console에서 메시지 2회와 command 명령을 직접 보내 결과가 edge 화면에 도착하는지 확인하는 저수준 검증이다. field 사용자 기본 UX는 Edge가 제시한 bootstrap 명령이다.
• client 개발 진단 흐름 검증 — scripts/dev/web.sh로 Flutter Web dev server를 띄우고 Control Plane HTTP/WS URL 주입과 /client wire 연결 상태를 확인하는 저수준 검증이다.
• 보조 E2E smoke — 임시 설정과 mock adapter로 최소 생존을 빠르게 확인하는 보조 검증이다. 이 결과만으로 완료 처리하지 않는다.
• OpenAI-compatible Ollama smoke — scripts/e2e-openai-ollama.sh로 OpenAI HTTP 입력 표면이 edge service와 node adapter 경로로 수렴하는지 확인하는 보조 검증이다.
• OpenAI-compatible CLI workspace smoke — scripts/e2e-openai-cli-workspace.sh로 metadata.workspace가 CLI 실행 작업 디렉터리로만 쓰이고 repo root/temp parent로 파일이 새지 않는지 확인하는 보조 검증이다.
• OpenAI-compatible provider smoke — scripts/e2e-openai-vllm.sh와 scripts/e2e-openai-lemonade.sh로 provider API route, request body, expected output을 확인하는 live-dependency 보조 검증이다.
• Long-context admission smoke — scripts/e2e-long-context-admission-smoke.sh로 provider pool capacity, queue, long-context slot, Control Plane status snapshot 회복을 live dev provider pool에서 확인하는 보조 검증이다.
• Control Plane-Edge wire smoke — scripts/e2e-control-plane-edge-wire.sh로 실제 Control Plane/Edge 프로세스의 Edge hello, 연결 성공, disconnect marker를 확인하는 보조 검증이다.
• compose local dev stack 검증 — docker-compose.yml 변경 시 Control Plane, datastore, Flutter Web service의 build/env/healthcheck wiring을 확인하는 검증이다.
• full-cycle 실제 구동 — 비효율적이어도 관련 사용자 명령과 실행 cycle을 한 번씩 실제 entrypoint로 통과시키는 검증이다.
• 실제 외부 CLI 검증 — claude, antigravity, codex, opencode처럼 외부 CLI 설치와 계정/환경이 필요한 기준 profile을 실제 호출하는 검증이다.
• one-line bootstrap/install UX — Node, specialized agent, domain agent, Control Plane enrollment처럼 사용자가 대상 host에서 복사해 실행하는 연결/설치 명령의 사용자 경험 기준이다.

유지할 패턴

• 테스트는 테스트 파일 변경 여부가 아니라 작업 영향 범위로 결정한다.
• 사용자 실행 파이프라인에 닿는 작업을 한 경우, 작업 완료 후 일반 Go 테스트와 변경 범위에 맞는 full-cycle 실제 구동을 검증한다. repo 내부 edge-node 진단에는 scripts/dev/edge.sh + scripts/dev/node.sh를 사용할 수 있지만, field 사용자 기본 UX는 bootstrap 명령으로 확인한다.
• 사용자 실행 파이프라인에는 scripts/dev/**, scripts/e2e-*.sh, Makefile, docker-compose.yml, apps/*/cmd/**, apps/*/internal/bootstrap/**, edge-node transport/service/registry/input surface, Control Plane wire endpoint, client wire surface, adapter 실행/stream/cancel/status 경로, configs/**, packages/go/config/**, packages/go/hostsetup/**, 관련 protobuf 계약 변경이 포함된다.
• edge-node 개발 진단 흐름 검증은 scripts/dev/edge.sh와 scripts/dev/node.sh를 별도 프로세스로 직접 실행하고, edge console prompt에 명령을 한 줄씩 입력한 뒤 기대 출력이 도착한 것을 확인하고 다음 입력으로 넘어간다.
• 메시지 검증 기준은 edge console에서 같은 session으로 메시지 2회를 보내고, 각 요청마다 [edge] sent, [node-*-event] start, 기대 payload를 포함한 비어 있지 않은 [node-*-message], 같은 run의 [node-*-event] complete가 edge 화면에 표시되는 것이다.
• 완료 이벤트만으로 정상 판정하지 않는다. [edge] sent나 [edge-message]에 보이는 사용자 입력 echo는 응답 relay 증거가 아니며, node 로컬 출력에 생성된 같은 run의 [node-message] payload 라인 목록이 edge console의 [node-*-message] 라인 목록과 내용/순서까지 동일해야 한다. complete event는 동일성 확인 대상인 모든 message payload가 edge에 표시된 뒤의 마감 신호이며, 답변이 끝나기 전에 complete가 먼저 표시되거나 complete 뒤에 같은 run의 message가 추가로 표시되면 실패다.
• command 검증 기준은 edge console에서 /nodes와 변경 범위에 닿는 command를 직접 입력하고, node에서 온 결과가 edge 화면에 [node-*-<command>] 또는 명확한 성공/unsupported/error 출력으로 표시되는 것이다. CLI 경로 변경 시 최소 /capabilities, /transport, /sessions, persistent profile이면 /terminate-session을 확인한다.
• 보조 E2E smoke는 mock adapter와 임시 설정/포트를 사용해 외부 CLI 의존성 없이 수행한다.
• 보조 E2E smoke에서는 최소한 node 등록, /nodes 확인, console 메시지 전송, delta/message 출력, complete event를 확인한다.
• full-cycle 실제 구동에서는 startup/register, foreground run, session 변경, background run, terminate-session, status, 관련 routing/cancel/timeout/persistent session cycle을 실제 entrypoint로 한 번씩 통과시킨다.
• one-line bootstrap/install command는 Jenkins agent 연결처럼 간결해야 한다. 사용자에게 전달하는 명령은 artifact/bootstrap URL이 완성된 한 줄이어야 하며, 사용자가 직접 바꾸는 값은 token 같은 단일 positional 값만 둔다.
• one-line bootstrap/install command의 Edge 주소, artifact 주소, target, platform, config path 같은 값은 작업자/Edge/Control Plane이 미리 굽거나 완성해서 제공한다. 사용자 기본 경로에서 IOP_*= 같은 named environment parameter나 여러 주소 조합을 직접 입력하게 하지 않는다.
• field Node bootstrap의 사용자 명령은 대상 OS에 맞는 완성된 bootstrap URL과 실제 token 값을 포함한 한 줄 명령을 기준으로 한다. Linux/macOS는 curl -fsSL ... | bash -s ..., Windows native는 PowerShell .ps1 bootstrap과 Start-IopNode를 기준으로 한다. 다른 bootstrap/enrollment 작업에서도 같은 수준의 단일 token UX를 우선 적용하고, 예외가 필요하면 사용자에게 먼저 확인한다.
• 사용자에게 실행 방법을 알려줄 때는 placeholder 형식을 쓰지 않는다. token 원문을 현재 채널에 적기 어렵다면 placeholder 명령을 주지 말고, 안전한 secret 전달 절차를 먼저 끝낸 뒤 실제 값이 들어간 완성 명령만 제공한다.
• field bootstrap 안내에서 token을 숨기겠다는 이유로 ssh ... awk ..., command substitution, 여러 환경 변수 선언, inline config 생성, 수동 binary download를 한 줄에 합치지 않는다.
• 추가 설정이 필요한 경우 기본 bootstrap 명령 뒤에 “선택 옵션”으로 분리한다. 기본 성공 경로는 사용자가 값 치환 없이 실행하면 동작해야 하며, 환경 변수나 config 편집은 고급/디버그 override로만 검증한다.
• repo 내부 edge-node 진단의 상세 수행 절차와 기능별 체크리스트는 agent-ops/skills/project/e2e-smoke/SKILL.md를 따른다.
• make test-e2e, scripts/e2e-smoke.sh, scripts/e2e-openai-ollama.sh, scripts/e2e-control-plane-edge-wire.sh는 보조 smoke 명령이다. 실행할 수 있으면 보조 확인으로 기록하되, full-cycle 실제 구동이나 field bootstrap 검증을 대체하지 않는다.
• Client-Control Plane wire나 client UI를 바꾸면 make client-test를 기본 검증으로 기록한다. Web build/deploy 경로를 바꾸면 make client-build-web, scripts/dev/web.sh, compose build 중 변경 범위에 맞는 경로를 추가 확인한다.
• Control Plane-Edge wire나 Edge outbound connector를 바꾸면 대상 Go 테스트와 함께 make test-control-plane-edge-wire를 보조 검증으로 기록한다. status snapshot, node event relay, HTTP /edges 조회를 바꾼 경우 해당 동작을 별도로 확인한다.
• OpenAI-compatible route, /v1/responses, CLI workspace handoff, provider tunnel, provider auth, tool validation, usage metering을 바꾸면 대상 Go 테스트와 함께 관련 OpenAI smoke(test-openai-ollama, scripts/e2e-openai-cli-workspace.sh, scripts/e2e-openai-vllm.sh, scripts/e2e-openai-lemonade.sh) 중 변경 범위에 맞는 것을 보조 검증으로 기록한다.
• provider pool, model catalog, queue admission, long-context capacity, Control Plane provider snapshot을 바꾸면 scripts/e2e-long-context-admission-smoke.sh --preflight와 필요한 --scenario를 live 환경 가용성에 따라 실행하고, 실행 불가/실패는 profile별 blocker로 보고한다.
• iop-edge bootstrap pack, make pack-edge, 내장 artifact server 변경 시 최소 현재 host target build를 실행하고 archive 압축 해제, artifact 폴더 위치, checksum 생성, node bootstrap script가 positional token UX를 유지하는지 확인한다.
• 풀테스트에서는 실제 외부 CLI profile 검증을 필수로 수행한다. 환경, 계정, provider, 원격 endpoint 문제로 호출할 수 없거나 실패한 profile은 누락하지 말고 profile별 실패 또는 blocker로 보고한다.
• 작업 최종 보고에는 실행한 테스트 명령, repo 내부 edge-node 진단 수행 여부, 보조 E2E smoke 수행 여부, full-cycle 실제 구동 수행 여부를 명시한다. 수행하지 못한 필수 검증은 이유와 남은 위험을 함께 적는다.

기준 출력 예시

아래처럼 edge console에서 입력한 메시지 2회와 command 결과가 edge 화면에 도착해야 기준을 통과한 것으로 본다. run id와 node alias는 실행 환경에 따라 달라질 수 있다.

edge> /nodes
  test-node (test-node)

edge> Convert token iop_manual_one and reply only with converted token
[edge] sent run_id=manual-... node=test-node adapter=cli target=fake-cli session=default background=false
[node-test-node-event] start run_id=manual-...
[node-test-node-message] IOP_MANUAL_ONE_OK
[node-test-node-message] IOP_MANUAL_ONE_TAIL
[node-test-node-event] complete run_id=manual-... detail="idle-timeout"

edge> Convert token iop_manual_two and reply only with converted token
[edge] sent run_id=manual-... node=test-node adapter=cli target=fake-cli session=default background=false
[node-test-node-event] start run_id=manual-...
[node-test-node-message] IOP_MANUAL_TWO_OK
[node-test-node-message] IOP_MANUAL_TWO_TAIL
[node-test-node-event] complete run_id=manual-... detail="idle-timeout"

edge> /capabilities
[node-test-node-capabilities] target=fake-cli session=default
  adapter = cli
  max_concurrency = 4
  targets = fake-cli

edge> /transport
[node-test-node-transport] target=fake-cli session=default
  adapter = cli
  connected = true
  node_id = test-node
  session_id = default
  target = fake-cli

edge> /sessions
[node-test-node-sessions] target=fake-cli session=default
  count = 1
  sessions = persistent:fake-cli/default

edge> /terminate-session
terminated session default node=test-node

다른 도메인과의 경계

• node: node는 adapter 실행과 edge 연결 구현을 소유한다. testing은 node 변경 후 어떤 검증을 거칠지 정한다.
• edge: edge는 registry, service, transport, console, HTTP/A2A input surface 구현을 소유한다. testing은 edge 변경 후 사용자 실행 흐름을 어떻게 확인할지 정한다.
• control-plane: control-plane은 server endpoint, Edge wire registry, Client WS boundary 구현을 소유한다. testing은 해당 변경 후 어떤 smoke와 실제 구동 검증을 거칠지 정한다.
• client: client는 Flutter UI와 Dart wire wrapper 구현을 소유한다. testing은 client 변경 후 어떤 Flutter test/build/dev-server 검증을 거칠지 정한다.
• platform-common: platform-common은 config/proto 계약을 소유한다. testing은 해당 계약 변경이 edge-node 실행 흐름에 닿을 때 필요한 검증을 정한다.

금지 사항

• 사용자 실행 파이프라인에 닿는 변경을 하고 유닛/패키지 테스트만으로 완료 처리하지 않는다.
• make test-e2e, scripts/e2e-smoke.sh, scripts/e2e-openai-ollama.sh, scripts/e2e-control-plane-edge-wire.sh, 또는 smoke 통과 출력만으로 완료 처리하지 않는다.
• 관련 작업 후 full-cycle 실제 구동을 비용이 크다는 이유만으로 생략하지 않는다.
• 보조 E2E smoke를 외부 CLI 설치, 로그인, 네트워크 계정 상태에 의존하게 만들지 않는다.
• live-dependency smoke(e2e-openai-vllm, e2e-openai-lemonade, e2e-long-context-admission-smoke)가 필요한 작업에서 endpoint/account/token 문제를 성공으로 간주하지 않는다. 실행 불가는 명확한 blocker 또는 남은 위험으로 보고한다.
• 검증을 위해 기본 configs/*.yaml을 임시값으로 오염시키지 않는다. 임시 설정 파일이나 환경 변수 override를 사용한다.
• smoke script가 bearer token, provider token, API key를 stdout/stderr, evidence output, tracked fixture에 기록하지 않게 한다.
• 사용자 기본 bootstrap/install 안내에 IOP_ARTIFACT_BASE_URL=..., IOP_EDGE_ADDR=..., IOP_NODE_TOKEN=... 같은 named environment parameter를 요구하지 않는다. 이런 값은 작업자용 디버그/override 경로로만 분리한다.
• 사용자 기본 bootstrap/install 안내에 원격 token 조회, shell quoting이 복잡한 wrapper, 수동 node.yaml 생성, 수동 iop-node serve --config ... 실행을 섞지 않는다.
• 사용자 기본 bootstrap/install 안내에 angle-bracket placeholder, YOUR_TOKEN, REPLACE_ME 같은 치환용 값을 넣지 않는다. 실제 값을 제공할 수 없으면 실행 명령을 제시하지 않고 필요한 값의 안전 전달이 먼저 필요하다고 보고한다.
• 필수 검증을 실행하지 못했는데 조용히 생략하지 않는다.