OpenClaw 테스트 가이드: 단위 테스트부터 E2E까지 완벽 설정

테스트를 작성하고 관리하는 과정에서 예상치 못한 오류나 성능 저하를 마주하면 정말 막막하죠. 특히 복잡한 환경에서 코드가 의도대로 동작하는지 확인하는 것은 모든 개발자가 겪는 공통적인 고민입니다.

OpenClaw 테스트 및 성능 벤치마크 도구를 활용하면 이러한 문제를 효율적으로 해결할 수 있습니다. 이 가이드를 통해 OpenClaw의 테스트 환경을 설정하고 성능을 최적화하는 방법을 살펴보세요.

테스트

전체 테스트 키트(스위트, 라이브, Docker)에 대한 자세한 내용은 Testing 문서를 확인해 주세요.

pnpm test:force: 기본 제어 포트를 점유하고 있는 기존 Gateway 프로세스를 강제로 종료한 뒤, 서버 테스트가 실행 중인 인스턴스와 충돌하지 않도록 격리된 Gateway 포트에서 전체 Vitest 스위트를 실행합니다. 이전 Gateway 실행으로 인해 18789 포트가 점유된 상태일 때 사용하세요.
pnpm test:coverage: vitest.unit.config.ts를 통해 V8 커버리지를 포함한 유닛 스위트를 실행합니다. 이는 전체 레포지토리 파일이 아닌, 유닛 커버리지 스위트에 의해 로드된 파일들을 대상으로 합니다. 임계값은 라인/함수/문장 기준 70%, 분기 기준 55%입니다.
pnpm test:coverage:changed: origin/main 이후 변경된 파일에 대해서만 유닛 커버리지를 실행합니다.
pnpm test:changed: 변경 사항이 라우팅 가능한 소스/테스트 파일에만 영향을 미칠 경우, 변경된 git 경로를 스코프가 지정된 Vitest 레인으로 확장합니다. 설정이나 셋업 변경 시에는 기본 루트 프로젝트 실행으로 돌아가 필요한 경우 와이어링 편집을 광범위하게 다시 실행합니다.
pnpm changed:lanes: origin/main 대비 변경 사항에 의해 트리거되는 아키텍처 레인을 보여줍니다.
pnpm check:changed: origin/main 대비 변경 사항에 대해 스마트 변경 게이트를 실행합니다. 핵심 작업은 핵심 테스트 레인에서, 확장 작업은 확장 테스트 레인에서 실행하며, 테스트 전용 작업은 테스트 타입 체크/테스트만 수행하고, 공개 Plugin SDK나 플러그인 계약 변경 사항은 확장 검증으로 확장합니다.
pnpm test: 명시적인 파일/디렉토리 타겟을 스코프가 지정된 Vitest 레인으로 라우팅합니다. 타겟이 없는 실행은 고정된 샤드 그룹을 사용하며, 로컬 병렬 실행을 위해 리프 설정으로 확장됩니다. 확장 그룹은 하나의 거대한 루트 프로젝트 프로세스 대신 항상 확장별 샤드 설정으로 확장됩니다.
전체 및 확장 샤드 실행은 .artifacts/vitest-shard-timings.json의 로컬 타이밍 데이터를 업데이트하며, 이후 실행 시 이 타이밍을 사용하여 느린 샤드와 빠른 샤드의 균형을 맞춥니다. 로컬 타이밍 아티팩트를 무시하려면 OPENCLAW_TEST_PROJECTS_TIMINGS=0을 설정하세요.
선택된 plugin-sdk 및 commands 테스트 파일은 이제 test/setup.ts만 유지하는 전용 경량 레인으로 라우팅되어, 런타임이 무거운 케이스는 기존 레인에 남겨둡니다.
선택된 plugin-sdk 및 commands 헬퍼 소스 파일도 pnpm test:changed를 해당 경량 레인의 명시적 형제 테스트에 매핑하여, 작은 헬퍼 수정 시 무거운 런타임 기반 스위트가 다시 실행되는 것을 방지합니다.
auto-reply는 이제 세 개의 전용 설정(core, top-level, reply)으로 분할되어, reply 하네스가 가벼운 최상위 상태/토큰/헬퍼 테스트를 압도하지 않도록 합니다.
기본 Vitest 설정은 이제 기본적으로 pool: "threads" 및 isolate: false를 사용하며, 레포지토리 설정 전반에 걸쳐 공유 비격리 러너가 활성화됩니다.
pnpm test:channels: vitest.channels.config.ts를 실행합니다.
pnpm test:extensions 및 pnpm test extensions: 모든 확장/플러그인 샤드를 실행합니다. 무거운 채널 확장과 OpenAI는 전용 샤드로 실행되며, 다른 확장 그룹은 배치 처리됩니다. 단일 번들 플러그인 레인을 사용하려면 pnpm test extensions/<id>를 사용하세요.
pnpm test:perf:imports: 명시적 파일/디렉토리 타겟에 대해 스코프 지정 레인 라우팅을 사용하면서 Vitest 임포트 지속 시간 및 분석 보고를 활성화합니다.
pnpm test:perf:imports:changed: 위와 동일한 임포트 프로파일링을 수행하되, origin/main 이후 변경된 파일만 대상으로 합니다.
pnpm test:perf:changed:bench — —ref <git-ref>: 동일한 커밋된 git diff에 대해 네이티브 루트 프로젝트 실행과 라우팅된 변경 모드 경로를 벤치마킹합니다.
pnpm test:perf:changed:bench — —worktree: 커밋하지 않고 현재 워크트리 변경 세트를 벤치마킹합니다.
pnpm test:perf:profile:main: Vitest 메인 스레드에 대한 CPU 프로파일을 .artifacts/vitest-main-profile에 기록합니다.
pnpm test:perf:profile:runner: 유닛 러너에 대한 CPU 및 힙 프로파일을 .artifacts/vitest-runner-profile에 기록합니다.
Gateway 통합: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test 또는 pnpm test:gateway를 통해 옵트인할 수 있습니다.
pnpm test:e2e: Gateway 엔드투엔드 스모크 테스트(다중 인스턴스 WS/HTTP/Node 페어링)를 실행합니다. vitest.e2e.config.ts에서 threads + isolate: false 및 적응형 워커를 기본값으로 사용하며, OPENCLAW_E2E_WORKERS=<n>으로 조정하고 상세 로그를 보려면 OPENCLAW_E2E_VERBOSE=1을 설정하세요.
pnpm test:live: 제공자 라이브 테스트(minimax/zai)를 실행합니다. API 키가 필요하며, 건너뛰지 않으려면 LIVE=1(또는 제공자별 *_LIVE_TEST=1)을 설정해야 합니다.
pnpm test:docker:openwebui: Docker화된 OpenClaw와 Open WebUI를 시작하고, Open WebUI를 통해 로그인한 뒤 /api/models를 확인하고 /api/chat/completions를 통해 실제 프록시 채팅을 실행합니다. 사용 가능한 라이브 모델 키가 필요하며, 외부 Open WebUI 이미지를 가져옵니다. 일반 유닛/e2e 스위트처럼 CI에서 안정적이지 않을 수 있습니다.
pnpm test:docker:mcp-channels: 시드된 Gateway 컨테이너와 openclaw mcp serve를 생성하는 두 번째 클라이언트 컨테이너를 시작합니다. 이후 라우팅된 대화 탐색, 트랜스크립트 읽기, 첨부 파일 메타데이터, 라이브 이벤트 큐 동작, 아웃바운드 전송 라우팅, Claude 스타일 채널 및 권한 알림을 실제 stdio 브릿지를 통해 검증합니다.

