iop/agent-test/dev/client-smoke.md

---
test_env: dev
test_profile: client-smoke
domain: client
verification_type: smoke
last_rule_updated_at: 2026-07-30
---

# client-smoke dev 테스트

## 읽기 조건

- `apps/client/**` 또는 `packages/flutter/iop_console/**` 변경의 dev 테스트, 검증, 실행 조건 판단이 필요한 경우

## 적용 범위

- IOP Flutter client app shell
- IOP-owned embeddable console package
- Client-Control Plane proto-socket hello baseline
- Flutter widget/unit tests
- dev web preview와 compose web build URL 주입

## 분류

- domain: client
- verification_type: smoke
- scope: Flutter client와 IOP console package 변경

## 환경

- host: Flutter client 또는 `packages/flutter/iop_console`가 포함된 runtime evidence는 원격 runner `ssh toki@toki-labs.com`의 `/Users/toki/agent-work/iop-dev` 기준으로 수행한다.
- port: web/dev preview `13001`, Control Plane HTTP `18001`, Portal/Control Plane wire test endpoint `19001`, Edge-Node TCP transport `19003`.
- runtime: Flutter/Dart
- package manager: Flutter pub
- docker: compose 검증은 `docker compose --env-file .env.dev.example ...` 기준이다.
- external service: sibling path dependencies `../agent-shell`, `../nexo/packages/messaging_flutter`, `../proto-socket/dart`
- model endpoint:
- credential: token/secret 원문은 문서에 기록하지 않는다.

명령은 원격 runner 사용 시 `/Users/toki/agent-work/iop-dev` 기준으로 실행한다. 현재 작업 컨테이너의 변경분이 원격 checkout에 동기화되지 않았으면 원격 검증 완료로 보지 않는다.

원격 runner의 `../nexo`가 Docker build context 밖을 가리키는 symlink이면 BuildKit은 그 의존성을 따라가지 않는다. Web image build 전에는 필요한 `packages/messaging_flutter` subtree가 build context 안의 실제 디렉터리인지 확인한다. 일시적으로 materialize한 경우에는 build 직후 원래 symlink를 복구하고, 원본 Nexo checkout은 수정하지 않는다.

## 명령

- setup: `cd apps/client && flutter pub get`
- package-setup: `cd packages/flutter/iop_console && flutter pub get`
- unit: `cd apps/client && flutter test`
- package-unit: `cd packages/flutter/iop_console && flutter test`
- lint: `cd apps/client && flutter analyze --no-fatal-infos`
- smoke: `cd apps/client && flutter test`
- e2e: `IOP_WEB_PORT=13001 IOP_CONTROL_PLANE_HTTP_URL=http://toki-labs.com:18001 IOP_CONTROL_PLANE_WIRE_URL=ws://toki-labs.com:19001/client ./scripts/dev/web.sh`
- compose-e2e: `IOP_EDGE_NODE_TOKEN=<token> docker compose --env-file .env.dev.example up --build`
- web-build: `make client-build-web IOP_CONTROL_PLANE_HTTP_URL=http://toki-labs.com:18001 IOP_CONTROL_PLANE_WIRE_URL=ws://toki-labs.com:19001/client`
- model:
- full-cycle:

## 최소 검증

- client 또는 `packages/flutter/iop_console` 변경은 최소 `cd apps/client && flutter test`로 확인한다.
- `packages/flutter/iop_console` 자체 API나 widget 구조가 바뀌면 `cd packages/flutter/iop_console && flutter test` 실행 가능 여부를 확인한다.
- analyzer 영향이 있는 dependency, app shell, generated import 변경이면 `cd apps/client && flutter analyze --no-fatal-infos`를 함께 확인한다.
- Web build/deploy, `apps/client/Dockerfile`, `docker-compose.yml`, `scripts/dev/web.sh`, `Makefile client-build-web` 변경은 원격 runner에서 dev-server 기동 또는 compose build 중 변경 범위에 맞는 경로를 확인하고, 외부 브라우저 확인 URL이 `http://toki-labs.com:13001` 계열인지 보고한다.
- Web image를 fresh deployment 증거로 삼으려면 선택한 source ref에서 build가 성공해야 한다. dependency 또는 Flutter compile 오류로 build가 막힌 경우, 기존 healthy Web container는 기존 사용자 경로 증거로만 기록하고 새 ref 배포 성공으로 판정하지 않는다.
- compose 경로를 확인할 때는 `IOP_EDGE_NODE_TOKEN`을 원격 runner 환경에서 주입하고, token 원문은 tracked 파일에 기록하지 않는다.

## 보조 검증

- `cd apps/client && flutter pub get`
- `cd packages/flutter/iop_console && flutter pub get`

## 판정 기준

- Flutter test가 실패 없이 종료한다.
- Analyzer는 기존 non-fatal info를 기능 실패로 확대하지 않는다.
- path dependency가 없어 실행하지 못하면 누락된 sibling workspace를 차단 사유로 보고한다.
- dev web preview가 필요한 경우 browser-facing URL과 compiled Control Plane HTTP/WS URL이 모두 dev 포트(`13001`, `18001`, `19001`)를 사용한다.

## 기준 출력 예시

```text
All tests passed!
```

## 차단 기준

- 원격 runner 접근, Flutter SDK, Docker compose, 또는 필요한 dev 포트 개방이 없어 client runtime 검증을 실행할 수 없다.
- 필요한 sibling path dependency가 없어 `flutter pub get` 또는 test가 진행되지 않는다.
- Nexo symlink가 Docker build context 밖을 가리키거나, 이를 context 안에서 해소한 뒤에도 Flutter compile이 실패해 fresh Web image를 만들 수 없다. 이 경우 기존 Web container 재사용으로 fresh deployment 차단을 해소하지 않는다.

## 보고 항목

- 실행한 명령:
- 성공한 검증:
- 실패/차단된 검증:
- 생략 사유:
- 남은 위험:

## 금지 사항

- secret, token, 개인 endpoint 원문은 tracked 파일에 기록하지 않는다.
- IOP client에 NomadCode product shell UX를 직접 복제하지 않는다.