---
test_env: dev
last_rule_updated_at: 2026-06-12
---

# dev 테스트 규칙

**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
**dev 테스트 환경은 local 테스트 조건을 그대로 따르되, 같은 원격 host에서 local/test stack과 공존하도록 host publish 포트와 compose project/network를 분리한다.**

## 공통 규칙

- dev 테스트/검증은 이 파일을 기준으로 판단한다.
- 작업 완료 검증은 변경 범위 기준으로 선택한다.
- 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
- 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
- 환경값, secret, 개인 endpoint는 tracked docs/roadmap에 쓰지 않는다.
- token/secret 원문은 원격 환경에서 주입하고, shell stdout/stderr와 최종 보고에 출력하지 않는다.
- 테스트용 Docker 환경을 작성/수정할 때는 Docker Compose `networks`, IPAM subnet, static IPv4, `extra_hosts`, host publish 문서 어디에도 `192.168.0.0/24` (`192.168.0.X`) 대역을 사용하지 않는다.
- 새 Docker 테스트 subnet이 필요하면 기존 프로젝트 포트/네트워크 표준을 먼저 따르고, 불가피한 경우 host LAN/VPN과 충돌하지 않는 `192.168.0.0/24` 밖의 private subnet만 사용한다.

## 기본 환경

- host: dev runtime evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop-dev` 기준으로 수행한다.
- repo root: 명령은 원격 checkout `/Users/toki/agent-work/iop-dev` 기준으로 실행한다.
- sync 기준: 원격 runner를 사용하는 경우 local uncommitted 변경은 원격 repo에 자동 반영되지 않는다. 동기화되지 않았으면 현재 변경분 검증으로 보지 않는다.
- env file: dev stack은 `docker compose --env-file .env.dev.example ...`로 명시한다.
- compose identity: `COMPOSE_PROJECT_NAME=iop-dev-agent`, `IOP_COMPOSE_NETWORK=iop-dev-agent-net`.
- port: web/dev preview `13001`, Control Plane HTTP `18001`, Portal/Control Plane wire test endpoint `19001`, CP-Edge wire `19002`, Edge-Node TCP transport `19003`, Postgres host publish `15401`, Redis host publish `16301`.
- optional dev field ports: artifact/bootstrap HTTP `18082`, Edge OpenAI-compatible HTTP `18083`, Edge metrics `19101`. 이 값은 compose 기본 stack에 publish되지 않으며 field/bootstrap 또는 Edge direct dev profile이 필요할 때만 사용한다.
- runtime: Go quick check는 local toolchain을 우선한다. Flutter client 포함 검증과 Docker/code-server/full-cycle runtime은 원격 runner를 사용한다.
- package manager: Go modules / Makefile / Flutter pub
- docker: 현재 작업 컨테이너에서는 Docker-in-Docker를 사용하지 않는다. Docker compose 검증은 원격 runner 또는 code-server 환경에서 수행한다.
- external service: dev compose Control Plane HTTP `http://toki-labs.com:18001`, dev Client wire `ws://toki-labs.com:19001/client`.
- model endpoint: dev Edge OpenAI-compatible profile을 별도로 띄우는 경우 `http://toki-labs.com:18083/v1`.
- credential: token/secret 원문은 문서에 기록하지 않는다.

## 포트 매핑

| 용도 | local/test | dev |
|---|---:|---:|
| Web preview | `13000` | `13001` |
| Control Plane HTTP | `18000` | `18001` |
| CP Client WS | `19080` | `19001` |
| CP-Edge wire | `19081` | `19002` |
| Edge-Node TCP | `19090` | `19003` |
| Edge artifact/bootstrap | `18080` | `18082` |
| Edge OpenAI-compatible | `18081` | `18083` |
| Edge metrics | `19092` | `19101` |
| PostgreSQL host publish | `15400` | `15401` |
| Redis host publish | `16300` | `16301` |

## 라우팅

- node / smoke / node 실행 파이프라인 baseline: `agent-test/dev/node-smoke.md`
- edge / smoke / edge 실행 그룹과 입력 표면 baseline: `agent-test/dev/edge-smoke.md`
- control-plane / smoke / control-plane health와 wire baseline: `agent-test/dev/control-plane-smoke.md`
- client / smoke / Flutter client와 IOP console package baseline: `agent-test/dev/client-smoke.md`
- platform-common / smoke / 공통 설정과 protobuf 계약 baseline: `agent-test/dev/platform-common-smoke.md`
- testing / smoke / 테스트 도구와 full-cycle 검증 baseline: `agent-test/dev/testing-smoke.md`

## 라우팅 규칙

- 여러 항목이 맞으면 모두 읽는다.
- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `<domain>-smoke` 문서를 기본 baseline으로 둔다.
- 도메인이 아직 없을 때만 project-smoke를 fallback baseline으로 둔다.
- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.
