blacksmith-testbox

Blacksmith Testbox

Escopo

Use o Testbox quando você precisar de paridade de CI remota, segredos injetados, serviços hospedados, ou uma imagem de SO/runtime que sua máquina local não pode fornecer de forma econômica.

Para o OpenClaw, o Crabbox é uma alternativa suportada quando o Blacksmith não estiver disponível ou a capacidade de nuvem gerenciada for preferível.

Não use o Testbox como padrão para todo loop local de teste/build. Se o repositório tiver comandos locais documentados para iteração normal, use-os primeiro para manter caches aquecidos, estado de build local e feedback rápido.

O Testbox é o caminho caro. Use-o com intenção.

Mantenedores do OpenClaw podem optar pela validação prioritária via Testbox definindo OPENCLAW_TESTBOX=1 em seu ambiente ou em regras de agente fixas. Este modo é apenas para mantenedores e requer acesso ao Blacksmith.

Quando OPENCLAW_TESTBOX=1 estiver definido no OpenClaw:

• Pré-aqueça um Testbox cedo para trabalhos mais longos, amplos ou incertos.
• Prefira o Testbox para verificações pnpm, e2e, prova de pacotes e suítes amplas.
• Reutilize o mesmo ID de Testbox para cada comando run na mesma tarefa/sessão.
• Use comandos locais apenas quando a tarefa definir explicitamente OPENCLAW_LOCAL_CHECK_MODE=throttled|full, ou quando o usuário solicitar prova local.

Instalar o CLI

Se blacksmith não estiver instalado, instale-o:

curl -fsSL https://get.blacksmith.sh | sh

Para o canal canary (versão bleeding-edge):

BLACKSMITH_CHANNEL=canary sh -c 'curl -fsSL https://get.blacksmith.sh | sh'

Em seguida, autentique-se:

blacksmith auth login

Autenticação via navegador acionada por agente (não interativa)

Quando um agente precisar garantir que o usuário esteja autenticado antes de executar comandos do testbox (ex: warmup, run), use autenticação baseada em navegador com modo não interativo. Isso abre o navegador para o usuário fazer login; o agente não interage com o navegador. O seletor de organização no painel é ignorado, então o usuário vê apenas o fluxo de login.

Comando obrigatório (--organization é obrigatório com --non-interactive):

blacksmith auth login --non-interactive --organization <org-slug>

O slug da organização pode vir da variável de ambiente BLACKSMITH_ORG ou da flag global --org. Se nenhum estiver definido, o agente deve usar a organização conhecida do projeto (ex: da configuração do repositório ou contexto do usuário). Exemplo:

blacksmith auth login --non-interactive --organization acme-corp
blacksmith --org acme-corp auth login --non-interactive --organization acme-corp

Fluxo: O CLI inicia um servidor de callback local, abre o navegador para a página de autenticação do painel e bloqueia por até 2 minutos. O usuário conclui o login e autorização no navegador. O painel redireciona para localhost com o token; o CLI salva as credenciais e sai. O agente então prossegue.

Não use --api-token para este fluxo — isso é para autenticação headless/baseada em token. Esta skill foca na autenticação baseada em navegador quando o usuário prefere fazer login via interface web.

Flags opcionais:

• --dashboard-url <url> — Substitui a URL do painel (ex: para staging)

Decida primeiro: local ou Testbox

Antes de aquecer qualquer coisa, verifique as próprias instruções do repositório.

Prefira comandos locais quando:

• o repositório documenta um fluxo de trabalho local suportado de teste/build
• você está iterando em testes unitários, lint, typecheck, formatação ou outras validações exclusivamente locais
• o valor vem de caches locais aquecidos e execuções repetidas rápidas
• o comando não precisa de segredos remotos, serviços hospedados ou imagens exclusivas de CI

Prefira o Testbox quando:

