openclaw-test-performance

OpenClaw 테스트 성능

증거를 먼저 사용하세요. 목표는 커버리지를 유지하면서 pnpm test, 플러그인 스위트 및 플러그인 인스펙터의 속도/RSS를 실제로 개선하는 것이며, 추측에 의한 러너 튜닝이 아닙니다.

워크플로우

1. 편집하기 전에 관련 로컬 AGENTS.md 파일을 읽으십시오:
   • src/agents/AGENTS.md: 에이전트/임포트 핫스팟
   • src/channels/AGENTS.md 및 src/plugins/AGENTS.md: 플러그인/채널 지연 로딩
   • src/gateway/AGENTS.md: 서버 라이프사이클 테스트
   • test/helpers/AGENTS.md 및 src/channels/plugins/contracts/test-helpers/AGENTS.md: 공유 계약 헬퍼
   • src/infra/outbound/AGENTS.md: 아웃바운드/미디어/액션 테스트
2. 코드 변경 전에 기준을 설정하십시오:
   • 전체 스위트 랭킹에는 pnpm test:perf:groups --full-suite --allow-failures --output <file>을 선호합니다.
   • 번들 플러그인 범위의 경우, 전체 확장 스위핑 전에 가장 작은 관련 pnpm test:extensions:batch <plugin[,plugin...]> 또는 플러그인 인스펙터 명령을 실행하십시오.
   • 범위가 지정된 핫스팟의 경우 다음을 사용하십시오: /usr/bin/time -l pnpm test <file-or-files> --maxWorkers=1 --reporter=verbose
   • 임포트 의심이 있는 경우 다음을 추가하십시오: OPENCLAW_VITEST_IMPORT_DURATIONS=1 OPENCLAW_VITEST_PRINT_IMPORT_BREAKDOWN=1.
3. 벽/러너 노이즈와 실제 파일 비용을 분리하십시오:
   • Vitest 기간, 테스트 본문 타이밍, 임포트 분해, 벽 시간 및 최대 RSS를 비교하십시오.
   • 그룹/전체 스위트 숫자가 오래되었거나 노이즈가 있는 경우 단일 파일을 다시 실행하십시오.
   • 전체 스위트 그룹 실행에서 레인 실패가 보고되었지만 JSON은 테스트 통과를 나타내는 경우, 이를 하네스/노이즈로 캡처하고 의심 파일을 직접 확인하십시오.
4. 수익과 위험에 따라 다음 공격을 선택하십시오:
   • 높은 수익: 하나의 파일/테스트가 초 또는 RSS를 지배하고 명확한 근본 원인이 있는 경우.
   • 높은 영향력: 하나의 플러그인 또는 SDK 배럴이 모든 플러그인 인스펙터 또는 확장 배치 실행에서 광범위한 런타임을 로드하게 하는 경우.
   • 낮은 위험: 정적 디스크립터, 대상 파싱, 라우팅, 인증 우회, 설정 힌트, 레지스트리 픽스처, 테스트 서버 라이프사이클.
   • 높은 위험: 실제 메모리/런타임 동작, 라이브 프로바이더, 프로토콜 계약, 광범위한 프로덕션 리팩터.
5. 증상이 아닌 근본 원인을 수정하십시오:
   • 정적 메타데이터/파싱을 전체 런타임 및 빠른 경로에서 재사용되는 좁은 헬퍼 또는 경량 아티팩트로 이동하십시오.
   • 광범위한 목보다 의존성 주입, 로드된 플러그인 전용 조회, 명시적 픽스처 및 순수 헬퍼를 선호하십시오.
   • 신규 핸드셰이크가 관련이 없는 경우 스위트 수준의 서버/클라이언트를 재사용하십시오.
   • 테스트가 스케줄링을 증명하지 않는 한 스케줄러/백그라운드 루프를 꺼 두십시오.
   • 플러그인 경로에서 정적 메타데이터를 매니페스트/경량 아티팩트로 이동하고 런타임 플러그인 로드를 명시적 실행 경계 뒤에 유지하십시오.
6. 커버리지 형태를 유지하십시오:
   • 느린 통합 증명을 삭제하지 마십시오. 단, 정확한 프로덕션 구성이 명명된 헬퍼로 추출되어 테스트된 경우는 예외입니다.
   • 크로스 컴포넌트 연결이 중요할 때 하나의 저렴한 통합 스모크 테스트를 유지하십시오.
   • 제거된 우발적 커버리지가 있으면 명시적으로 명시하십시오.
7. 변경 후 동일한 명령을 다시 벤치마킹하고 초 및 백분율 이득을 계산하십시오.
8. 요청 시 또는 이 스레드가 추적 중인 경우 실행 보고서를 업데이트하십시오. 전/후 명령, 아티팩트, 커버리지 노트, 검증 및 다음 공격 순서를 포함하십시오.
9. 의도된 경로를 스테이징하고, 표준 Git으로 커밋하고, 사용자가 커밋/푸시를 요청했을 때 푸시하십시오. 이 공격을 위해 수정된 파일만 스테이징하십시오.