Local PR gate

로컬 PR 제출 전 게이트 체크를 위해 다음 명령어를 실행하세요.

pnpm check:changed
pnpm check
pnpm check:test-types
pnpm build
pnpm test
pnpm check:docs

만약 로드된 호스트에서 pnpm test가 불안정하다면, 회귀로 간주하기 전에 한 번 더 실행해 보고 pnpm test <path/to/test>로 격리하여 실행하세요. 메모리가 제한된 호스트에서는 다음을 사용하세요:

OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

Model latency bench (local keys)

모델 응답 속도를 측정하기 위한 벤치마크 스크립트입니다.

스크립트 위치: scripts/bench-model.ts
사용법:

source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10

선택적 환경 변수: MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_MODEL, ANTHROPIC_API_KEY
기본 프롬프트: “Reply with a single word: ok. No punctuation or extra text.”

CLI startup bench

CLI 시작 성능을 측정하고 벤치마크 결과를 관리합니다.

스크립트 위치: scripts/bench-cli-startup.ts
사용법:

pnpm test:startup:bench
pnpm test:startup:bench:smoke
pnpm test:startup:bench:save
pnpm test:startup:bench:update
pnpm test:startup:bench:check
pnpm tsx scripts/bench-cli-startup.ts
pnpm tsx scripts/bench-cli-startup.ts --runs 12
pnpm tsx scripts/bench-cli-startup.ts --preset real
pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3
pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all
pnpm tsx scripts/bench-cli-startup.ts --preset all --output .artifacts/cli-startup-bench-all.json
pnpm tsx scripts/bench-cli-startup.ts --preset real --case gatewayStatusJson --output .artifacts/cli-startup-bench-smoke.json
pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
pnpm tsx scripts/bench-cli-startup.ts --json

Onboarding E2E (Docker)

Docker를 사용한 온보딩 스모크 테스트를 수행합니다.

깨끗한 Linux 컨테이너에서의 전체 콜드 스타트 흐름:

scripts/e2e/onboard-docker.sh

이 스크립트는 의사 터미널(pseudo-tty)을 통해 대화형 마법사를 구동하고, 설정/워크스페이스/세션 파일을 확인한 뒤 Gateway를 시작하고 openclaw health를 실행합니다.

QR import smoke (Docker)

지원되는 Docker Node 런타임에서 qrcode-terminal이 정상적으로 로드되는지 확인합니다.

실행 명령어:

pnpm test:docker:qr

더 자세한 도움이 필요하시면 AI Setup Assistant를 이용해 주세요.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.