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.
• route-mode: auto, speed, stability, full 중 하나. 사용자가 4분류 요청을 할 때 실행 entrypoint를 전환할 때 사용한다.
• route-command: auto, speed, stability는 run_test_by_change.sh --route <mode> --dry-run으로 후보를 먼저 보고한다. full은 run_full_test.sh --dry-run으로 classifier 결과, full functional 추천 여부, nightly-pending 미실행/PASS 아님 항목을 먼저 보고한 뒤 run_full_test.sh 본 실행으로 이동한다.
• report-format: 기본은 Markdown 표. 실패 시 실패 로그 tail과 재현 명령을 함께 적는다.

먼저 확인할 것

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

실행 절차

1. 범위 결정

   • “전체 테스트”, “전체 검증”, “테스트 매트릭스” 요청은 all로 실행한다. 단, “전체 테스트 해봐”처럼 user-entrypoint 라우팅 문구는 아래 full route 규칙을 우선한다.
   • “proto 동기화 검사”, “프로토 sync” 요청은 proto로 실행한다.
   • “언어간 크로스 테스트”, “크로스 테스트”, “통신 테스트” 요청은 사용자가 유닛 테스트도 요구하지 않는 한 cross로 실행한다.
   • “유닛 테스트”, “동일 언어 테스트” 요청은 unit으로 실행한다.
   • “테스트 해봐”는 변경 기반 route를 auto로 계산해 기능/성능/안정성 후보를 함께 제시한다.
   • “속도 테스트 해봐”는 speed route를 우선해 성능 후보를 중심으로 계산한다.
   • “안정성 테스트 해봐”는 stability route를 우선해 안정성 후보를 중심으로 계산한다.
   • “전체 테스트 해봐”는 full route를 우선해 run_full_test.sh --dry-run으로 full functional periodic 실행 계약을 먼저 계산한다.
   • “성능 측정”, “성능 기준선”, “performance baseline”, “regression gate” 요청은 matrix가 아니라 성능 전용 shell을 실행한다.
   • route-mode는 문장에 따라 자동 해석한다. 실행 전 auto/speed/stability는 run_test_by_change.sh --route <mode> --dry-run, full은 run_full_test.sh --dry-run 출력으로 추천/예외 항목을 사용자에게 먼저 보고한다.

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

• 성능 전용 검증은 cross-lang compatibility matrix와 분리해 실행한다.

bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --full
bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --quick --baseline agent-test/runs/<baseline-record>.md

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과 재현 명령을 적는다.
   • 코드 변경은 하지 않았는지, 테스트 실행으로 생성된 캐시/빌드 산출물 외 작업트리 변경이 있는지 확인해 함께 알린다.

실행 결과 검증

