테스트

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

에이전트 기본값

에이전트 세션은 Crabbox를 통해 테스트와 계산 집약적인 검증을 원격으로 실행합니다. 신뢰할 수 있는 메인테이너 코드에는 기본적으로 Blacksmith Testbox를 사용합니다. 구성된 Testbox 워크플로는 자격 증명을 주입하므로, 신뢰할 수 없는 기여자 또는 포크 코드는 대신 시크릿이 없는 포크 CI나 정제된 직접 AWS Crabbox를 사용해야 합니다.

신뢰할 수 있는 코드 작업에 테스트나 고강도 검증이 필요할 가능성이 있다면, 백그라운드 명령 세션에서 즉시 미리 준비하고, 준비되는 동안 작업을 계속하며, 반환된 tbx_... ID를 재사용하고, 실행할 때마다 현재 체크아웃을 동기화한 뒤, 인계 전에 중지합니다.

node scripts/crabbox-wrapper.mjs warmup --provider blacksmith-testbox --keep --timing-json

처음으로 재사용에 성공하면 래퍼는 리스의 베이스, 의존성 및 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>.
• 변경 게이트 또는 광범위한 검증: 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가 연결 유지 액션 외부에서 중지되기 때문에 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 실행 구성 하나를 실행합니다.
• 형제 테스트가 있는 소스 파일은 더 넓은 디렉터리 글롭으로 대체하기 전에 해당 형제 테스트에 매핑됩니다. 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 타르볼로 한 번 패키징하며, 기본 Node/Git 실행기 이미지와 해당 타르볼을 /app에 설치하는 기능 이미지를 빌드하거나 재사용한 다음, 가중치 기반 스케줄러를 통해 Docker 스모크 실행 구성을 실행합니다. scripts/package-openclaw-for-docker.mjs는 유일한 로컬/CI 패키지 생성기이며, Docker가 사용하기 전에 타르볼과 dist/postinstall-inventory.json을 검증합니다.

• 기본 이미지(OPENCLAW_DOCKER_E2E_BARE_IMAGE): 설치 프로그램/업데이트/Plugin 의존성 실행 구성입니다. 복사된 저장소 소스 대신 미리 빌드된 타르볼을 마운트합니다.
• 기능 이미지(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 테스트