Blacksmith Testbox은(는) 무엇을 하나요?
범위
로컬 머신에서 비용 효율적으로 제공할 수 없는 원격 CI 패리티, 주입된 시크릿, 호스팅 서비스 또는 OS/런타임 이미지가 필요할 때 Testbox를 사용하세요.
OpenClaw의 경우, Blacksmith를 사용할 수 없거나 자체 클라우드 용량이 선호될 때 Crabbox가 지원되는 대안입니다.
모든 로컬 테스트/빌드 루프에 Testbox를 기본으로 사용하지 마십시오. 저장소에 일반적인 반복 작업을 위한 문서화된 로컬 명령어가 있다면, 웜 캐시(warm cache), 로컬 빌드 상태를 유지하고 빠른 피드백을 위해 먼저 해당 명령어를 사용하세요.
Testbox는 비용이 많이 드는 경로입니다. 의도적으로 사용하세요.
OpenClaw 유지보수자는 환경 변수나 상시 에이전트 규칙에 OPENCLAW_TESTBOX=1을 설정하여 Testbox 우선 검증 모드를 선택할 수 있습니다. 이 모드는 유지보수자 전용이며 Blacksmith 접근 권한이 필요합니다.
OpenClaw에서 OPENCLAW_TESTBOX=1이 설정된 경우:
- 더 길거나 광범위하거나 불확실한 작업의 시작 부분에서 Testbox를 미리 워밍업하세요.
pnpm게이트(gate), e2e, 패키지형 증명, 광범위한 테스트 스위트에 대해 Testbox를 선호하세요.- 동일한 작업/세션 내의 모든
run명령어에 대해 동일한 Testbox ID를 재사용하세요. - 작업이 명시적으로
OPENCLAW_LOCAL_CHECK_MODE=throttled|full을 설정하거나 사용자가 로컬 증명을 요청하는 경우에만 로컬 명령어를 사용하세요.
CLI 설치
blacksmith가 설치되어 있지 않으면 설치하세요:
curl -fsSL https://get.blacksmith.sh | sh
Canary 채널(최첨단)의 경우:
BLACKSMITH_CHANNEL=canary sh -c 'curl -fsSL https://get.blacksmith.sh | sh'
그런 다음 인증하세요:
blacksmith auth login
에이전트 트리거 브라우저 인증(비대화형)
에이전트가 testbox 명령어(예: warmup, run)를 실행하기 전에 사용자가 인증되었는지 확인해야 할 때, 비대화형 모드로 브라우저 기반 인증을 사용하세요. 이는 사용자가 로그인할 수 있도록 브라우저를 열지만, 에이전트는 브라우저와 상호작용하지 않습니다. 대시보드의 조직 선택기는 건너뛰어지므로 사용자는 로그인 화면만 볼 수 있습니다.
필수 명령어 (--organization은 --non-interactive와 함께 필수입니다):
blacksmith auth login --non-interactive --organization <org-slug>
조직 슬러그(org slug)는 BLACKSMITH_ORG 환경 변수나 --org 전역 플래그에서 가져올 수 있습니다. 둘 다 설정되지 않은 경우, 에이전트는 프로젝트의 알려진 조직(예: 저장소 구성 또는 사용자 컨텍스트에서)을 사용해야 합니다. 예시:
blacksmith auth login --non-interactive --organization acme-corp
blacksmith --org acme-corp auth login --non-interactive --organization acme-corp
흐름: CLI가 로컬 콜백 서버를 시작하고, 대시보드 인증 페이지로 브라우저를 열며, 최대 2분 동안 차단됩니다. 사용자는 브라우저에서 로그인 및 권한 부여를 완료합니다. 대시보드가 localhost로 토큰과 함께 리디렉션합니다. CLI가 자격 증명을 저장하고 종료합니다. 그런 다음 에이전트가 진행합니다.
이 흐름에는 --api-token을 사용하지 마십시오. 이는 헤드리스/토큰 기반 인증을 위한 것입니다. 이 스킬은 사용자가 웹 UI를 통해 로그인하는 것을 선호할 때 브라우저 기반 인증에 중점을 둡니다.
선택적 플래그:
--dashboard-url <url>— 대시보드 URL 재정의(예: 스테이징 환경)
먼저 결정: 로컬 또는 Testbox
무엇이든 워밍업하기 전에 저장소 자체의 지침을 확인하세요.
다음과 같은 경우 로컬 명령어를 선호하세요:
- 저장소가 지원되는 로컬 테스트/빌드 워크플로우를 문서화한 경우
- 단위 테스트, 린트, 타입체크, 포맷팅 또는 기타 로컬 전용 검증을 반복하는 경우
- 웜 로컬 캐시와 빠른 반복 실행에서 가치를 얻는 경우
- 명령어에 원격 시크릿, 호스팅 서비스 또는 CI 전용 이미지가 필요하지 않은 경우
다음과 같은 경우 Testbox를 선호하세요:
- 저장소가 명시적으로 CI 패리티 또는 원격 검증을 요구하는 경우
- 명령어에 시크릿, 서비스 컨테이너 또는 프로비저닝된 인프라가 필요한 경우
- CI 전용 실패를 재현하는 경우
- GitHub Actions에서 정확한 워크플로우 이미지/작업 환경이 필요한 경우
특히 OpenClaw의 경우, 유지보수자 Testbox 모드가 OPENCLAW_TESTBOX=1로 활성화되지 않는 한 일반적인 로컬 반복 작업은 로컬로 유지됩니다:
pnpm check:changedpnpm test:changedpnpm test <path-or-filter>pnpm test:serialpnpm build
OPENCLAW_TESTBOX=1이 활성화된 경우, 웜 Testbox 내에서 동일한 저장소 명령어를 실행하세요. 사용자가 하나의 명령어에 대해 노트북 친화적인 로컬 증명을 원하는 경우, 명시적 이스케이프 해치 OPENCLAW_LOCAL_CHECK_MODE=throttled를 사용하세요.
설치 가능한 패키지 제품 증명의 경우, 임시 Testbox 명령어보다 GitHub Package Acceptance 워크플로우를 선호하세요. 이 워크플로우는 하나의 패키지 후보(source=npm, source=ref, source=url 또는 source=artifact)를 확인하고, 이를 package-under-test로 업로드한 후, GitHub/Blacksmith 러너에서 해당 정확한 tarball에 대해 재사용 가능한 Docker E2E 레인을 실행합니다. 신뢰할 수 있는 워크플로우/하네스 코드에는 workflow_ref를 사용하고, 이전의 신뢰할 수 있는 브랜치, 태그 또는 SHA를 테스트할 때 패키징할 소스 ref에는 package_ref를 사용하세요.
설정: 코딩 전 워밍업
Testbox가 필요하다고 결정했다면, 일찍 워밍업하세요. 그러면 즉시 ID가 반환되고 사용자가 작업하는 동안 백그라운드에서 CI 환경이 부팅됩니다:
blacksmith testbox warmup ci-check-testbox.yml
# → tbx_01jkz5b3t9...
이 ID를 현재 세션에 저장하세요. 모든 run 명령어에 필요합니다. blacksmith testbox list는 진단 용도로 취급하고, 재사용 가능한 작업 큐로 취급하지 마세요. 나열된 박스는 조직/저장소 수준에서 볼 수 있지만, 현재 로컬 에이전트 레인에서는 사용할 수 없거나 오래된 상태일 수 있습니다.
OpenClaw 유지보수자 Testbox 모드의 경우, 더 길거나 광범위한 작업 시작 시 미리 워밍업하세요:
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
pnpm testbox:claim --id <ID>
e2e/패키지/빌드 증명이 시딩된 dist/, dist-runtime/ 및 빌드-올 캐시의 이점을 얻는 경우 빌드 아티팩트 워밍업을 사용하세요:
blacksmith testbox warmup ci-build-artifacts-testbox.yml --ref main --idle-timeout 90
pnpm testbox:claim --id <ID>
워밍업은 전체 CI 환경(의존성 설치, 서비스 시작, 시크릿 주입, 기본 브랜치의 저장소 클린 체크아웃)으로 VM을 프로비저닝하는 GitHub Actions 워크플로우를 시작합니다.
OpenClaw에서, 원시 커밋 SHA는 warmup --ref에 신뢰할 수 있는 디스패치 ref가 아닙니다. 브랜치 또는 태그를 사용하세요. 빌드-아티팩트 워크플로우는 내부적으로 openclaw@beta 및 openclaw@latest를 SHA 캐시 키로 확인합니다.
옵션:
--ref <branch|tag> Git ref (기본값: 저장소의 기본 브랜치)
--job <name> 워크플로우 내 특정 작업 (여러 작업이 있는 경우)
--idle-timeout <min> 유휴 시간 제한 (분, 기본값: 30)
중요: 항상 저장소 루트에서 실행
항상 git 저장소의 루트에서 blacksmith testbox 명령어를 호출하세요. CLI는 현재 작업 디렉토리를 rsync(--delete 사용)를 통해 testbox에 동기화합니다. 서브디렉토리에서 실행하면(예: cd backend && blacksmith testbox run ...), rsync는 해당 서브디렉토리만 미러링하고 testbox의 다른 모든 항목을 삭제합니다 — dashboard/, cli/ 등 다른 디렉토리를 지웁니다.
# 올바름 — 저장소 루트에서 실행하고 명령어에 경로 사용
blacksmith testbox run --id <ID> "cd backend && php artisan test"
blacksmith testbox run --id <ID> "cd dashboard && npm test"
# 잘못됨 — CLI를 호출하기 전에 서브디렉토리로 cd하지 마십시오
cd backend && blacksmith testbox run --id <ID> "php artisan test"
셸이 서브디렉토리에 있는 경우, 먼저 저장소 루트로 cd하세요:
cd "$(git rev-parse --show-toplevel)"
blacksmith testbox run --id <ID> "cd backend && php artisan test"
명령어 실행
blacksmith testbox run --id <ID> "<command>"
run 명령어는 testbox가 여전히 부팅 중인 경우 자동으로 준비될 때까지 기다리므로, 워밍업 직후 상태를 확인할 필요 없이 run을 호출할 수 있습니다.
OpenClaw에서는, 오래되었거나 재사용된 ID가 Blacksmith CLI가 동기화에 시간을 소비하거나 혼란스러운 키 없음 오류를 발생시키기 전에 실패하도록 보호된 러너 래퍼를 선호하세요:
pnpm testbox:run --id <ID> -- "OPENCLAW_TESTBOX=1 pnpm check:changed"
래퍼는 로컬 Testbox별 키가 없거나 ID가 pnpm testbox:claim --id <ID>로 이 OpenClaw 체크아웃에 의해 클레임되지 않은 경우 실행을 거부합니다. 이를 예상된 해결 방법으로 취급하고, GitHub 계정이나 일반 SSH 키 문제로 취급하지 마세요. 로컬 키만으로는 충분하지 않습니다. 준비된 박스라도 다른 레인의 오래된 rsync 상태를 가지고 있을 수 있습니다.
에이전트가 충돌하면, 원격 박스는 Blacksmith의 유휴 시간 제한에 의존합니다. 로컬 OpenClaw 클레임 마커는 자동으로 삭제되지 않으므로, 래퍼는 12시간보다 오래된 클레임을 오래된 것으로 취급합니다. 의도적인 장기 실행 작업에만 OPENCLAW_TESTBOX_CLAIM_TTL_MINUTES=<minutes>로 재정의하세요.
광범위한 게이트 전에 수동으로 조합된 명령어를 실행하기 전에 다음을 실행할 수도 있습니다:
pnpm testbox:sanity -- --id <ID>
Testbox에서 파일 다운로드
download 명령어를 사용하여 실행 중인 testbox에서 로컬 머신으로 파일이나 디렉토리를 검색하세요. 이는 빌드 아티팩트, 테스트 결과, 커버리지 보고서 또는 testbox에서 생성된 모든 출력을 가져오는 데 유용합니다.
blacksmith testbox download --id <ID> <remote-path> [local-path]
원격 경로는 testbox 작업 디렉토리(run과 동일)를 기준으로 합니다. 로컬 경로가 지정되지 않으면 파일은 동일한 기본 이름을 사용하여 현재 디렉토리에 저장됩니다.
디렉토리를 다운로드하려면 원격 경로에 후행 /를 추가하세요. 그러면 재귀 모드가 트리거됩니다:
# 단일 파일 다운로드
blacksmith testbox download --id <ID> coverage/report.html
# 특정 로컬 경로로 파일 다운로드
blacksmith testbox download --id <ID> build/output.tar.gz ./output.tar.gz
# 전체 디렉토리 다운로드
blacksmith testbox download --id <ID> test-results/ ./results/
옵션:
--ssh-private-key <path> SSH 개인 키 경로 (워밍업이 --ssh-public-key를 사용한 경우)
파일 동기화 작동 방식
이 모델을 이해하는 것은 Testbox를 올바르게 사용하는 데 중요합니다.
run을 호출하면 CLI는 명령어를 실행하기 전에 로컬 변경 사항을 원격 testbox에 델타 동기화(delta sync) 수행합니다:
-
testbox VM은 워밍업 ref에서 클린
actions/checkout으로 시작합니다. 워크플로우의 설정 단계(예:npm install,pip install,composer install)는 워밍업 중에 실행되어 원격 VM에 의존성 디렉토리를 채웁니다. -
각
run시, CLI는 git을 사용하여 마지막 동기화 이후 로컬에서 변경된 파일을 감지합니다. 추적된 파일(tracked files)과 추적되지 않았지만 무시되지 않은 파일(즉,git ls-files가 보고하는 파일)만 동기화합니다. -
.gitignore에 지정된 디렉토리는 절대 동기화되지 않습니다. 즉,node_modules/,vendor/,.venv/,build/,dist/등과 같은 디렉토리는 로컬 머신에서 전송되지 않습니다. testbox는 워밍업 워크플로우 단계에서 채워진 자체 복사본을 사용합니다. -
마지막 동기화 이후 변경된 사항이 없으면(동일한 git 커밋 및 작업 트리 상태), 속도를 위해 동기화가 완전히 건너뜁니다.
이것이 중요한 이유
-
의존성 변경:
package.json,requirements.txt,composer.json,go.mod또는 유사한 의존성 매니페스트를 수정하면, lock/매니페스트 파일은 동기화되지만 실제 의존성 디렉토리는 동기화되지 않습니다. testbox에서 설치 명령어를 다시 실행해야 합니다:blacksmith testbox run --id <ID> "npm install && npm test" blacksmith testbox run --id <ID> "pip install -r requirements.txt && pytest" blacksmith testbox run --id <ID> "composer install && phpunit" -
생성/빌드 아티팩트: 테스트가 빌드 단계(예:
npm run build,make)에 의존하고 빌드 출력에 영향을 미치는 소스 파일을 변경한 경우, 테스트 전에 testbox에서 빌드를 다시 실행하세요. -
새로운 추적되지 않은 파일: 로컬에서 생성한 새 파일은 동기화됩니다(git에서 무시되지 않는 한). 먼저
git add할 필요가 없습니다. -
삭제된 파일: 로컬에서 삭제한 파일은 원격 testbox에서도 삭제됩니다. 동기화 모델은 원격을 로컬 관리 파일 세트와 일치하도록 유지합니다.
중요: 로컬 테스트 금지 금지
로컬 검증이 금지되었다고 가정하지 마십시오. 많은 저장소가 의도적으로 빠르고 웜한 로컬 루프에 투자하며, 모든 실행을 Testbox를 통해 강제하면 이 이점이 사라집니다.
실제로 필요한 검사(원격 패리티, 시크릿, 서비스, CI 전용 러너 또는 워크플로우 이미지에 대한 재현성)에만 Testbox를 사용하세요.
저장소에서 로컬 테스트/빌드가 일반적인 경로라고 명시하면, 저장소를 따르세요.
OpenClaw 유지보수자 예외: 사용자 또는 에이전트 환경에서 OPENCLAW_TESTBOX=1이 설정된 경우, 이 저장소의 일반적인 검증 경로로 Testbox를 취급하세요. 명시적인 로컬 이스케이프 해치로 OPENCLAW_LOCAL_CHECK_MODE=throttled|full을 사용하세요.
사용 시기
다음과 같은 경우 Testbox를 사용하세요:
- 데이터베이스 마이그레이션 또는 파괴적인 환경 검사를 실행할 때
- 로컬에 없는 시크릿 또는 환경 변수에 의존하는 명령어를 실행할 때
- CI 전용 실패를 재현하거나 워크플로우 이미지에 대해 검증할 때
- 프로비저닝된 서비스 또는 원격 러너가 필요한 동작을 검증할 때
- 저장소나 사용자가 원할 때 커밋/푸시 전 최종 패리티 검사를 수행할 때
저장소 지침에 따라 목록을 조정하세요. 저장소가 지원되는 로컬 테스트/빌드를 문서화한 경우, 일상적인 반복 작업에는 로컬을 선호하고 패리티나 원격 상태가 필요한 검사에만 Testbox를 사용하세요.
워크플로우
- 저장소의 로컬 루프가 올바른 기본값인지 결정하세요. OpenClaw의 경우,
OPENCLAW_TESTBOX=1이 Testbox를 유지보수자 기본값으로 만듭니다. - Testbox가 필요하다면, 일찍 워밍업하세요:
blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90→ ID 저장, 그 다음pnpm testbox:claim --id <ID> - testbox가 백그라운드에서 부팅되는 동안 코드를 작성하세요.
- 필요할 때 원격 명령어를 실행하세요:
pnpm testbox:run --id <ID> -- "OPENCLAW_TESTBOX=1 pnpm check:changed" - 테스트가 실패하면 코드를 수정하고 동일한 웜 박스에 대해 다시 실행하세요.
- 의존성 매니페스트(package.json 등)를 변경했다면 설치 명령어를 앞에 추가하세요:
blacksmith testbox run --id <ID> "npm install && npm test" - 좁은 PR이 전체 동기화를 보고하거나 박스가 재사용/만료된 경우, 느린 게이트 전에 원격 복사본을 sanity 확인하세요:
pnpm testbox:run --id <ID> -- "pnpm testbox:sanity". 루트 파일 누락이나 대량 추적 파일 삭제가 보고되면 박스를 중지하고 새 것으로 워밍업하세요. 의도적인 장기 실행 작업이나 브랜치 전환에만OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1을 사용하세요.