테스트

• 전체 테스트 키트(스위트, 라이브, Docker): 테스트
• 업데이트 및 Plugin 패키지 검증: 업데이트 및 Plugin 테스트

에이전트 기본값

에이전트 세션은 신뢰할 수 있는 소스이고 기존 종속성 설치가 준비된 경우에만 하나 또는 몇 개의 집중 테스트와 저비용 정적 검사를 로컬에서 실행합니다. 신뢰할 수 없는 리포지토리 도구는 로컬에서 절대 실행하지 마십시오. 더 큰 스위트, 타입 검사/린트가 분산 실행되는 변경 게이트, 빌드, Docker, 패키지 레인, E2E, 라이브 증명 및 크로스 플랫폼 검증은 Crabbox를 통해 원격으로 실행합니다. 신뢰할 수 있는 메인테이너의 대규모 증명에는 기본적으로 Blacksmith Testbox를 사용합니다. 구성된 Testbox 워크플로는 자격 증명을 주입하므로, 신뢰할 수 없는 기여자 또는 포크 코드는 대신 비밀 정보가 없는 포크 CI나 정제된 직접 AWS Crabbox를 사용해야 합니다.

예상되는 작업을 위해 미리 워밍업하지 마십시오. 첫 번째 대규모 명령이 준비되면 백엔드를 지연 획득하고, 반환된 tbx_... id를 이후의 대규모 명령에 재사용하며, 실행할 때마다 현재 체크아웃을 동기화하고 인계 전에 중지하십시오.

첫 번째 재사용이 성공하면 래퍼는 리스의 베이스, 종속성 및 Testbox 워크플로 지문을 .crabbox/testbox-leases/ 아래에 기록합니다. 소스만 편집한 경우 워밍업된 박스를 계속 재사용합니다. 병합 베이스, 잠금 파일, 패키지 관리자 입력, 래퍼 또는 Testbox 워크플로가 변경되면 안전하게 실패하고 새 리스가 필요합니다. 모든 실행은 여전히 현재 체크아웃을 동기화합니다. OPENCLAW_TESTBOX_ALLOW_STALE=1은 의도적인 진단에만 사용하며 릴리스 증명에는 사용하지 않습니다.

아래의 로컬 테스트 명령은 사람이 수행하는 워크플로와 제한된 에이전트 증명을 위한 것입니다. 원격 공급자를 사용할 수 없는 경우 이를 보고해야 하며, 그렇다고 해서 광범위한 로컬 게이트를 암묵적으로 실행할 수 있는 것은 아닙니다.

신뢰할 수 없는 대규모 증명의 경우 --provider aws으로 지연 워밍업하십시오. 모든 실행은 CRABBOX_ENV_ALLOW=CI을 설정하고, --provider aws --no-hydrate을 전달하며, 종속성을 설치하거나 테스트를 실행하기 전에 새로운 임시 원격 HOME을 사용해야 합니다. 해당 신뢰할 수 없는 소스 전용으로 새로 워밍업한 리스를 사용하고, 신뢰할 수 있거나 이전에 자격 증명이 주입된 리스는 절대 재사용하지 마십시오. 깨끗하고 신뢰할 수 있는 main 체크아웃에서 설치된 신뢰할 수 있는 Crabbox 바이너리를 실행하고 --fresh-pr을 사용하여 원격 PR만 가져오십시오. 신뢰할 수 없는 체크아웃의 래퍼나 구성을 로컬에서 절대 실행하지 마십시오. CRABBOX_AWS_INSTANCE_PROFILE을 설정 해제하고, 확인된 aws.instanceProfile이 비어 있지 않으면 안전하게 실패하십시오. 설치/테스트 전에 신뢰할 수 있는 절대 경로 도구를 사용하여 IMDSv2 토큰을 요구하고, IAM 자격 증명 엔드포인트가 404를 반환하는지 증명하며, 원격 git rev-parse HEAD이 검토된 전체 PR 헤드 SHA와 같은지 확인하십시오. 리스를 해당 SHA에 바인딩하고 헤드가 변경되면 중지한 후 다시 워밍업하십시오. 깨끗한 main에서 신뢰할 수 있는 scripts/crabbox-untrusted-bootstrap.sh을 --fresh-pr과 함께 업로드하십시오. 이 스크립트는 고정된 Node/pnpm을 설치하고, SHA와 패키지 관리자 고정값을 확인하고, HOME을 격리하고, 종속성을 설치한 다음 요청된 테스트를 실행합니다. 브로커가 역할이 없거나 원격 PR이 존재하지 않음을 증명할 수 없다면 비밀 정보가 없는 포크 CI를 사용하십시오. hydrate-github, --no-sync 또는 자격 증명이 주입된 Testbox 워크플로는 사용하지 마십시오. 모든 CRABBOX_TAILSCALE* 재정의를 설정 해제하고, --network public --tailscale=false를 강제 적용하고, 출구 노드/LAN 플래그를 지우고, 스크립트를 업로드하기 전에 crabbox inspect이 Tailscale 상태 없이 공용 네트워킹을 보고하도록 요구하십시오.

