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

domain	last_rule_review_commit	last_rule_updated_at
testing	3b9f37076a	2026-05-27

testing

목적 / 책임

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

포함 경로

• Makefile — 공식 test target과 보조 smoke target을 선언하는 위치이다.
• bin/edge.sh — 사용자가 edge console/server를 실행하는 shell entrypoint이며 bin shell 사용자 흐름 검증의 기준 대상이다.
• bin/node.sh — 사용자가 node를 edge에 연결하는 shell entrypoint이며 bin shell 사용자 흐름 검증의 기준 대상이다.
• bin/web.sh — 사용자가 Web Portal dev server를 실행하는 shell entrypoint이다.
• bin/build/field-binaries.sh — field 배포용 edge/node 바이너리 build entrypoint이다.
• scripts/e2e-smoke.sh — mock/real profile 기반 보조 edge-node smoke 검증이다.
• scripts/e2e-openai-ollama.sh — OpenAI-compatible Ollama 입력 표면 보조 smoke 검증이다.

제외 경로

• apps/node/ — node 실행 구현의 소유자는 node 도메인이다. testing 도메인은 작업 후 검증 기준만 정의한다.
• apps/edge/ — edge 실행 구현의 소유자는 edge 도메인이다. testing 도메인은 작업 후 검증 기준만 정의한다.
• apps/web/ — Web Portal 구현의 소유자는 별도 후보 도메인이다. testing 도메인은 entrypoint와 검증 기준만 정의한다.
• packages/ 및 proto/ — 공통 계약의 소유자는 platform-common 도메인이다. testing 도메인은 해당 변경 후 필요한 검증 기준만 정의한다.

주요 구성 요소

• 대상 패키지 테스트 — 변경한 패키지와 인접한 패키지의 빠른 회귀 검증이다.
• go test ./... — 저장소 전체 Go 테스트 회귀 검증이다.
• bin shell 사용자 흐름 검증 — 사용자가 하듯이 bin/edge.sh와 bin/node.sh를 각각 실행하고, edge console에서 메시지 2회와 command 명령을 직접 보내 결과가 edge 화면에 도착하는지 확인하는 기준 검증이다.
• 보조 E2E smoke — 임시 설정과 mock adapter로 최소 생존을 빠르게 확인하는 보조 검증이다. 이 결과만으로 완료 처리하지 않는다.
• OpenAI-compatible Ollama smoke — scripts/e2e-openai-ollama.sh로 OpenAI HTTP 입력 표면이 edge service와 node adapter 경로로 수렴하는지 확인하는 보조 검증이다.
• Web Portal verify — apps/web 변경 시 npm run verify --prefix apps/web 기준으로 TypeScript check와 production build를 확인한다.
• full-cycle 실제 구동 — 비효율적이어도 관련 사용자 명령과 실행 cycle을 한 번씩 실제 entrypoint로 통과시키는 검증이다.
• 실제 외부 CLI 검증 — claude, antigravity, codex, opencode처럼 외부 CLI 설치와 계정/환경이 필요한 기준 profile을 실제 호출하는 검증이다.
• one-line bootstrap/install UX — Node, OTO, specialized agent, Control Plane enrollment처럼 사용자가 대상 host에서 복사해 실행하는 연결/설치 명령의 사용자 경험 기준이다.

유지할 패턴