• 요청 범위의 모든 명령이 실행되었는가
• 성능 요청이면 run_performance.sh 결과 파일과 regression 비교 여부를 보고했는가
• 실패 명령의 재현 명령과 로그 요약을 남겼는가
• 최종 답변에 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/**를 자동으로 읽지 않는다.

functional-routing anchor 정책

• --route auto에서 일반 언어 구현 변경은 파일명 방향 단서에 따라 functional-server-x5 <lang> 또는 functional-client-x5 <lang>를 recommended로 둔다.
• 같은 언어에서 server/client 방향이 모두 감지되거나 방향을 알 수 없으면 functional-both-x5 <lang>를 recommended로 둔다.
• transport, codec/framing/communicator, queue/gateway, public API entrypoint 변경은 파일명에 server/client 단서가 있어도 수정 언어 기준 functional-both-x5 <lang>를 우선한다.
• transport/queue 변경의 전역 후보(functional-both-x5 transport/queue)와 proto/communicator/public API wider 후보는 언어별 anchor 후보와 별도로 중복 제거된 recommended/skipped 상태로 남긴다.

full-functional-periodic 정책 (RFP-1, RFP-2, RFP-3)

• run_full_test.sh --dry-run 출력이 functional-full, functional-full-dart-web, functional-full-dart-web-wss를 recommended 상태로 포함하면 full functional periodic이 발동된다. 이 dry-run은 내부에서 run_test_by_change.sh --route full --dry-run classifier를 호출한다.
• full functional 호출 시 run_matrix.sh --all 또는 --cross 실행으로 언어 PASS 매트릭스(Dart.io, Dart.web, Dart.web(WSS), Go, Kotlin, Python, TypeScript)와 크로스테스트 상세 표를 반드시 확인한다.
• 언어 anchor 후보는 full 5x5 대신 run_matrix.sh --cross --anchor <lang> --direction server|client|both로 실행한다. self 방향은 해당 언어 동일언어 테스트로 채우고, Dart.web/WSS는 anchor x5에 포함하지 않는다.
• Dart.web과 Dart.web(WSS)는 브라우저 client runtime이므로 서버 행에는 넣지 않는다.
• Dart.web/WSS client coverage는 full matrix의 Dart.web 및 Dart.web(WSS) 열에서 각 server-capable 언어 행이 모두 PASS여야 한다.
• recommended: 즉시 실행 후보. runner가 실행해야 함.
• nightly-pending: 야간 별도 실행 후보. 실행하지 않은 것을 PASS로 보고하지 않음.
  • performance-full 후보 command: bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_performance.sh --full (20:00 이후 시작한 record만 baseline 후보)
  • stability-full 후보 command: bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stress.sh --full --profile sustained,parallel,payload (20:00 이후 시작한 record만 야간 측정 후보)
• skipped-candidate: 미실행 후보. runner가 실행하지 않음.
• --route auto 또는 --route speed에서 성능 영향 가능 변경은 performance-quick을 낮 시간 참고값으로 추천한다. 이 결과는 야간 baseline 완료 근거로 쓰지 않는다.
• --route auto 또는 --route stability에서 transport/queue/concurrency 변경은 stability-quick을 추천하고 timeout, nonce/type mismatch, FIFO, pending leak, queue/gateway backlog를 hard gate로 본다.
• --route full + docs_only=no이면 full functional periodic 발동. performance-full/stability-full 같은 nightly-pending 항목은 별도 기록만 하고 실행하지 않음.
• run_full_test.sh --dry-run은 실행 전 보고 전용이다. ### Nightly pending (미실행, PASS 아님) 항목은 20:00 이후 별도 실행 후보이며 dry-run 또는 daytime full route의 PASS 근거가 아니다.
• run_full_test.sh는 classifier -> recommended 확인 -> matrix 실행 workflow를 실행한다.

user-entrypoint route 정책

실행 wrapper (non-dry-run 포함)

요청	실행 entrypoint	동작
테스트 해봐	run_test_by_change.sh --route auto	dry-run으로 후보 보고 → recommended 항목 실행 → 결과 record 경로 기록. skipped/nightly-pending은 실행 안 함
속도 테스트 해봐	run_speed_test.sh	dry-run으로 speed 후보 보고 → performance-quick recommended면 run_performance.sh --quick 실행. nightly-pending full은 후보 command만 기록
안정성 테스트 해봐	run_stability_test.sh	dry-run으로 stability 후보 보고 → stability-quick recommended면 run_stress.sh --quick hard gate 실행. nightly-pending full은 후보 command만 기록

dry-run 전용 보고

• 테스트 해봐 (dry-run): bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_test_by_change.sh --route auto --dry-run으로 변경 파일, 선택된 functional/performance/stability 후보, skipped/nightly-pending 항목을 먼저 보고한다.
• 속도 테스트 해봐 (dry-run): bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_speed_test.sh --dry-run으로 performance-quick 중심 후보와 performance-full/stability-full nightly 후보를 분리해 보고한다. performance-full이 nightly-pending이면 20:00 이전 baseline PASS 근거가 아니다.
• 안정성 테스트 해봐 (dry-run): bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_stability_test.sh --dry-run으로 stability-quick hard gate 후보를 먼저 보고한다. timeout, nonce/type mismatch, FIFO violation, pending leak, queue/gateway backlog 위반이 있으면 성능 수치가 좋아도 PASS가 아니다.

결과 기록 계약

• non-dry-run 실행 시 선택 이유, 실행 명령, 결과 record 경로를 출력에 남긴다.
• 실행하지 않은 skipped/nightly-pending 항목은 PASS로 보고하지 않는다.
• nightly-pending 후보는 ## nightly-pending 후보 (미실행, PASS 아님) 섹션에 후보 command와 함께 기록한다.
• anchor 실행(functional-server-x5, functional-client-x5, functional-both-x5)은 지원 언어 target이면 run_matrix.sh --cross --anchor <lang> --direction <server|client|both>를 실행하고 결과 record를 남긴다. transport/queue 같은 비언어 target은 실행하지 않고 skipped로 기록한다.