일반적인 로컬 순서

1. 변경 범위 Vitest 증명에는 pnpm test:changed을 사용합니다.
2. 파일 하나, 디렉터리 하나 또는 명시적 대상에는 pnpm test <path-or-filter>을 사용합니다.
3. 의도적으로 전체 로컬 Vitest 스위트가 필요한 경우에만 pnpm test을 사용합니다.

Codex 워크트리 또는 연결된/희소 체크아웃에서 에이전트는 직접적인 로컬 pnpm test* / pnpm check* / pnpm crabbox:run을 피합니다.

• 종속성이 준비된 제한적 집중 증명: node scripts/run-vitest.mjs <path-or-filter>.
• 분류 우선 변경 검사: node scripts/check-changed.mjs; 문서 전용, 변경 없음 및 소규모 메타데이터 계획은 종속성이 준비된 경우 로컬에서 유지하고, 대규모이거나 종속성이 누락된 계획은 Testbox에 위임합니다.
• 명시적으로 유지된 리스를 사용하는 광범위한 증명: pnpm이 Testbox 내부에서 실행되도록 node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed을 사용합니다.
• 래퍼의 최종 exitCode과 타이밍 JSON이 명령 결과입니다. 위임된 Blacksmith GitHub Actions 실행에서는 Testbox가 keepalive 액션 외부에서 중지되므로 SSH 명령이 성공한 후 cancelled이 표시될 수 있습니다. 이를 실패로 간주하기 전에 래퍼 요약과 명령 출력을 확인하십시오.
• OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree <local-heavy-check command>: pnpm check:changed 및 대상이 지정된 pnpm test ... 같은 명령의 대규모 검사 직렬화를 Git 공통 디렉터리 대신 현재 워크트리 내부에 유지합니다. 연결된 워크트리 간에 독립적인 검사를 의도적으로 실행하는 고용량 로컬 호스트에서만 사용하십시오.

핵심 명령

테스트 래퍼 실행은 짧은 [test] passed|failed|skipped ... in ... 요약으로 끝나며, Vitest 자체의 소요 시간 줄은 샤드별 세부 정보로 유지됩니다.

공유 테스트 상태 및 프로세스 도우미

