proto-socket/agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md

name

description

run-proto-socket-test-matrix

Run and summarize the Proto Socket validation matrix across proto schema sync plus Dart, Go, Kotlin, Python, and TypeScript tests. Use when the user asks for "전체 테스트", "전체테스트해", "전체 검증", "테스트 매트릭스", "proto 동기화 검사", "언어별 크로스 테스트", "언어간 크로스 테스트", "크로스 테스트해", "통신 테스트", or similar requests that require proto sync, same-language unit/transport tests, and cross-language server/client communication checks with PASS/FAIL tables.

Run Proto Socket Test Matrix

목적

Proto Socket의 proto schema sync와 지원 언어 전체 테스트 상태를 재현 가능한 명령으로 확인하고, 사용자에게 PASS/FAIL 표로 보고한다. 기본 범위는 proto 동기화 검사, 동일 언어 테스트, 언어간 크로스 통신 테스트 전체이며, 요청이 크로스 테스트만이면 크로스 범위만 실행한다.

언제 호출할지

• 사용자가 “전체 테스트해”, “전체테스트”, “전체 검증”, “테스트 매트릭스”처럼 전체 검증을 요청할 때
• 사용자가 “proto 동기화 검사”, “프로토 동기화”, “스키마 sync”처럼 proto 복사본 동기화 검증을 요청할 때
• 사용자가 “언어간 크로스 테스트해”, “언어별 크로스 테스트”, “통신 테스트”처럼 언어 간 통신 검증을 요청할 때
• 새 언어 추가, 통신 구현 변경, 테스트 정리 후 지원 언어 매트릭스의 현재 통과 여부를 표로 정리해야 할 때

입력

• scope: all, unit, cross, proto 중 하나. 사용자가 범위를 지정하지 않으면 all.
• report-format: 기본은 Markdown 표. 실패 시 실패 로그 tail과 재현 명령을 함께 적는다.

먼저 확인할 것

