테스트

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 전체 테스트 키트(스위트, 라이브, Docker): 테스트
• 업데이트 및 Plugin 패키지 검증: 업데이트 및 Plugin 테스트
• pnpm test:force: 기본 제어 포트를 점유하고 있는 남은 Gateway 프로세스를 종료한 다음, 격리된 Gateway 포트로 전체 Vitest 스위트를 실행하여 서버 테스트가 실행 중인 인스턴스와 충돌하지 않게 합니다. 이전 Gateway 실행으로 포트 18789가 점유된 상태로 남았을 때 사용하세요.
• pnpm test:coverage: vitest.unit.config.ts를 통해 V8 커버리지로 단위 스위트를 실행합니다. 이는 전체 저장소의 모든 파일 커버리지가 아니라 기본 단위 레인 커버리지 게이트입니다. 임계값은 줄/함수/문 70%, 분기 55%입니다. coverage.all이 false이고 기본 레인이 형제 소스 파일이 있는 non-fast 단위 테스트로 커버리지 포함 범위를 제한하므로, 이 게이트는 우연히 로드한 모든 전이 import 대신 이 레인이 소유한 소스를 측정합니다.
• pnpm test:coverage:changed: origin/main 이후 변경된 파일에 대해서만 단위 커버리지를 실행합니다.
• pnpm test:changed: 저비용 스마트 변경 테스트 실행입니다. 직접 테스트 편집, 형제 *.test.ts 파일, 명시적 소스 매핑, 로컬 import 그래프에서 정확한 대상을 실행합니다. 광범위한/config/package 변경은 정확한 테스트로 매핑되지 않는 한 건너뜁니다.
• OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed: 명시적인 광범위 변경 테스트 실행입니다. 테스트 하네스/config/package 편집이 Vitest의 더 넓은 changed-test 동작으로 폴백해야 할 때 사용하세요.
• pnpm changed:lanes: origin/main과의 diff로 트리거되는 아키텍처 레인을 표시합니다.
• pnpm check:changed: origin/main과의 diff에 대해 스마트 변경 체크 게이트를 실행합니다. 영향을 받는 아키텍처 레인에 대해 typecheck, lint, guard 명령을 실행하지만 Vitest 테스트는 실행하지 않습니다. 테스트 증명에는 pnpm test:changed 또는 명시적인 pnpm test <target>을 사용하세요.
• pnpm test: 명시적 파일/디렉터리 대상을 범위 지정된 Vitest 레인으로 라우팅합니다. 대상이 없는 실행은 고정 샤드 그룹을 사용하며 로컬 병렬 실행을 위해 리프 config로 확장됩니다. 확장 그룹은 항상 하나의 거대한 루트 프로젝트 프로세스 대신 확장별 샤드 config로 확장됩니다.
• 테스트 래퍼 실행은 짧은 [test] passed|failed|skipped ... in ... 요약으로 끝납니다. Vitest 자체 duration 줄은 샤드별 세부 정보로 유지됩니다.
• 공유 OpenClaw 테스트 상태: 테스트에 격리된 HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, config fixture, workspace, agent dir 또는 auth-profile store가 필요할 때 Vitest에서 src/test-utils/openclaw-test-state.ts를 사용하세요.
• 프로세스 E2E 헬퍼: Vitest 프로세스 수준 E2E 테스트에 실행 중인 Gateway, CLI env, 로그 캡처, 정리가 한곳에서 필요할 때 test/helpers/openclaw-test-instance.ts를 사용하세요.
• Docker/Bash E2E 헬퍼: scripts/lib/docker-e2e-image.sh를 source하는 레인은 docker_e2e_test_state_shell_b64 <label> <scenario>를 컨테이너에 전달하고 scripts/lib/openclaw-e2e-instance.sh로 디코드할 수 있습니다. multi-home 스크립트는 docker_e2e_test_state_function_b64를 전달하고 각 플로우에서 openclaw_test_state_create <label> <scenario>를 호출할 수 있습니다. 더 낮은 수준의 호출자는 컨테이너 내부 셸 스니펫에 scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>을 사용하거나, source할 수 있는 호스트 env 파일에 node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json을 사용할 수 있습니다. create 앞의 --는 최신 Node 런타임이 --env-file을 Node 플래그로 처리하지 못하게 합니다. Gateway를 시작하는 Docker/Bash 레인은 컨테이너 안에서 scripts/lib/openclaw-e2e-instance.sh를 source하여 엔트리포인트 해석, mock OpenAI 시작, Gateway 전경/백그라운드 실행, 준비 상태 probe, 상태 env export, 로그 덤프, 프로세스 정리를 수행할 수 있습니다.
• 전체, 확장, include-pattern 샤드 실행은 로컬 타이밍 데이터를 .artifacts/vitest-shard-timings.json에 업데이트합니다. 이후 whole-config 실행은 해당 타이밍을 사용해 느린 샤드와 빠른 샤드의 균형을 맞춥니다. Include-pattern CI 샤드는 타이밍 키에 샤드 이름을 추가하여, whole-config 타이밍 데이터를 대체하지 않고도 필터링된 샤드 타이밍이 보이게 유지합니다. 로컬 타이밍 아티팩트를 무시하려면 OPENCLAW_TEST_PROJECTS_TIMINGS=0을 설정하세요.
• 선택된 plugin-sdk 및 commands 테스트 파일은 이제 test/setup.ts만 유지하는 전용 light 레인을 통해 라우팅되며, runtime-heavy 케이스는 기존 레인에 남겨둡니다.
• 형제 테스트가 있는 소스 파일은 더 넓은 디렉터리 glob으로 폴백하기 전에 해당 형제 테스트로 매핑됩니다. src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers, src/plugins/contracts 아래의 헬퍼 편집은 의존성 경로가 정확할 때 모든 샤드를 광범위하게 실행하는 대신 로컬 import 그래프를 사용해 import하는 테스트를 실행합니다.
• auto-reply는 이제 세 개의 전용 config(core, top-level, reply)로도 분리되어 reply 하네스가 더 가벼운 top-level status/token/helper 테스트를 지배하지 않게 합니다.
• 기본 Vitest config는 이제 저장소 config 전반에서 공유 non-isolated runner를 활성화한 상태로 pool: "threads"와 isolate: false를 기본값으로 사용합니다.
• pnpm test:channels는 vitest.channels.config.ts를 실행합니다.
• pnpm test:extensions 및 pnpm test extensions는 모든 확장/Plugin 샤드를 실행합니다. 무거운 채널 Plugin, 브라우저 Plugin, OpenAI는 전용 샤드로 실행되고, 다른 Plugin 그룹은 batched 상태로 유지됩니다. 번들 Plugin 레인 하나에는 pnpm test extensions/<id>를 사용하세요.
• pnpm test:perf:imports: 명시적 파일/디렉터리 대상에 대해 범위 지정된 레인 라우팅을 계속 사용하면서 Vitest import-duration 및 import-breakdown 보고를 활성화합니다.
• pnpm test:perf:imports:changed: 동일한 import profiling이지만 origin/main 이후 변경된 파일에 대해서만 실행합니다.
• pnpm test:perf:changed:bench -- --ref <git-ref>는 동일한 커밋된 git diff에 대해 라우팅된 changed-mode 경로를 네이티브 루트 프로젝트 실행과 벤치마크합니다.
• pnpm test:perf:changed:bench -- --worktree는 먼저 커밋하지 않고 현재 worktree 변경 세트를 벤치마크합니다.
• pnpm test:perf:profile:main: Vitest 메인 스레드의 CPU profile을 .artifacts/vitest-main-profile에 씁니다.
• pnpm test:perf:profile:runner: 단위 runner의 CPU 및 heap profile을 .artifacts/vitest-runner-profile에 씁니다.
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: 모든 full-suite Vitest 리프 config를 직렬로 실행하고, 그룹화된 duration 데이터와 config별 JSON/log 아티팩트를 씁니다. Test Performance Agent는 느린 테스트 수정을 시도하기 전에 이를 baseline으로 사용합니다.
• pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json: 성능 중심 변경 후 그룹화된 보고서를 비교합니다.
• Gateway 통합: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test 또는 pnpm test:gateway로 opt-in합니다.
• pnpm test:e2e: Gateway end-to-end smoke 테스트(multi-instance WS/HTTP/node 페어링)를 실행합니다. vitest.e2e.config.ts에서 adaptive worker와 함께 threads + isolate: false를 기본값으로 사용합니다. OPENCLAW_E2E_WORKERS=<n>로 조정하고 자세한 로그에는 OPENCLAW_E2E_VERBOSE=1을 설정하세요.
• pnpm test:live: provider live 테스트(minimax/zai)를 실행합니다. 건너뛰기를 해제하려면 API 키와 LIVE=1 또는 provider별 *_LIVE_TEST=1이 필요합니다.
• pnpm test:docker:all: 공유 live-test 이미지를 빌드하고, OpenClaw를 npm tarball로 한 번 패킹하고, bare Node/Git runner 이미지와 해당 tarball을 /app에 설치하는 functional 이미지를 빌드/재사용한 다음, 가중치 스케줄러를 통해 OPENCLAW_SKIP_DOCKER_BUILD=1로 Docker smoke 레인을 실행합니다. bare 이미지(OPENCLAW_DOCKER_E2E_BARE_IMAGE)는 installer/update/plugin-dependency 레인에 사용되며, 이 레인들은 복사된 repo source 대신 미리 빌드된 tarball을 마운트합니다. functional 이미지(OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE)는 일반 built-app 기능 레인에 사용됩니다. scripts/package-openclaw-for-docker.mjs는 단일 local/CI package packer이며, Docker가 사용하기 전에 tarball과 dist/postinstall-inventory.json을 검증합니다. Docker 레인 정의는 scripts/lib/docker-e2e-scenarios.mjs에 있고, planner 로직은 scripts/lib/docker-e2e-plan.mjs에 있으며, scripts/test-docker-all.mjs는 선택된 plan을 실행합니다. node scripts/test-docker-all.mjs --plan-json은 Docker를 빌드하거나 실행하지 않고, 선택된 레인, image kind, package/live-image 필요 사항, state scenario, credential check에 대한 scheduler-owned CI plan을 출력합니다. OPENCLAW_DOCKER_ALL_PARALLELISM=<n>은 프로세스 슬롯을 제어하며 기본값은 10입니다. OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n>은 provider-sensitive tail pool을 제어하며 기본값은 10입니다. Heavy lane cap의 기본값은 OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=10, OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7입니다. provider cap은 OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4, OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4, OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4를 통해 provider당 하나의 heavy lane으로 기본 설정됩니다. 더 큰 호스트에는 OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT 또는 OPENCLAW_DOCKER_ALL_DOCKER_LIMIT를 사용하세요. 낮은 병렬성 호스트에서 하나의 레인이 유효 가중치 또는 리소스 cap을 초과해도, 빈 pool에서 시작할 수 있으며 capacity를 해제할 때까지 단독으로 실행됩니다. 로컬 Docker daemon create storm을 피하기 위해 레인 시작은 기본적으로 2초 간격으로 지연됩니다. OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms>로 재정의하세요. runner는 기본적으로 Docker를 preflight하고, 오래된 OpenClaw E2E 컨테이너를 정리하며, 30초마다 active-lane 상태를 출력하고, 호환되는 레인 간 provider CLI tool cache를 공유하고, 일시적인 live-provider 실패를 기본적으로 한 번 재시도하며(OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>), 이후 실행에서 longest-first ordering을 위해 레인 타이밍을 .artifacts/docker-tests/lane-timings.json에 저장합니다. Docker를 실행하지 않고 레인 manifest를 출력하려면 OPENCLAW_DOCKER_ALL_DRY_RUN=1을 사용하고, 상태 출력 조정에는 OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms>를 사용하며, 타이밍 재사용을 비활성화하려면 OPENCLAW_DOCKER_ALL_TIMINGS=0을 사용하세요. 결정적/local 레인만 실행하려면 OPENCLAW_DOCKER_ALL_LIVE_MODE=skip을 사용하고, live-provider 레인만 실행하려면 OPENCLAW_DOCKER_ALL_LIVE_MODE=only를 사용하세요. package alias는 pnpm test:docker:local:all 및 pnpm test:docker:live:all입니다. Live-only mode는 main 및 tail live 레인을 하나의 longest-first pool로 병합하여 provider bucket이 Claude, Codex, Gemini 작업을 함께 packed할 수 있게 합니다. runner는 OPENCLAW_DOCKER_ALL_FAIL_FAST=0이 설정되지 않은 한 첫 실패 이후 새로운 pooled lane 스케줄링을 중단하며, 각 레인에는 120분 fallback timeout이 있고 OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS로 재정의할 수 있습니다. 선택된 live/tail 레인은 더 엄격한 레인별 cap을 사용합니다. CLI backend Docker setup 명령에는 OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS를 통한 자체 timeout이 있습니다(기본값 180). 레인별 로그, summary.json, failures.json, phase timing은 .artifacts/docker-tests/<run-id>/ 아래에 기록됩니다. 느린 레인을 검사하려면 pnpm test:docker:timings <summary.json>을 사용하고, 저비용 targeted rerun 명령을 출력하려면 pnpm test:docker:rerun <run-id|summary.json|failures.json>을 사용하세요.
• pnpm test:docker:browser-cdp-snapshot: Chromium-backed source E2E 컨테이너를 빌드하고, raw CDP와 격리된 Gateway를 시작하며, browser doctor --deep을 실행한 다음 CDP role snapshot에 link URL, cursor-promoted clickable, iframe ref, frame metadata가 포함되는지 검증합니다.
• pnpm test:docker:skill-install: bare Docker runner에 패킹된 OpenClaw tarball을 설치하고, skills.install.allowUploadedArchives를 비활성화하며, live ClawHub 검색에서 현재 skill slug를 해석하고, openclaw skills install을 통해 설치한 다음 SKILL.md, .clawhub/origin.json, .clawhub/lock.json, skills info --json을 검증합니다.
• CLI backend live Docker probe는 예를 들어 pnpm test:docker:live-cli-backend:codex, pnpm test:docker:live-cli-backend:codex:resume, pnpm test:docker:live-cli-backend:codex:mcp처럼 focused lane으로 실행할 수 있습니다. Claude와 Gemini에는 일치하는 :resume 및 :mcp alias가 있습니다.
• pnpm test:docker:openwebui: Dockerized OpenClaw + Open WebUI를 시작하고, Open WebUI를 통해 로그인하며, /api/models를 확인한 다음 /api/chat/completions를 통해 실제 proxied chat을 실행합니다. 사용 가능한 live model key(예: ~/.profile의 OpenAI)가 필요하고, 외부 Open WebUI 이미지를 pull하며, 일반 unit/e2e 스위트처럼 CI-stable할 것으로 기대하지 않습니다.
• pnpm test:docker:mcp-channels: 시드된 Gateway 컨테이너와 openclaw mcp serve를 생성하는 두 번째 클라이언트 컨테이너를 시작한 다음, 실제 stdio 브리지를 통해 라우팅된 대화 발견, 트랜스크립트 읽기, 첨부 파일 메타데이터, 라이브 이벤트 큐 동작, 아웃바운드 전송 라우팅, Claude 스타일 채널 및 권한 알림을 검증합니다. Claude 알림 검증은 원시 stdio MCP 프레임을 직접 읽으므로 스모크가 브리지가 실제로 내보내는 내용을 반영합니다.
• pnpm test:docker:upgrade-survivor: 패킹된 OpenClaw tarball을 지저분한 기존 사용자 fixture 위에 설치하고, 라이브 제공자 또는 채널 키 없이 패키지 업데이트와 비대화형 doctor를 실행한 다음, 루프백 Gateway를 시작하고 에이전트, 채널 구성, Plugin 허용 목록, 작업공간/세션 파일, 오래된 레거시 Plugin 의존성 상태, 시작, RPC 상태가 유지되는지 확인합니다.
• pnpm test:docker:published-upgrade-survivor: 기본적으로 openclaw@latest를 설치하고, 라이브 제공자 또는 채널 키 없이 현실적인 기존 사용자 파일을 시드하며, 구워진 openclaw config set 명령 레시피로 해당 기준선을 구성하고, 게시된 설치를 패킹된 OpenClaw tarball로 업데이트하고, 비대화형 doctor를 실행하고, .artifacts/upgrade-survivor/summary.json을 쓴 다음, 루프백 Gateway를 시작하고 구성된 intent, 작업공간/세션 파일, 오래된 Plugin 구성 및 레거시 의존성 상태, 시작, /healthz, /readyz, RPC 상태가 유지되거나 깔끔하게 복구되는지 확인합니다. OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC로 기준선 하나를 재정의하거나, OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS로 openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15 같은 정확한 로컬 매트릭스를 확장하거나, OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues로 시나리오 fixture를 추가하세요. reported-issues 세트에는 업그레이드 중 구성된 외부 OpenClaw plugins가 자동으로 설치되는지 검증하는 configured-plugin-installs와 소스 전용 Plugin shadow가 시작을 깨뜨리지 않도록 하는 stale-source-plugin-shadow가 포함됩니다. Package Acceptance는 이를 published_upgrade_survivor_baseline, published_upgrade_survivor_baselines, published_upgrade_survivor_scenarios로 노출하며, 정확한 패키지 사양을 Docker 레인에 넘기기 전에 last-stable-4 또는 all-since-2026.4.23 같은 메타 기준선 토큰을 해석합니다.
• pnpm test:docker:update-migration: 정리가 많은 plugin-deps-cleanup 시나리오에서 published-upgrade survivor 하네스를 실행하며, 기본적으로 openclaw@2026.4.23에서 시작합니다. 별도의 Update Migration 워크플로는 baselines=all-since-2026.4.23으로 이 레인을 확장하여 .23 이후의 모든 안정 게시 패키지가 후보 버전으로 업데이트되고 Full Release CI 외부에서 구성된 Plugin 의존성 정리를 증명하도록 합니다.
• pnpm test:docker:plugins: 로컬 경로, file:, 호이스팅된 의존성이 있는 npm 레지스트리 패키지, git 이동 ref, ClawHub fixture, marketplace 업데이트, Claude 번들 활성화/검사에 대한 설치/업데이트 스모크를 실행합니다.

