--- test_env: dev last_rule_updated_at: 2026-07-18 --- # dev 테스트 규칙 **현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.** **dev는 RARA의 기본 테스트 환경이며 local host가 아니라 원격 Mac runner를 기준으로 한다.** ## 공통 규칙 - 사용자가 테스트 환경을 별도로 지정하지 않으면 이 `dev` 환경을 기본 기준으로 삼는다. - local 검증은 원격 프리플라이트와 source 동기화를 대신하지 않는다. - 작업 완료 검증은 변경 범위에 맞는 도메인 profile을 선택한다. - 필수 검증을 실행하지 못하면 차단 사유로 보고한다. - 최종 보고에는 원격 source identity, 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다. - secret, token, password, private key, 개인 endpoint 원문은 tracked 파일이나 shell 출력에 남기지 않는다. - 원격 서비스는 기본적으로 runner loopback에 bind한다. 외부 공개 검증이 명시된 경우에만 별도 접근 경계와 방화벽 상태를 확인한다. ## 기본 환경 - host: `ssh toki@toki-labs.com` 표준 원격 Mac runner - repo root: 목표 checkout `/Users/toki/agent-work/rara-dev` - checkout 상태: 2026-07-18 점검 시 아직 없음. 최초 원격 검증 전 생성이 필요하다. - sync 기준: 검증할 exact source commit을 origin에서 fetch한 뒤 clean checkout하고, local 변경과 원격 HEAD가 동일한지 확인한다. - runtime: macOS arm64. 2026-07-18 login shell에서 Go 1.26.3과 Python 3.12.9(`python3.12`)를 확인했다. - package manager: Go modules, Python venv/pip - docker: login shell의 Docker Desktop/Engine 27.4.0을 사용한다. 일반 비대화형 SSH PATH에는 Go와 Docker가 없으므로 원격 명령은 login shell 또는 검증된 explicit PATH로 실행한다. - external service: readiness·통합 smoke에는 PostgreSQL이 필요하며, 준비되지 않으면 source test/build까지만 수행하고 통합 검증은 차단으로 보고한다. - model endpoint: 기본값 없음. adaptation/model 통합 검증 시 별도 승인된 endpoint가 필요하다. - credential: secret/token/API key 원문은 문서에 기록하지 않는다. ## 포트 매핑 2026-07-18 기준 workspace 원장에 기존 `70` 슬롯 배정이 없고, 원격 runner의 아래 후보 포트가 listen 중이 아님을 확인한 뒤 RARA `dev` 전용으로 배정했다. 실행 직전 동일 검사를 반복한다. | 용도 | local 호환값 | dev 원격값 | bind 기준 | |---|---:|---:|---| | Control Plane HTTP | `18080` | `18070` | `127.0.0.1:18070` | | RAG API HTTP | `18081` | `18071` | `127.0.0.1:18071` | | Go Worker HTTP | `18082` | `18072` | `127.0.0.1:18072` | | Python Executor gRPC | `19090` | `19070` | `127.0.0.1:19070` | | PostgreSQL host publish | `5432` | `15470` | `127.0.0.1:15470 -> 5432` | | Frontend reserve | 해당 없음 | `13070` reserved | 현재 RARA runtime에 없음 | | Cache reserve | 해당 없음 | `16370` reserved | 현재 RARA runtime에 없음 | | Metrics / diagnostics reserve | 해당 없음 | `19170-19172` reserved | 현재 RARA runtime에 없음 | - `18080-18099`와 `19080/19090`은 IOP shared field/runtime baseline이므로 RARA 원격 dev 서비스에 재사용하지 않는다. - repo의 `configs/*.yaml` 기본 listen 값은 local 호환값이다. 원격 dev에서는 `RARA_LISTEN`과 `RARA_PYTHON_LISTEN_PORT`로 위 dev 값을 명시한다. - PostgreSQL host publish가 필요하지 않으면 `15470`을 열지 않고 service와 DB를 전용 network 또는 loopback으로만 연결한다. ## 런타임 프로필 - source validation: 원격 checkout에서 `make test && make build`를 기본 완료 검증으로 사용한다. - service smoke: PostgreSQL이 준비된 경우 Control Plane `18070`, RAG API `18071`, Go Worker `18072`를 각각 dev override로 실행하고 health/readiness를 확인한다. - Python executor smoke: `RARA_PYTHON_LISTEN_HOST=127.0.0.1`과 `RARA_PYTHON_LISTEN_PORT=19070`을 사용한다. - compose candidate: 향후 remote compose를 추가할 경우 `COMPOSE_PROJECT_NAME=rara-dev-agent`, network `rara-dev-agent-net`, subnet `10.89.7.0/24`, PostgreSQL host publish `15470`을 기준으로 한다. 2026-07-18 기존 remote Docker network와 subnet이 겹치지 않음을 확인했지만, 현재 compose에는 dev override와 network 정의가 없으므로 실제 구성으로 간주하지 않는다. - artifact: runner-local filesystem artifact root를 사용하며 공개 artifact HTTP 포트는 없다. ## 프리플라이트 - 원격 검증 전 runner 접속, `/Users/toki/agent-work/rara-dev` 존재 여부, branch, HEAD, dirty 상태, local 변경과 source 동기화 여부를 확인한다. - login shell에서 `go version`, `python3.12 --version`, `docker version`, 필요한 tool/version, `.venv`의 Python identity를 확인한다. 기본 `python3`은 2026-07-18 기준 3.14.6이므로 Python 3.12 venv라고 추정하지 않는다. - `13070`, `18070-18072`, `15470`, `16370`, `19070`, `19170-19172`가 다른 process에 점유되지 않았는지 확인한다. 미사용 후보까지 함께 확인해 `70` 슬롯의 부분 재사용을 방지한다. - service smoke 전 config path, `RARA_LISTEN`, `RARA_DATABASE_URL`, artifact root, process identity를 확인한다. - Docker daemon과 PostgreSQL container가 실제로 준비되지 않았으면 설치 상태만으로 통합 검증 가능하다고 추정하지 않고 integration blocker로 보고한다. - checkout 부재, source 불일치, stale binary, port 점유, runtime version 불일치는 setup/sync/rebuild 후 해소하거나 차단 사유로 보고한다. ## 노드/서비스 인벤토리 위치 - machine-readable runner·port 기준: `agent-test/dev/inventory.yaml` - Control Plane 기준: `agent-test/dev/control-plane-smoke.md` - RAG API 기준: `agent-test/dev/rag-data-plane-smoke.md` - Go/Python worker 기준: `agent-test/dev/workflow-execution-smoke.md` - 공통 config·database·artifact·배포 기준: `agent-test/dev/platform-common-smoke.md` ## 반복 테스트 기준 - 원격 evidence는 current source와 동일한 remote checkout에서만 수집한다. - source test/build와 PostgreSQL 의존 service smoke를 구분해 보고한다. - 여러 RARA 서비스를 동시에 실행할 때 각 프로세스에 다른 `RARA_LISTEN`을 명시한다. - test 종료 후 장기 runtime으로 승인되지 않은 프로세스는 정리하고, 포트가 반환됐는지 확인한다. - secret이 포함될 수 있는 database URL과 외부 endpoint는 값 대신 주입 여부만 보고한다. ## 라우팅 - control-plane / smoke / 수명주기 API와 제어 상태 원격 검증: `agent-test/dev/control-plane-smoke.md` - rag-data-plane / smoke / retrieve·answer 계약 원격 검증: `agent-test/dev/rag-data-plane-smoke.md` - workflow-execution / smoke / Go worker와 Python executor 원격 검증: `agent-test/dev/workflow-execution-smoke.md` - platform-common / smoke / config·database·artifact·배포 원격 검증: `agent-test/dev/platform-common-smoke.md` ## 라우팅 규칙 - 여러 항목이 맞으면 모두 읽는다. - 도메인 매핑이나 domain rule이 있으면 각 도메인의 `-smoke`를 baseline으로 둔다. - 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.