• o repositório exige explicitamente paridade de CI ou validação remota
• o comando precisa de segredos, contêineres de serviço ou infraestrutura provisionada
• você está reproduzindo falhas exclusivas de CI
• você precisa da imagem de fluxo de trabalho/ambiente de tarefa exata do GitHub Actions

Para o OpenClaw especificamente, a iteração local normal permanece local a menos que o modo Testbox de mantenedor esteja ativado com OPENCLAW_TESTBOX=1:

• pnpm check:changed
• pnpm test:changed
• pnpm test <caminho-ou-filtro>
• pnpm test:serial
• pnpm build

Se OPENCLAW_TESTBOX=1 estiver ativado, execute esses mesmos comandos do repositório dentro do Testbox aquecido. Se o usuário quiser prova local amigável ao notebook para um comando, use a saída de escape explícita OPENCLAW_LOCAL_CHECK_MODE=throttled.

Para prova de produto de pacote instalável, prefira o fluxo de trabalho Package Acceptance do GitHub em vez de um comando ad hoc do Testbox. Ele resolve um candidato a pacote (source=npm, source=ref, source=url ou source=artifact), faz upload dele como package-under-test e executa as pistas reutilizáveis de Docker E2E nesse tarball exato nos runners GitHub/Blacksmith. Use workflow_ref para o código confiável de fluxo de trabalho/harness e package_ref para a ref de origem a ser empacotada ao testar um branch, tag ou SHA mais antigo e confiável.

Configuração: Aquecimento antes de codificar

Se você decidiu que o Testbox é justificado, aqueça um cedo. Isso retorna um ID instantaneamente e inicia o ambiente de CI em segundo plano enquanto você trabalha:

blacksmith testbox warmup ci-check-testbox.yml
# → tbx_01jkz5b3t9...

Salve este ID na sessão atual. Você precisa dele para cada comando run. Trate blacksmith testbox list como diagnóstico, não como uma fila de trabalho reutilizável. Caixas listadas podem estar visíveis no nível da organização/repositório enquanto ainda são inutilizáveis ou desatualizadas para a pista do agente local atual.

Para o modo Testbox de mantenedor do OpenClaw, pré-aqueça no início de tarefas mais longas ou amplas:

blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90
pnpm testbox:claim --id <ID>

Use o aquecimento de artefatos de build quando provas e2e/pacote/build se beneficiarem de caches dist/, dist-runtime/ e build-all propagados:

blacksmith testbox warmup ci-build-artifacts-testbox.yml --ref main --idle-timeout 90
pnpm testbox:claim --id <ID>

O aquecimento despacha um fluxo de trabalho do GitHub Actions que provisiona uma VM com o ambiente de CI completo: dependências instaladas, serviços iniciados, segredos injetados e um checkout limpo do repositório no branch padrão.

No OpenClaw, SHAs de commit brutos não são refs de despacho confiáveis para warmup --ref; use um branch ou tag. O fluxo de trabalho de artefatos de build resolve openclaw@beta e openclaw@latest para chaves de cache SHA internamente.

Opções:

--ref <branch|tag>     Ref Git para despachar (padrão: branch padrão do repositório)
--job <nome>           Tarefa específica dentro do fluxo de trabalho (se houver múltiplas)
--idle-timeout <min>   Tempo limite de inatividade em minutos (padrão: 30)

CRÍTICO: Sempre execute a partir da raiz do repositório

SEMPRE invoque comandos blacksmith testbox a partir da raiz do repositório git. O CLI sincroniza o diretório de trabalho atual para o testbox usando rsync com --delete. Se você executar a partir de um subdiretório (ex: cd backend && blacksmith testbox run ...), o rsync espelhará apenas aquele subdiretório e excluirá todo o resto no testbox — apagando outros diretórios como dashboard/, cli/, etc.

# CORRETO — execute da raiz do repositório, use caminhos no comando
blacksmith testbox run --id <ID> "cd backend && php artisan test"
blacksmith testbox run --id <ID> "cd dashboard && npm test"