​

로컬 PR 게이트

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

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

​

모델 지연 시간 벤치마크(로컬 키)

• source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10
• 선택적 환경 변수: MINIMAX_API_KEY, MINIMAX_BASE_URL, MINIMAX_MODEL, ANTHROPIC_API_KEY
• 기본 프롬프트: “한 단어로만 답하세요: ok. 문장 부호나 추가 텍스트는 넣지 마세요.”

• minimax 중앙값 1279ms(최소 1114, 최대 2431)
• opus 중앙값 2454ms(최소 1224, 최대 3170)

​

CLI 시작 벤치마크

• 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 --preset real --case tasksJson --case tasksListJson --case tasksAuditJson --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

• startup: --version, --help, health, health --json, status --json, status
• real: health, status, status --json, sessions, sessions --json, tasks --json, tasks list --json, tasks audit --json, agents list --json, gateway status, gateway status --json, gateway health --json, config get gateway.port
• all: 두 프리셋 모두

• pnpm test:startup:bench:smoke는 대상 스모크 아티팩트를 .artifacts/cli-startup-bench-smoke.json에 기록합니다.
• pnpm test:startup:bench:save는 runs=5 및 warmup=1을 사용해 전체 스위트 아티팩트를 .artifacts/cli-startup-bench-all.json에 기록합니다.
• pnpm test:startup:bench:update는 runs=5 및 warmup=1을 사용해 체크인된 기준 픽스처를 test/fixtures/cli-startup-bench.json에서 새로 고칩니다.

• test/fixtures/cli-startup-bench.json
• pnpm test:startup:bench:update로 새로 고침
• pnpm test:startup:bench:check로 현재 결과를 픽스처와 비교

​

온보딩 E2E(Docker)

scripts/e2e/onboard-docker.sh

​

QR 가져오기 스모크(Docker)

pnpm test:docker:qr

​

관련 항목

• 테스트
• 라이브 테스트
• 업데이트 및 plugins 테스트