---
test_env: local
last_rule_updated_at: 2026-07-01
---

# local 테스트 규칙

**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
**기본 local 테스트 환경은 standard remote runner다. 현재 checkout에서의 `git diff --check`는 편집 직후 preflight로만 사용하고, runner/runtime evidence가 필요한 검증은 원격 runner 기준으로 판단한다.**

## 공통 규칙

- local 테스트/검증은 이 파일을 기준으로 판단한다.
- 작업 완료 검증은 변경 범위 기준으로 선택한다.
- 필수 검증을 실행하지 못하면 차단 사유로 보고한다.
- 최종 보고에는 실행 명령, 결과, 생략 사유, 남은 위험을 남긴다.
- 환경값, secret, 개인 endpoint는 tracked docs/roadmap에 쓰지 않는다.
- private input이 필요한 검증은 라우팅된 도메인/검증 시나리오별 문서를 읽고 필요한 값만 ignored local file에서 로드한다.
- raw token, password, webhook secret, provider credential, private key는 tracked docs, roadmap, task log, 최종 응답에 기록하지 않는다.
- 테스트용 Docker 환경을 작성/수정할 때는 Docker Compose `networks`, IPAM subnet, static IPv4, `extra_hosts`, host publish 문서 어디에도 `192.168.0.0/24` (`192.168.0.X`) 대역을 사용하지 않는다.
- 새 Docker 테스트 subnet이 필요하면 기존 workspace 포트/네트워크 표준을 먼저 따르고, 불가피한 경우 host LAN/VPN과 충돌하지 않는 `192.168.0.0/24` 밖의 private subnet만 사용한다.
- 컨테이너 내부 listen 포트는 제품 기본값을 우선 유지하고, workspace 충돌 관리는 host publish/direct smoke 포트로 처리한다.

## 기본 환경

- host: standard remote runner `toki@toki-labs.com`, code-server compose checkout. Host path is `$HOME/docker/services/code-server/data/volume/workspace/gito`; container path is `/config/workspace/gito`. `$HOME/agent-work/gito` is not the baseline checkout for gito.
- port: remote local profile은 Flutter/project preview `13060`, Core HTTP host publish 또는 direct smoke `18060`, optional proto-socket/agent transport `19060`, PostgreSQL/Redis host publish 후보 `15460/16360`을 쓴다. Core process/container 내부 기본 listen은 `8080`으로 유지하고, `127.0.0.1:8080`은 명시적 product compatibility 확인에만 사용한다. NomadCode local consumer target은 `http://127.0.0.1:18010/api/integrations/gito/webhook`이다. dev profile은 `agent-test/dev/rules.md`의 `13061/18061/19061/15461/16361`과 NomadCode dev `18011`을 사용한다. code-server service 자체는 `$HOME/docker/services/code-server/compose/docker-compose.yml`가 관리하며, gito 테스트 포트로 재정의하지 않는다.
- runtime: repo root helper(`bin/test`, `bin/lint`, `bin/build`)와 변경 범위별 Go, Flutter/Dart toolchain.
- package manager: Go modules, Flutter pub.
- docker: 기본 runner는 `$HOME/docker/services/code-server/compose/docker-compose.yml`의 `code-server`, `code-server-postgres`, `code-server-redis`를 사용한다. 비대화형 ssh에서 Docker CLI가 PATH에 없으면 `/usr/local/bin/docker`를 사용한다. gito 전용 DB 검증은 `code-server-postgres`에 `gito_test` DB를 만들고, code-server 컨테이너의 `DATABASE_URL`에서 DB 이름만 `gito_test`로 바꿔 `GITO_TEST_DATABASE_URL`에 주입한다. raw DSN/password는 출력하거나 tracked 파일에 기록하지 않는다. 별도 compose를 추가하거나 복제할 때는 project/network 이름을 `gito`로 분리하고 host publish 기본값을 `GITO_CORE_HOST_PORT=18060`, `GITO_POSTGRES_HOST_PORT=15460`, `GITO_REDIS_HOST_PORT=16360` 계열로 둔다.
- external service: Forgejo/Gitea/GitHub/GitLab/Jira/IOP 같은 provider 또는 runner 연동은 도메인/검증 시나리오별 문서가 명시한 경우에만 사용한다.
- model endpoint:
- credential: ignored local file 또는 `credential_ref` only. 구체 credential 경로와 사용 조건은 해당 도메인/검증 시나리오별 문서를 따른다.

## 라우팅

- workspace-ops / smoke / root helpers, docs, agent rules, roadmap, local test rules: `agent-test/local/workspace-ops-smoke.md`
- core / smoke / services/core backend, control plane, worker, shell baseline: `agent-test/local/core-smoke.md`
- contracts / smoke / packages/contracts and agent-contract notes baseline: `agent-test/local/contracts-smoke.md`
- client / smoke / apps/client Flutter control surface baseline: `agent-test/local/client-smoke.md`

## 라우팅 규칙

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