플러그인 스위트 워크플로우

성능 작업에 번들 플러그인, 플러그인 인스펙터, SDK 배럴, 패키지 경계 테스트 또는 확장 스위트가 관련된 경우 이 섹션을 사용하십시오.

1. 먼저 스위트 형태를 파악하십시오:
   • 소스 테스트: pnpm test extensions/<id> 또는 pnpm test:extensions:batch <id>
   • 패키지 경계: pnpm run test:extensions:package-boundary:canary 및 pnpm run test:extensions:package-boundary:compile
   • 모든 번들 소스 테스트: pnpm test:extensions
   • 플러그인 임포트 메모리: pnpm test:extensions:memory -- --json .artifacts/test-perf/extensions-memory.json
   • 플러그인 인스펙터/리포트 작업: 리포트 프리미티브를 plugin-inspector에 유지하고, 래퍼를 얇게 유지하며 명령이 지원할 때 피크 RSS를 수집하십시오.
2. 좁게 시작한 다음 넓히십시오:
   • 하나의 플러그인이 변경됨: 해당 플러그인의 테스트와 플러그인 인스펙터 슬라이스를 실행하십시오.
   • SDK/공용 배럴이 변경됨: 대표적인 프로바이더, 채널, 메모리 및 기능 플러그인을 추가하십시오.
   • 로더/런타임 미러가 변경됨: 필요에 따라 패키지 경계 검사 및 빌드/패키지 증명을 추가하십시오.
   • 알 수 없는 공유 플러그인 동작: pnpm test:extensions 전에 먼저 test:extensions:batch 그룹을 실행하십시오.
3. 플러그인 인스펙터 실패를 제품 신호로 취급하십시오:
   • JSON은 파싱 가능해야 합니다.
   • 경고/오류는 분류되어야 하며 숨겨져서는 안 됩니다.
   • 런타임 캡처는 조용하고 설정에 관대해야 합니다.
   • 명령 출력에는 가용 시 벽 시간, 종료 코드 및 피크 RSS가 포함되어야 합니다.
4. 호스트 선택을 위해 $openclaw-testing을 따르십시오. 신뢰할 수 있는 소스 벤치마크는 유사한 기계/부하 조건에서 로컬로 실행할 수 있습니다. 증명의 일부로 깨끗한 패키징, Linux/플랫폼 동작, 격리 또는 명시적 원격 요청이 있는 경우 $crabbox를 사용하고, 소유한 임대만 재사용하고 정리하십시오.
5. 플러그인 성능이 패키지 아티팩트에 민감한 경우, 소스 전용 타이밍을 신뢰하는 대신 release-openclaw-plugin-testing 및 패키지 승인으로 전환하십시오.

메트릭 수집

변경 전후에 적어도 하나의 안정적인 메트릭을 수집하십시오. 동일한 기계와 동일한 명령을 선호하십시오. Testbox 비교의 경우 가능하면 동일한 tbx_... ID를 사용하십시오.

메트릭	용도	선호 소스
벽 시간	사용자에게 보이는 스위트 비용	/usr/bin/time -l, 테스트 래퍼 기간, Testbox 실행 시간
Vitest 기간	테스트 본문/임포트 비용	파일/샤드별 Vitest 출력
임포트 기간	광범위한 배럴/런타임 로드	OPENCLAW_VITEST_IMPORT_DURATIONS=1
최대 RSS	메모리 압력 및 OOM 위험	/usr/bin/time -l, pnpm test:extensions:memory, 래퍼 메모리 요약
CPU/사용자/시스템	CPU 바운드 vs 대기 바운드 분할	로컬 /usr/bin/time -l, 로컬 CPU가 노이즈가 많을 때 Testbox 작업 타이밍
힙 증거	실제 누수 vs 유지된 모듈 그래프	openclaw-test-heap-leaks 워크플로

CPU/RSS를 포함한 로컬 범위 명령:

timeout 240 /usr/bin/time -l pnpm test <file> --maxWorkers=1 --reporter=verbose

플러그인 임포트 메모리 프로필:

pnpm build
pnpm test:extensions:memory -- --top 20 --json .artifacts/test-perf/extensions-memory.json

대상 플러그인 임포트 메모리:

pnpm test:extensions:memory -- --extension discord --extension telegram --skip-combined

힙/RSS 증가:

pnpm test:perf:groups \
  --config test/vitest/vitest.unit-fast.config.ts \
  --allow-failures \
  --output .artifacts/test-perf/unit-fast-memory.json
pnpm test:perf:profile:runner -- \
  --output-dir .artifacts/test-perf/vitest-runner-profile -- <file>

RSS가 간격을 넘어 계속 증가하거나, 작업자가 OOM이 발생하거나, 의심 명령에 앱 객체 보존이 있는 경우 openclaw-test-heap-leaks를 사용하십시오. 스냅샷 또는 리테이너가 이를 뒷받침할 때까지 RSS 증가를 누수라고 부르지 마십시오.