• src/test-utils/openclaw-test-state.ts: 테스트에 격리된 HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, 구성 픽스처, 워크스페이스, 에이전트 디렉터리 또는 인증 프로필 저장소가 필요할 때 Vitest에서 사용합니다.
• pnpm test:env-mutations:report: HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH, OPENCLAW_WORKSPACE_DIR 또는 관련 환경 키를 직접 변경하는 테스트/하네스에 대한 비차단 보고서입니다. 공유 테스트 상태 도우미로 마이그레이션할 후보를 찾는 데 사용합니다.
• test/helpers/openclaw-test-instance.ts: 실행 중인 Gateway, CLI 환경, 로그 캡처 및 정리가 한곳에서 필요한 프로세스 수준 E2E 테스트입니다.
• scripts/lib/docker-e2e-image.sh을 소싱하는 Docker/Bash E2E 레인은 docker_e2e_test_state_shell_b64 <label> <scenario>을 컨테이너에 전달하고 scripts/lib/openclaw-e2e-instance.sh으로 디코딩할 수 있습니다. 다중 홈 스크립트는 docker_e2e_test_state_function_b64을 전달하고 각 흐름에서 openclaw_test_state_create <label> <scenario>을 호출할 수 있습니다. node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json은 소싱 가능한 호스트 환경 파일을 작성합니다(create 앞의 --은 최신 Node 런타임이 --env-file을 Node 플래그로 취급하지 않도록 합니다). Gateway를 실행하는 레인은 엔트리포인트 확인, 모의 OpenAI 시작, 포그라운드/백그라운드 실행, 준비 상태 프로브, 상태 환경 내보내기, 로그 덤프 및 프로세스 정리를 위해 scripts/lib/openclaw-e2e-instance.sh을 소싱할 수 있습니다.

Control UI, TUI 및 확장 레인