# ERRADO — NÃO use cd em um subdiretório antes de invocar o CLI
cd backend && blacksmith testbox run --id <ID> "php artisan test"

Se seu shell estiver em um subdiretório, volte para a raiz do repositório primeiro:

cd "$(git rev-parse --show-toplevel)"
blacksmith testbox run --id <ID> "cd backend && php artisan test"

Executando comandos

blacksmith testbox run --id <ID> "<comando>"

O comando run automaticamente espera o testbox ficar pronto se ainda estiver inicializando, então você pode chamar run imediatamente após o aquecimento sem precisar verificar o status primeiro.

No OpenClaw, prefira o wrapper de executor protegido para que IDs obsoletos/reutilizados falhem antes do CLI do Blacksmith gastar tempo sincronizando ou emitir um erro confuso de chave ausente:

pnpm testbox:run --id <ID> -- "OPENCLAW_TESTBOX=1 pnpm check:changed"

O wrapper se recusa a executar quando a chave local por Testbox está ausente ou quando o ID não foi reivindicado por este checkout do OpenClaw com pnpm testbox:claim --id <ID>. Trate isso como a remediação esperada, não como um problema de conta GitHub ou chave SSH normal. Uma chave local sozinha não é suficiente; uma caixa pronta pode ainda carregar estado rsync obsoleto de outra pista.

Se o agente travar, a caixa remota depende do tempo limite de inatividade do Blacksmith. O marcador de reivindicação local do OpenClaw não é excluído automaticamente, então o wrapper trata reivindicações com mais de 12 horas como obsoletas. Substitua apenas para trabalho intencional de longa duração com OPENCLAW_TESTBOX_CLAIM_TTL_MINUTES=<minutos>.

Antes de gastar uma verificação ampla em um comando montado manualmente, você também pode executar:

pnpm testbox:sanity -- --id <ID>

Baixando arquivos de um testbox

Use o comando download para recuperar arquivos ou diretórios de um testbox em execução para sua máquina local. Isso é útil para buscar artefatos de build, resultados de teste, relatórios de cobertura ou qualquer saída gerada no testbox.

blacksmith testbox download --id <ID> <caminho-remoto> [caminho-local]

O caminho remoto é relativo ao diretório de trabalho do testbox (igual ao run). Se nenhum caminho local for especificado, o arquivo é salvo no diretório atual usando o mesmo nome base.

Para baixar um diretório, anexe um / final ao caminho remoto — isso dispara o modo recursivo:

# Baixar um único arquivo
blacksmith testbox download --id <ID> coverage/report.html

# Baixar um arquivo para um caminho local específico
blacksmith testbox download --id <ID> build/output.tar.gz ./output.tar.gz

# Baixar um diretório inteiro
blacksmith testbox download --id <ID> test-results/ ./results/

Opções:

--ssh-private-key <caminho>   Caminho para a chave privada SSH (se o warmup usou --ssh-public-key)

Como funciona a sincronização de arquivos

Entender este modelo é crítico para usar o Testbox corretamente.

Quando você chama run, o CLI realiza uma sincronização delta das suas alterações locais para o testbox remoto antes de executar seu comando:

1. A VM do testbox inicia a partir de um actions/checkout limpo na ref de aquecimento. As etapas de configuração do fluxo de trabalho (ex: npm install, pip install, composer install) são executadas durante o aquecimento e preenchem diretórios de dependências na VM remota.

2. Em cada run, o CLI usa git para detectar quais arquivos mudaram localmente desde a última sincronização. Ele sincroniza APENAS arquivos rastreados e arquivos não rastreados não ignorados (ou seja, arquivos que git ls-files relata).

3. Diretórios em .gitignore nunca são sincronizados. Isso significa que diretórios como node_modules/, vendor/, .venv/, build/, dist/, etc. NÃO são transferidos da sua máquina local. O testbox usa suas próprias cópias desses diretórios, preenchidas durante as etapas do fluxo de trabalho de aquecimento.

