From 538e8d0d78a43b919fc8508d0384f49cc887b561 Mon Sep 17 00:00:00 2001 From: toki Date: Mon, 25 May 2026 21:55:31 +0900 Subject: [PATCH] update roadmap and documentation - Update README.md and example/README.md - Update agent-ops/roadmap/current.md and PHASE.md - Archive self-contained-test-harness.md milestone - Add docs/ directory --- README.md | 4 + .../milestones/self-contained-test-harness.md | 27 ++--- agent-ops/roadmap/current.md | 3 - .../phase/validation-foundation/PHASE.md | 4 +- docs/android-test-environment.md | 104 ++++++++++++++++++ example/README.md | 4 + 6 files changed, 128 insertions(+), 18 deletions(-) rename agent-ops/roadmap/{ => archive}/phase/validation-foundation/milestones/self-contained-test-harness.md (73%) create mode 100644 docs/android-test-environment.md diff --git a/README.md b/README.md index d2a74ec..ac72247 100644 --- a/README.md +++ b/README.md @@ -213,6 +213,10 @@ cd example/android ./gradlew testDebugUnitTest ``` +If the local machine does not have an Android SDK or Android device/emulator, +use the separate SSH-based Android test environment documented in +[`docs/android-test-environment.md`](docs/android-test-environment.md). + ## Test Strategy Use deterministic tests for repository-owned behavior. The example integration diff --git a/agent-ops/roadmap/phase/validation-foundation/milestones/self-contained-test-harness.md b/agent-ops/roadmap/archive/phase/validation-foundation/milestones/self-contained-test-harness.md similarity index 73% rename from agent-ops/roadmap/phase/validation-foundation/milestones/self-contained-test-harness.md rename to agent-ops/roadmap/archive/phase/validation-foundation/milestones/self-contained-test-harness.md index e3eacf6..ccbbdb6 100644 --- a/agent-ops/roadmap/phase/validation-foundation/milestones/self-contained-test-harness.md +++ b/agent-ops/roadmap/archive/phase/validation-foundation/milestones/self-contained-test-harness.md @@ -11,7 +11,7 @@ ## 상태 -[진행중] +[완료] ## 구현 잠금 @@ -39,11 +39,11 @@ 디바이스 또는 emulator에서 플러그인 연결을 확인하는 테스트를 둔다. -- [ ] [plugin-registration] example app에서 plugin registration이 정상 동작하는지 확인한다 +- [x] [plugin-registration] example app에서 plugin registration이 정상 동작하는지 확인한다 - [x] [method-channel] Dart에서 native method channel 호출을 검증한다 - [x] [event-channel] native event를 Dart stream으로 전달하는 흐름을 검증한다 - [x] [opened-routing] notification opened payload가 channel/thread callback으로 연결되는지 검증한다 -- [ ] [device-run] 연결된 Android device 또는 emulator에서 `flutter test integration_test` 실행 결과를 기록한다 +- [x] [device-run] 연결된 Android device 또는 emulator에서 `flutter test integration_test` 실행 결과를 기록한다 ### Epic: [test-controls] 재현 가능한 테스트 제어 @@ -55,20 +55,20 @@ ## 완료 기준 -- [ ] `example/` 앱만으로 plugin registration과 기본 channel 계약을 확인할 수 있다 +- [x] `example/` 앱만으로 plugin registration과 기본 channel 계약을 확인할 수 있다 - [x] `example/integration_test`가 singleton 접근 이상의 통합 경로를 검증한다 - [x] 실제 FCM이 없어도 테스트 가능한 경로와 수동 smoke 경로가 분리되어 있다 -- [ ] 소비 프로젝트 없이 새 plugin 변경의 기본 위험을 확인할 수 있다 +- [x] 소비 프로젝트 없이 새 plugin 변경의 기본 위험을 확인할 수 있다 ## 완료 리뷰 -- 상태: 없음 -- 요청일: 없음 -- 완료 근거: 없음 +- 상태: 승인됨 +- 요청일: 2026-05-25 +- 완료 근거: 2026-05-25 SSH Android 테스트 환경에서 최신 작업본을 동기화해 `flutter test integration_test -d emulator-5554`와 `./gradlew testDebugUnitTest`를 통과했다. - 리뷰 필요: - - [ ] 사용자가 완료 결과를 확인했다 - - [ ] archive 이동을 승인했다 -- 리뷰 코멘트: 없음 + - [x] 사용자가 완료 결과를 확인했다 + - [x] archive 이동을 승인했다 +- 리뷰 코멘트: 2026-05-25 사용자 검토 승인에 따라 완료 처리하고 archive로 이동한다. ## 범위 제외 @@ -82,5 +82,6 @@ - 표준선(선택): `example/`은 Flutter plugin 표준 host app으로 유지하고, 테스트용 기능은 제품 기능처럼 확장하지 않는다 - 선행 작업: 프로젝트 운영 계약 정리 - 후속 작업: 품질 게이트 자동화, Android 런타임 신뢰도 강화 -- 확인 필요: 연결된 Android device 또는 emulator에서 `cd example && flutter test integration_test`를 실행해 plugin registration과 기본 channel 계약을 확인한다. -- 최근 검증: 2026-05-25 `flutter analyze`, `flutter test`, `cd example && flutter analyze`, `cd example && flutter test` 통과. `cd example && flutter test integration_test`는 지원되는 device/emulator가 없어 실행하지 못했다. +- 별도 테스트 환경 가이드: `docs/android-test-environment.md` +- 확인 필요: 없음 +- 최근 검증: 2026-05-25 로컬에서 `flutter analyze`, `flutter test`, `cd example && flutter analyze`, `cd example && flutter test` 통과. SSH Android 테스트 환경(`toki@toki-labs.com`, `Pixel_6_Pro_API_34`)에서 최신 작업본 기준 `cd example && flutter test integration_test -d emulator-5554`, `cd example/android && ./gradlew testDebugUnitTest` 통과. diff --git a/agent-ops/roadmap/current.md b/agent-ops/roadmap/current.md index ab01a11..3830ac7 100644 --- a/agent-ops/roadmap/current.md +++ b/agent-ops/roadmap/current.md @@ -7,9 +7,6 @@ ## 활성 Milestone -- [진행중] 독립 테스트 하네스 정착 - - Phase: `agent-ops/roadmap/phase/validation-foundation/PHASE.md` - - 경로: `agent-ops/roadmap/phase/validation-foundation/milestones/self-contained-test-harness.md` - [계획] 품질 게이트 자동화 - Phase: `agent-ops/roadmap/phase/validation-foundation/PHASE.md` - 경로: `agent-ops/roadmap/phase/validation-foundation/milestones/quality-gates.md` diff --git a/agent-ops/roadmap/phase/validation-foundation/PHASE.md b/agent-ops/roadmap/phase/validation-foundation/PHASE.md index 3c181ce..83ee4b6 100644 --- a/agent-ops/roadmap/phase/validation-foundation/PHASE.md +++ b/agent-ops/roadmap/phase/validation-foundation/PHASE.md @@ -16,8 +16,8 @@ - [완료] 프로젝트 운영 계약 정리 - 경로: `agent-ops/roadmap/archive/phase/validation-foundation/milestones/project-operating-contract.md` - 요약: 플러그인의 목적, repo 구조, 소비 프로젝트와의 책임 경계를 문서와 규칙으로 정리한다. -- [진행중] 독립 테스트 하네스 정착 - - 경로: `agent-ops/roadmap/phase/validation-foundation/milestones/self-contained-test-harness.md` +- [완료] 독립 테스트 하네스 정착 + - 경로: `agent-ops/roadmap/archive/phase/validation-foundation/milestones/self-contained-test-harness.md` - 요약: `example/` 앱을 실제 소비 앱 대신 사용하는 얇은 통합 테스트 환경으로 정착시킨다. - [계획] 품질 게이트 자동화 - 경로: `agent-ops/roadmap/phase/validation-foundation/milestones/quality-gates.md` diff --git a/docs/android-test-environment.md b/docs/android-test-environment.md new file mode 100644 index 0000000..31c9c4e --- /dev/null +++ b/docs/android-test-environment.md @@ -0,0 +1,104 @@ +# Android Test Environment + +This repository can use `toki@toki-labs.com` as a separate Android test +environment when the local machine does not have an Android SDK, device, or +emulator. + +## Remote Host + +- SSH target: `toki@toki-labs.com` +- Flutter SDK: `/Users/toki/SDK/flutter/bin/flutter` +- Android SDK: `/Users/toki/Library/Android/sdk` +- Known usable AVD: `Pixel_6_Pro_API_34` + +Use these environment variables for every remote Android test session: + +```sh +export PATH="$HOME/SDK/flutter/bin:$HOME/Library/Android/sdk/emulator:$HOME/Library/Android/sdk/platform-tools:$HOME/Library/Android/sdk/cmdline-tools/latest/bin:$PATH" +export ANDROID_HOME="$HOME/Library/Android/sdk" +export ANDROID_SDK_ROOT="$ANDROID_HOME" +``` + +## Sync A Working Copy + +From the local repository root, copy the current working tree to an isolated +remote directory. This is useful when local changes are not committed yet. + +```sh +REMOTE_DIR='$HOME/tmp/mattermost-push-plugin-codex-test' + +tar \ + --exclude='./.git' \ + --exclude='./.dart_tool' \ + --exclude='./build' \ + --exclude='./example/.dart_tool' \ + --exclude='./example/build' \ + --exclude='./example/android/.gradle' \ + --exclude='./android/.gradle' \ + --exclude='./.gradle' \ + -czf - . \ + | ssh toki@toki-labs.com "rm -rf \"$REMOTE_DIR\" && mkdir -p \"$REMOTE_DIR\" && tar -xzf - -C \"$REMOTE_DIR\"" +``` + +## Start The Android Emulator + +Connect to the host and start the Android emulator if no Android device is +already connected. + +```sh +ssh toki@toki-labs.com + +export PATH="$HOME/SDK/flutter/bin:$HOME/Library/Android/sdk/emulator:$HOME/Library/Android/sdk/platform-tools:$HOME/Library/Android/sdk/cmdline-tools/latest/bin:$PATH" +export ANDROID_HOME="$HOME/Library/Android/sdk" +export ANDROID_SDK_ROOT="$ANDROID_HOME" + +flutter emulators +flutter emulators --launch Pixel_6_Pro_API_34 +``` + +For non-interactive sessions, a headless launch also works: + +```sh +nohup emulator -avd Pixel_6_Pro_API_34 -no-window -no-audio -no-boot-anim -gpu swiftshader_indirect > "$HOME/tmp/pixel6pro-api34-emulator.log" 2>&1 & +``` + +Wait until the emulator is ready: + +```sh +adb wait-for-device +until [ "$(adb shell getprop sys.boot_completed 2>/dev/null | tr -d '\r')" = "1" ]; do sleep 2; done +adb devices +``` + +## Run The Checks + +Run the deterministic Flutter checks: + +```sh +cd "$HOME/tmp/mattermost-push-plugin-codex-test" +flutter analyze +flutter test + +cd example +flutter analyze +flutter test +flutter test integration_test -d emulator-5554 +``` + +Run Android Gradle unit tests: + +```sh +cd "$HOME/tmp/mattermost-push-plugin-codex-test/example/android" +./gradlew testDebugUnitTest +``` + +## Interpreting Results + +- `flutter test integration_test -d emulator-5554` verifies plugin registration, + method-channel calls, EventChannel delivery, and opened-routing through the + Android host app. +- `./gradlew testDebugUnitTest` verifies the Android unit-test layer and proves + the Android SDK path is usable. +- Real Firebase FCM delivery, Mattermost ACK delivery, inline reply, and dismiss + behavior remain manual smoke checks because they require external service + configuration. diff --git a/example/README.md b/example/README.md index 53ebe68..45f3fb4 100644 --- a/example/README.md +++ b/example/README.md @@ -71,6 +71,10 @@ Run Android native unit tests from `example/android`: Android Gradle tests require a configured Android SDK through `ANDROID_HOME` or `example/android/local.properties`. +When the local machine does not have a usable Android SDK or emulator, use the +repository-level remote environment guide: +[`../docs/android-test-environment.md`](../docs/android-test-environment.md). + ## Maintenance Rules - Keep the app thin.