• Control UI 모의 E2E: pnpm test:ui:e2e은 Vite Control UI를 시작하고 모의 Gateway WebSocket을 대상으로 실제 Chromium 페이지를 구동하는 Vitest + Playwright 레인을 실행합니다. 테스트는 ui/src/**/*.e2e.test.ts에 있으며, 공유 모의 객체/제어 기능은 ui/src/test-helpers/control-ui-e2e.ts에 있습니다. pnpm test:e2e에는 이 레인이 포함됩니다. 에이전트 실행은 대상 증명을 포함하여 기본적으로 Testbox/Crabbox를 사용하며, 명시적으로 로컬 대체 수단이 필요한 경우에만 node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/ui/e2e/chat-flow.e2e.test.ts을 사용하십시오.
• TUI PTY 테스트: node scripts/run-vitest.mjs run --config test/vitest/vitest.tui-pty.config.ts은 빠른 가짜 백엔드 PTY 레인을 실행합니다. OPENCLAW_TUI_PTY_INCLUDE_LOCAL=1 또는 pnpm tui:pty:test:watch --mode local은 외부 모델 엔드포인트만 모의하는 더 느린 tui --local 스모크 테스트를 실행합니다. 원시 ANSI 스냅샷이 아니라 안정적으로 표시되는 텍스트나 픽스처 호출을 단언하십시오.
• pnpm test:extensions 및 pnpm test extensions은 모든 확장 프로그램/Plugin 샤드를 실행합니다. 무거운 채널 Plugin, 브라우저 Plugin 및 OpenAI는 전용 샤드로 실행되며, 다른 Plugin 그룹은 배치로 유지됩니다. pnpm test extensions/<id>은 번들 Plugin 레인 하나를 실행합니다.
• 형제 테스트가 있는 소스 파일은 더 넓은 디렉터리 glob으로 대체하기 전에 해당 형제 테스트에 매핑됩니다. src/channels/plugins/contracts/test-helpers, src/plugin-sdk/test-helpers 및 src/plugins/contracts 아래의 헬퍼 편집은 종속성 경로가 명확할 때 모든 샤드를 광범위하게 실행하는 대신 로컬 가져오기 그래프를 사용하여 이를 가져오는 테스트를 실행합니다.
• 계약 디렉터리 대상은 해당 계약 레인으로 분산됩니다. pnpm test src/channels/plugins/contracts은 네 개의 채널 계약 구성을 실행하고 pnpm test src/plugins/contracts은 Plugin 계약 구성을 실행합니다. 이는 일반 channels/plugins 프로젝트가 contracts/**을 제외하기 때문입니다.
• auto-reply은 세 개의 전용 구성(core, top-level, reply)으로 분할되어 응답 하네스가 더 가벼운 최상위 상태/토큰/헬퍼 테스트를 압도하지 않도록 합니다.
• 선택된 plugin-sdk 및 commands 테스트 파일은 test/setup.ts만 유지하는 전용 경량 레인을 통해 라우팅되며, 런타임 부하가 큰 사례는 기존 레인에 남겨 둡니다.
• 기본 Vitest 구성은 pool: "threads" 및 isolate: false을 기본값으로 사용하며, 저장소 전체 구성에서 공유 비격리 실행기가 활성화됩니다.
• pnpm test:channels은 vitest.channels.config.ts을 실행합니다.

Gateway 및 E2E

• Gateway 통합은 선택적으로 활성화합니다: OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test 또는 pnpm test:gateway.
• pnpm test:e2e: 저장소 E2E 집계 = pnpm test:e2e:gateway && pnpm test:ui:e2e.
• pnpm test:e2e:gateway: Gateway 엔드투엔드 스모크 테스트(다중 인스턴스 WS/HTTP/Node 페어링)입니다. vitest.e2e.config.ts의 적응형 워커와 함께 기본적으로 threads + isolate: false을 사용합니다. OPENCLAW_E2E_WORKERS=<n>으로 조정하고 OPENCLAW_E2E_VERBOSE=1으로 상세 로그를 활성화하십시오.
• pnpm test:live: 제공자 라이브 테스트(Claude/Minimax/DeepSeek/z.ai 등, *.live.test.ts으로 제한됨)입니다. 건너뛰기를 해제하려면 API 키와 LIVE=1(또는 OPENCLAW_LIVE_TEST=1)이 필요하며, OPENCLAW_LIVE_TEST_QUIET=0으로 상세 출력을 활성화합니다.

전체 Docker 제품군(pnpm test:docker:all)

공유 라이브 테스트 이미지를 빌드하고, OpenClaw를 npm tarball로 한 번 패키징하고, 기본 Node/Git 실행기 이미지와 해당 tarball을 /app에 설치하는 기능 이미지를 빌드하거나 재사용한 다음, 가중치 기반 스케줄러를 통해 Docker 스모크 레인을 실행합니다. scripts/package-openclaw-for-docker.mjs은 유일한 로컬/CI 패키지 패키저이며, Docker가 사용하기 전에 tarball과 dist/postinstall-inventory.json을 검증합니다.

• 기본 이미지(OPENCLAW_DOCKER_E2E_BARE_IMAGE): 설치 프로그램/업데이트/Plugin 종속성 레인으로, 복사된 저장소 소스 대신 미리 빌드된 tarball을 마운트합니다.
• 기능 이미지(OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE): 일반적인 빌드된 앱 기능 레인입니다.
• 레인 정의: scripts/lib/docker-e2e-scenarios.mjs. 플래너: scripts/lib/docker-e2e-plan.mjs. 실행기: scripts/test-docker-all.mjs.
• node scripts/test-docker-all.mjs --plan-json은 Docker를 빌드하거나 실행하지 않고 스케줄러가 소유하는 CI 계획(레인, 이미지 종류, 패키지/라이브 이미지 요구 사항, 상태 시나리오, 자격 증명 검사)을 출력합니다.

스케줄링 조정 항목(환경 변수, 괄호 안은 기본값):

리소스 상한의 환경 변수 패턴은 OPENCLAW_DOCKER_ALL_<RESOURCE>_LIMIT입니다(리소스 이름은 대문자로 변환되고 영숫자가 아닌 문자는 _으로 통합됨).

기타 동작: 러너는 기본적으로 Docker 사전 점검을 수행하고, 오래된 OpenClaw E2E 컨테이너를 정리하며, 호환되는 레인 간에 제공자 CLI 도구 캐시를 공유하고, OPENCLAW_DOCKER_ALL_FAIL_FAST=0이 설정되지 않은 경우 첫 번째 실패 이후 새로운 풀링 레인의 예약을 중단합니다. 병렬 처리 수준이 낮은 호스트에서 한 레인이 유효 가중치/리소스 상한을 초과하더라도 빈 풀에서 시작하여 용량을 해제할 때까지 단독으로 실행할 수 있습니다. 레인별 로그, summary.json, failures.json, 단계별 소요 시간은 .artifacts/docker-tests/<run-id>/ 아래에 기록됩니다. 느린 레인을 검사하려면 pnpm test:docker:timings <summary.json>을 사용하고, 비용이 적게 드는 대상별 재실행 명령을 출력하려면 pnpm test:docker:rerun <run-id|summary.json|failures.json>를 사용하십시오.

주요 Docker 레인

로컬 PR 게이트

로컬 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

테스트 성능 도구

• 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).
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: 모든 전체 스위트 Vitest 리프 구성을 직렬로 실행하고, 그룹화된 소요 시간 데이터와 구성별 JSON/로그 아티팩트를 기록합니다. 전체 스위트 보고서는 기본적으로 파일을 격리하므로 이전 파일에서 유지된 모듈 그래프와 GC 일시 중지 시간이 이후 어설션에 부과되지 않습니다. 공유 워커 누적을 의도적으로 프로파일링하는 경우에만 -- --no-isolate를 전달하십시오. 테스트 성능 에이전트는 느린 테스트 수정을 시도하기 전에 이를 기준선으로 사용합니다. pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json은 성능 중심 변경 후 그룹화된 보고서를 비교합니다.
• 전체, 확장 및 포함 패턴 샤드 실행은 .artifacts/vitest-shard-timings.json의 로컬 타이밍 데이터를 업데이트하며, 이후 전체 구성 실행에서는 해당 타이밍을 사용하여 느린 샤드와 빠른 샤드의 균형을 맞춥니다. 포함 패턴 CI 샤드는 타이밍 키에 샤드 이름을 추가하므로 전체 구성 타이밍 데이터를 대체하지 않고 필터링된 샤드 타이밍을 계속 표시할 수 있습니다. 로컬 타이밍 아티팩트를 무시하려면 OPENCLAW_TEST_PROJECTS_TIMINGS=0을 설정하십시오.

벤치마크

pnpm tsx scripts/bench-model.ts --runs 10

pnpm test:startup:benchpnpm test:startup:bench:smokepnpm test:startup:bench:savepnpm test:startup:bench:updatepnpm test:startup:bench:checkpnpm tsx scripts/bench-cli-startup.ts --runs 12pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all

pnpm test:startup:gateway -- --runs 5 --warmup 1pnpm test:startup:gateway -- --case skipChannels --case fiftyPlugins --runs 5node --import tsx scripts/bench-gateway-startup.ts --case default --runs 5 --output .artifacts/gateway-startup.json

pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5pnpm test:restart:gateway -- --case default --runs 3 --restarts 3 --warmup 1

온보딩 E2E(Docker)

선택 사항이며 컨테이너화된 온보딩 스모크 테스트에만 필요합니다. 깨끗한 Linux 컨테이너에서 전체 콜드 스타트 흐름을 실행합니다.

scripts/e2e/onboard-docker.sh

의사 TTY를 통해 대화형 마법사를 구동하고 구성/작업 공간/세션 파일을 검증한 다음, Gateway를 시작하고 openclaw health을 실행합니다.

QR 가져오기 스모크(Docker)

유지 관리되는 QR 런타임 헬퍼가 지원되는 Docker Node 런타임에서 로드되는지 확인합니다(Node 24가 기본값이며 Node 22와 호환됨).

pnpm test:docker:qr

관련 항목

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