4. Se nada mudou desde a última sincronização (mesmo commit git e estado da árvore de trabalho), a sincronização é completamente ignorada por velocidade.

Por que isso importa

• Alterando dependências: Se você modificar package.json, requirements.txt, composer.json, go.mod ou manifestos de dependência semelhantes, o arquivo de bloqueio/manifesto será sincronizado, mas o diretório de dependências real NÃO será. Você deve reexecutar o comando de instalação no 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"
  

• Artefatos gerados/build: Se seus testes dependem de uma etapa de build (ex: npm run build, make) e você alterou arquivos fonte que afetam a saída do build, reexecute o build no testbox antes de testar.

• Novos arquivos não rastreados: Novos arquivos que você criar localmente SÃO sincronizados (desde que não estejam no gitignore). Você não precisa git add eles primeiro.

• Arquivos excluídos: Arquivos que você excluir localmente também são excluídos no testbox remoto. O modelo de sincronização mantém o remoto em sintonia com seu conjunto de arquivos gerenciados local.

CRÍTICO: Não proíba testes locais

Não presuma que a validação local é proibida. Muitos repositórios investem intencionalmente em loops locais rápidos e aquecidos, e forçar cada execução através do Testbox destrói essa vantagem.

Use o Testbox para as verificações que realmente precisam dele: paridade remota, segredos, serviços, runners exclusivos de CI ou reprodutibilidade contra a imagem do fluxo de trabalho.

Se o repositório disser que testes/builds locais são o caminho normal, siga o repositório.

Exceção para mantenedores do OpenClaw: se OPENCLAW_TESTBOX=1 for definido pelo usuário ou ambiente do agente, trate o Testbox como o caminho de validação normal para este repositório. Use OPENCLAW_LOCAL_CHECK_MODE=throttled|full como a saída de escape local explícita.

Quando usar

Use o Testbox quando:

• executando migrações de banco de dados ou verificações de ambiente destrutivas
• executando comandos que dependem de segredos ou variáveis de ambiente não presentes localmente
• reproduzindo falhas exclusivas de CI ou validando contra a imagem do fluxo de trabalho
• validando comportamento que precisa de serviços provisionados ou runners remotos
• fazendo uma verificação final de paridade antes de commit/push quando o repositório ou usuário deseja isso

Reduza essa lista com base na orientação do repositório. Se o repositório documentar testes/builds locais suportados, prefira local para iteração de rotina e mantenha o Testbox para as verificações que precisam de paridade ou estado remoto.

Fluxo de trabalho

1. Decida se o loop local do repositório é o padrão correto. Para o OpenClaw, OPENCLAW_TESTBOX=1 torna o Testbox o padrão do mantenedor.
2. Se o Testbox for justificado, aqueça cedo: blacksmith testbox warmup ci-check-testbox.yml --ref main --idle-timeout 90 → salve o ID, então pnpm testbox:claim --id <ID>
3. Escreva código enquanto o testbox inicializa em segundo plano.
4. Execute o comando remoto quando necessário: pnpm testbox:run --id <ID> -- "OPENCLAW_TESTBOX=1 pnpm check:changed"
5. Se os testes falharem, corrija o código e reexecute na mesma caixa aquecida.
6. Se você alterou manifestos de dependência (package.json, etc.), preceda o comando de instalação: blacksmith testbox run --id <ID> "npm install && npm test"
7. Se um PR estreito relatar uma sincronização completa ou a caixa foi reutilizada/expirada, verifique a sanidade da cópia remota antes de uma verificação lenta: pnpm testbox:run --id <ID> -- "pnpm testbox:sanity". Se ela relatar arquivos raiz ausentes ou exclusões em massa rastreadas, pare a caixa e aqueça uma nova. Use OPENCLAW_TESTBOX_ALLOW_MASS_DELETIONS=1 apenas para uma intenção