• 세션에서 아직 읽지 않았다면 agent-ops/rules/project/rules.md와, 존재할 경우 agent-ops/rules/private/rules.md를 읽는다.
• 테스트만 실행할 때는 소스 수정 계획을 세우지 않는다. 실패 원인 수정까지 요청받은 경우에만 관련 domain rule을 읽고 코드 변경한다.
• agent-task/archive/**는 사용자가 명시적으로 요청한 경우에만 읽는다.
• 고정 포트를 쓰는 크로스테스트가 있으므로 크로스테스트는 순차 실행한다.

실행 절차

1. 범위 결정

   • “전체 테스트”, “전체 검증”, “테스트 매트릭스” 요청은 all로 실행한다.
   • “proto 동기화 검사”, “프로토 sync” 요청은 proto로 실행한다.
   • “언어간 크로스 테스트”, “크로스 테스트”, “통신 테스트” 요청은 사용자가 유닛 테스트도 요구하지 않는 한 cross로 실행한다.
   • “유닛 테스트”, “동일 언어 테스트” 요청은 unit으로 실행한다.

2. 스크립트 실행

   • 저장소 루트에서 다음 중 하나를 실행한다.

bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --unit
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --cross
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --proto

3. 수동 fallback
   • 스크립트를 쓸 수 없으면 README의 package-local 명령을 사용한다.
   • Proto 동기화 검사:

tools/check_proto_sync.sh

• 동일 언어 테스트:

(cd dart && dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js)
(cd go && go test ./...)
(cd kotlin && ./gradlew test)
(cd python && python3 -m pytest -q)
(cd typescript && npm run check && npm test)

• 크로스테스트는 서버 언어 행 기준으로 순차 실행한다.

(cd go && go run ./crosstest/go_dart.go)
(cd go && go run ./crosstest/go_kotlin.go)
(cd go && go run ./crosstest/go_python.go)
(cd go && go run ./crosstest/go_typescript.go)
(cd dart && dart run crosstest/dart_go.dart)
(cd dart && dart run crosstest/dart_kotlin.dart)
(cd dart && dart run crosstest/dart_python.dart)
(cd dart && dart run crosstest/dart_typescript.dart)
(cd kotlin && ./gradlew run -PmainClass=com.tokilabs.proto_socket.crosstest.KotlinDartKt)
(cd kotlin && ./gradlew run -PmainClass=com.tokilabs.proto_socket.crosstest.KotlinGoKt)
(cd kotlin && ./gradlew run -PmainClass=com.tokilabs.proto_socket.crosstest.KotlinPythonKt)
(cd kotlin && ./gradlew run -PmainClass=com.tokilabs.proto_socket.crosstest.KotlinTypescriptKt)
(cd python && python3 crosstest/python_dart.py)
(cd python && python3 crosstest/python_go.py)
(cd python && python3 crosstest/python_kotlin.py)
(cd python && python3 crosstest/python_typescript.py)
(cd typescript && ./node_modules/.bin/tsx crosstest/typescript_dart.ts)
(cd typescript && ./node_modules/.bin/tsx crosstest/typescript_go.ts)
(cd typescript && ./node_modules/.bin/tsx crosstest/typescript_kotlin.ts)
(cd typescript && ./node_modules/.bin/tsx crosstest/typescript_python.ts)

• Dart.web 클라이언트(브라우저 WS only)는 별도 표로 보고하며, 서버 언어별 runner를 순차 실행한다.

(cd dart && dart run crosstest/dart_web.dart)
(cd go && go run ./crosstest/go_dart_web.go)
(cd kotlin && ./gradlew run -PmainClass=com.tokilabs.proto_socket.crosstest.KotlinDartWebKt)
(cd python && python3 crosstest/python_dart_web.py)
(cd typescript && ./node_modules/.bin/tsx crosstest/typescript_dart_web.ts)

4. 결과 판정

   • 명령 종료 코드가 0이고 FAIL 라인이 없으면 PASS.
   • Proto 동기화 검사는 tools/check_proto_sync.sh 종료 코드가 0이면 PASS.
   • 크로스테스트는 각 방향의 PASS scenario=... 라인 수가 기대 개수와 일치하는지도 검증한다. 기본 cross matrix는 16개, Dart.web 표는 2개(send-push, request-response)를 기대한다.
   • 동일 언어 대각선 셀은 unit 또는 all 범위에서 해당 언어 동일 언어 테스트가 통과했을 때 PASS로 표시한다. cross만 실행했다면 대각선은 -로 둔다.
   • Dart.web 클라이언트는 브라우저 WS/WSS만 지원하므로 서버 행에는 넣지 않고, Dart.web과 Dart.web(WSS) 클라이언트 열로 보고한다.

5. 결과 보고

   • 요청 범위에 맞춰 proto 동기화 표, 동일 언어 테스트 표, 서버/클라이언트 크로스 통신 표를 한국어로 보고한다.
   • 실패가 있으면 실패 행을 먼저 보여주고, 실패 로그 tail과 재현 명령을 적는다.
   • 코드 변경은 하지 않았는지, 테스트 실행으로 생성된 캐시/빌드 산출물 외 작업트리 변경이 있는지 확인해 함께 알린다.

실행 결과 검증

• 요청 범위의 모든 명령이 실행되었는가
• 실패 명령의 재현 명령과 로그 요약을 남겼는가
• 최종 답변에 PASS/FAIL 표가 포함되었는가
• git status --short로 의도치 않은 소스 변경이 없는지 확인했는가
• 검증 실패 시: 누락된 명령을 실행하거나, 실행 불가 사유와 미검증 범위를 명확히 보고한다.

출력 형식

**Proto 동기화**
| 검사 | 명령 | 결과 |
|---|---|---|
| schema sync | `tools/check_proto_sync.sh` | PASS |

**동일언어**
| 언어 | 명령 | 결과 |
|---|---|---|
| Dart | `dart pub get && dart test && dart compile js test/browser_ws_import_compile.dart -o /tmp/proto_socket_browser_ws_import_compile.js` | PASS |

**언어 PASS 매트릭스**
| 서버 \ 클라이언트 | Dart.io | Dart.web | Dart.web(WSS) | Go | Kotlin | Python | TypeScript |
|---|---|---|---|---|---|---|---|
| Dart.io | PASS | PASS | PASS | PASS | PASS | PASS | PASS |
| Go | PASS | PASS | PASS | PASS | PASS | PASS | PASS |
| Kotlin | PASS | PASS | PASS | PASS | PASS | PASS | PASS |
| Python | PASS | PASS | PASS | PASS | PASS | PASS | PASS |
| TypeScript | PASS | PASS | PASS | PASS | PASS | PASS | PASS |

**크로스테스트 상세**
| 방향 | 결과 | PASS scenarios | Expected | FAIL lines |
|---|---:|---:|---:|---:|
| Dart.io -> Dart.web | PASS | 2 | 2 | 0 |
| Dart.io -> Dart.web(WSS) | PASS | 2 | 2 | 0 |
| Go -> Dart.web | PASS | 2 | 2 | 0 |
| Go -> Dart.web(WSS) | PASS | 2 | 2 | 0 |
| Kotlin -> Dart.web | PASS | 2 | 2 | 0 |
| Kotlin -> Dart.web(WSS) | PASS | 2 | 2 | 0 |
| Python -> Dart.web | PASS | 2 | 2 | 0 |
| Python -> Dart.web(WSS) | PASS | 2 | 2 | 0 |
| TypeScript -> Dart.web | PASS | 2 | 2 | 0 |
| TypeScript -> Dart.web(WSS) | PASS | 2 | 2 | 0 |

금지 사항

• 크로스테스트를 병렬 실행하지 않는다.
• 테스트 요청만 받았는데 소스 코드를 수정하지 않는다.
• 실패를 통과로 단정하지 않는다. 불확실하면 미검증 또는 실패 후보로 표시한다.
• agent-task/archive/**를 자동으로 읽지 않는다.