• 테스트는 테스트 파일 변경 여부가 아니라 작업 영향 범위로 결정한다.
• 사용자 실행 파이프라인에 닿는 작업을 한 경우, 작업 완료 후 일반 Go 테스트와 bin/edge.sh + bin/node.sh 기반 bin shell 사용자 흐름을 반드시 검증한다. 보조 E2E smoke는 추가로 수행할 수 있지만 완료 기준이 아니다.
• 사용자 실행 파이프라인에는 bin/**, apps/*/cmd/**, apps/*/internal/bootstrap/**, edge-node transport/service/registry/input surface, adapter 실행/stream/cancel/status 경로, configs/**, packages/config/**, packages/hostsetup/**, 관련 protobuf 계약 변경이 포함된다.
• bin shell 사용자 흐름 검증은 bin/edge.sh와 bin/node.sh를 별도 프로세스로 직접 실행하고, edge console prompt에 명령을 한 줄씩 입력한 뒤 기대 출력이 도착한 것을 확인하고 다음 입력으로 넘어간다.
• 메시지 검증 기준은 edge console에서 같은 session으로 메시지 2회를 보내고, 각 요청마다 [edge] sent, [node-*-event] start, 비어 있지 않은 [node-*-message], [node-*-event] complete가 edge 화면에 표시되는 것이다.
• 완료 이벤트만으로 정상 판정하지 않는다. node 로컬 출력에 생성된 [node-message] payload가 edge console의 [node-*-message] 출력에 모두 표시되어야 하며, complete event는 모든 message payload가 edge에 도착한 뒤의 마감 신호로 본다.
• 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의 사용자 명령은 curl -fsSL <완성된-bootstrap-url> | bash -s <token> 형태를 기준으로 한다. 다른 bootstrap/enrollment 작업에서도 같은 수준의 단일 token UX를 우선 적용하고, 예외가 필요하면 사용자에게 먼저 확인한다.
• 상세 수행 절차와 기능별 체크리스트는 agent-ops/skills/project/e2e-smoke/SKILL.md를 따른다.
• make test-e2e, scripts/e2e-smoke.sh, scripts/e2e-openai-ollama.sh는 보조 smoke 명령이다. 실행할 수 있으면 보조 확인으로 기록하되, bin shell 사용자 흐름을 대체하지 않는다.
• bin/build/field-binaries.sh 변경 시 최소 현재 host target build를 실행하고 산출물 위치와 checksum 생성을 확인한다.
• bin/web.sh 또는 apps/web/** 변경 시 npm run verify --prefix apps/web를 실행하고, dev server entrypoint 변경이면 ./bin/web.sh 기동 가능 여부도 확인한다.
• 풀테스트에서는 실제 외부 CLI profile 검증을 필수로 수행한다. 환경, 계정, provider, 원격 endpoint 문제로 호출할 수 없거나 실패한 profile은 누락하지 말고 profile별 실패 또는 blocker로 보고한다.
• 작업 최종 보고에는 실행한 테스트 명령, bin shell 사용자 흐름 수행 여부, 보조 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 변경 후 사용자 실행 흐름을 어떻게 확인할지 정한다.
• platform-common: platform-common은 config/proto 계약을 소유한다. testing은 해당 계약 변경이 edge-node 실행 흐름에 닿을 때 필요한 검증을 정한다.
• web 후보: Web Portal 구현 자체는 testing 도메인이 소유하지 않는다. testing은 web entrypoint와 verify 명령 기준만 다룬다.

금지 사항

• 사용자 실행 파이프라인에 닿는 변경을 하고 유닛/패키지 테스트만으로 완료 처리하지 않는다.
• make test-e2e, scripts/e2e-smoke.sh, scripts/e2e-openai-ollama.sh, 또는 smoke 통과 출력만으로 완료 처리하지 않는다.
• 관련 작업 후 full-cycle 실제 구동을 비용이 크다는 이유만으로 생략하지 않는다.
• 보조 E2E smoke를 외부 CLI 설치, 로그인, 네트워크 계정 상태에 의존하게 만들지 않는다.
• 검증을 위해 기본 configs/*.yaml을 임시값으로 오염시키지 않는다. 임시 설정 파일이나 환경 변수 override를 사용한다.
• 사용자 기본 bootstrap/install 안내에 IOP_ARTIFACT_BASE_URL=..., IOP_EDGE_ADDR=..., IOP_NODE_TOKEN=... 같은 named environment parameter를 요구하지 않는다. 이런 값은 작업자용 디버그/override 경로로만 분리한다.
• 필수 검증을 실행하지 못했는데 조용히 생략하지 않는다.