일반적인 근본 원인

• 정적 데이터를 위해 전체 번들 채널/플러그인 런타임이 로드됨.
• 이미 로드된 픽스처 또는 순수 파서로 충분할 때 getChannelPlugin() 폴백이 사용됨.
• 광범위한 api.ts, runtime-api.ts, test-api.ts 또는 플러그인 SDK 배럴이 핫 테스트로 가져와짐.
• SDK 루트 별칭 또는 패키지 배럴이 집중된 하위 경로를 다시 광범위한 플러그인 그래프로 끌어들임.
• 플러그인 인스펙터가 메타데이터, 리포트 또는 CI 정책 점수를 렌더링하기 위해 런타임 코드를 로드함.
• 번들 플러그인 캡처가 합성, 수정, 격리된 상태 대신 실제 구성/홈 상태를 재사용함.
• 부분 실제 목이 광범위한 모듈 주변에서 importActual()을 사용함.
• 테스트별 루프에서 vi.resetModules()와 새로운 임포트를 사용함.
• beforeAll에서 테스트 플러그인 레지스트리가 시드되고 afterEach에서 런타임 상태가 재설정됨.
• 상태 재설정으로 충분할 때 테스트별 게이트웨이/서버/클라이언트 시작.
• 유휴 스냅샷 또는 픽스처가 지불하는 런타임/기본 모델/인증 선택.
• 인수에 플러그인 소유 필드가 포함되어 있는지 확인하기 전에 플러그인 소유 미디어/액션 검색이 트리거됨.
• 고유한 OPENCLAW_VITEST_FS_MODULE_CACHE_PATH 값 없이 node_modules/.experimental-vitest-cache를 공유하는 병렬 Vitest 실행.

벤치마크 명령

범위 파일:

timeout 240 /usr/bin/time -l pnpm test <file> --maxWorkers=1 --reporter=verbose

임포트 분해가 포함된 범위 파일:

timeout 240 /usr/bin/time -l env \
  OPENCLAW_VITEST_IMPORT_DURATIONS=1 \
  OPENCLAW_VITEST_PRINT_IMPORT_BREAKDOWN=1 \
  pnpm test <file> --maxWorkers=1 --reporter=verbose

그룹 스위트:

pnpm test:perf:groups --full-suite --allow-failures \
  --output .artifacts/test-perf/<name>.json

확장 배치:

pnpm test:extensions:batch <plugin[,plugin...]> -- --reporter=verbose

모든 확장 테스트:

pnpm test:extensions

패키지 경계 플러그인 검사:

pnpm run test:extensions:package-boundary:canary
pnpm run test:extensions:package-boundary:compile

기존 Vitest JSON 리포트 재사용:

pnpm test:perf:groups --report <vitest-json> \
  --output .artifacts/test-perf/<name>.json

검증

• 항상 변경 사항을 증명하는 대상 테스트 표면을 실행하십시오.
• 집중 테스트, 필수 빌드, 증명 라우팅 및 게시 타이밍에 대해 OpenClaw 테스팅을 따르십시오.
• 테스트 전용 변경의 경우, 해당 소유자의 지원 명령을 통해 정확히 편집된 테스트를 실행하십시오.
• 플러그인 SDK/배럴/런타임 변경의 경우, 공용 API 표면이 달라질 수 있을 때 pnpm plugin-sdk:api:diff -- --base <base-sha> --head <head-sha>로 정확한 커밋을 비교하십시오. PR 로컬 증명의 경우 브랜치 병합 베이스를 <base-sha>로, 정확히 테스트된 헤드 커밋을 <head-sha>로 사용하십시오.
• 플러그인 스위트 성능 수정의 경우, 변경된 게이트와 대표 플러그인 배치를 하나 이상 검증하십시오. 버그가 패킹된 아티팩트에만 존재하는 경우 패키지 승인을 사용하십시오.
• 누락되거나 오래된 종속성의 경우 소스 종속성 및 현재 작업 트리 소유자의 지침을 따르십시오. 적격한 증명 경로를 사용하십시오.
• 리포트 형식을 사용하십시오:

| 메트릭         | 이전 | 이후 |          이득 |
| -------------- | ---: | ---: | ------------: |
| 파일 벽 시간 |   `Xs` |   `Ys` |  `-Zs` (`P%`) |
| 최대 RSS        |  `XMB` |  `YMB` | `-ZMB` (`P%`) |
| CPU 사용자/시스템   | `X/Ys` | `A/Bs` |       설명 |

인계

최종 내용을 간결하게 유지하십시오:

• 근본 원인.
• 스위트/플러그인 범위.
• 변경된 파일.
• 가능한 경우 이전/이후 벽, Vitest/임포트, CPU 및 RSS 숫자.
• 메모리가 관련된 경우 누수 분류: 실제 누수, 유지된 모듈 그래프 또는 불확실.
• 유지된 커버리지.
• 검증 명령.
• 원격 증명을 위한 Testbox ID 또는 워크플로 URL.
• 커밋 해시 및 푸시 상태.