Testes

OpenClaw tem três suítes Vitest (unitária/integração, e2e, ao vivo) e um pequeno conjunto de executores Docker. Este documento é um guia de "como testamos":

• O que cada suíte cobre (e o que ela deliberadamente não cobre).
• Quais comandos executar para fluxos de trabalho comuns (local, pré-push, depuração).
• Como os testes ao vivo descobrem credenciais e selecionam modelos/provedores.
• Como adicionar regressões para problemas reais de modelo/provedor.

# Início rápido

Na maioria dos dias:

• Gate completo (esperado antes do push): pnpm build && pnpm check && pnpm check:test-types && pnpm test
• Execução mais rápida da suíte completa local em uma máquina espaçosa: pnpm test:max
• Loop direto de observação do Vitest: pnpm test:watch
• O direcionamento direto por arquivo agora também roteia caminhos de extensões/canais: pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts
• Prefira execuções direcionadas primeiro quando estiver iterando em uma única falha.
• Site de QA com respaldo Docker: pnpm qa:lab:up
• Lane de QA com respaldo de VM Linux: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

Quando você tocar em testes ou quiser confiança extra:

• Gate de cobertura: pnpm test:coverage
• Suíte E2E: pnpm test:e2e

Ao depurar provedores/modelos reais (requer credenciais reais):

• Suíte ao vivo (modelos + sondas de ferramenta/imagem do Gateway): pnpm test:live
• Direcione um arquivo ao vivo de forma silenciosa: pnpm test:live -- src/agents/models.profiles.live.test.ts
• Relatórios de desempenho em runtime: dispare OpenClaw Performance com live_gpt54=true para uma rodada real de agente openai/gpt-5.4 ou deep_profile=true para artefatos de CPU/heap/trace do Kova. Execuções diárias agendadas publicam artefatos de lanes de provedor mock, perfil profundo e GPT 5.4 em openclaw/clawgrit-reports quando CLAWGRIT_REPORTS_TOKEN está configurado. O relatório de provedor mock também inclui números em nível de código-fonte para inicialização do Gateway, memória, pressão de Plugins, loop repetido de saudação com modelo falso e inicialização da CLI.
• Varredura de modelos ao vivo Docker: pnpm test:docker:live-models
  • Cada modelo selecionado agora executa uma rodada de texto mais uma pequena sonda no estilo leitura de arquivo. Modelos cujos metadados anunciam entrada image também executam uma pequena rodada de imagem. Desative as sondas extras com OPENCLAW_LIVE_MODEL_FILE_PROBE=0 ou OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0 ao isolar falhas de provedor.
  • Cobertura de CI: OpenClaw Scheduled Live And E2E Checks diário e OpenClaw Release Checks manual chamam o fluxo de trabalho reutilizável ao vivo/E2E com include_live_suites: true, que inclui jobs separados da matriz de modelos ao vivo Docker fragmentados por provedor.
  • Para reexecuções de CI focadas, dispare OpenClaw Live And E2E Checks (Reusable) com include_live_suites: true e live_models_only: true.
  • Adicione novos segredos de provedor de alto sinal a scripts/ci-hydrate-live-auth.sh mais .github/workflows/openclaw-live-and-e2e-checks-reusable.yml e seus chamadores agendados/de release.
• Smoke de chat vinculado nativo do Codex: pnpm test:docker:live-codex-bind
  • Executa uma lane ao vivo Docker contra o caminho de app-server do Codex, vincula uma DM sintética do Slack com /codex bind, exercita /codex fast e /codex permissions, depois verifica uma resposta simples e que um anexo de imagem seja roteado pela vinculação nativa do Plugin em vez de ACP.
• Smoke do harness de app-server do Codex: pnpm test:docker:live-codex-harness
  • Executa rodadas de agente do Gateway pelo harness de app-server do Codex de propriedade do Plugin, verifica /codex status e /codex models e, por padrão, exercita sondas de imagem, MCP de cron, subagente e Guardian. Desative a sonda de subagente com OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0 ao isolar outras falhas de app-server do Codex. Para uma verificação focada de subagente, desative as outras sondas: OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0 OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=1 pnpm test:docker:live-codex-harness. Isso sai depois da sonda de subagente, a menos que OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0 esteja definido.
• Smoke do comando de resgate do Crestodian: pnpm test:live:crestodian-rescue-channel
  • Verificação opcional de dupla segurança para a superfície de comando de resgate do canal de mensagens. Ela exercita /crestodian status, enfileira uma alteração persistente de modelo, responde /crestodian yes e verifica o caminho de gravação de auditoria/configuração.
• Smoke Docker do planejador do Crestodian: pnpm test:docker:crestodian-planner
  • Executa o Crestodian em um contêiner sem configuração com uma CLI Claude falsa no PATH e verifica se o fallback do planejador fuzzy se traduz em uma gravação de configuração tipada auditada.
• Smoke Docker da primeira execução do Crestodian: pnpm test:docker:crestodian-first-run
  • Começa de um diretório de estado vazio do OpenClaw, roteia openclaw puro para o Crestodian, aplica gravações de configuração/modelo/agente/Plugin do Discord + SecretRef, valida a configuração e verifica entradas de auditoria. O mesmo caminho de configuração Ring 0 também é coberto no QA Lab por pnpm openclaw qa suite --scenario crestodian-ring-zero-setup.
• Smoke de custo Moonshot/Kimi: com MOONSHOT_API_KEY definido, execute openclaw models list --provider moonshot --json, depois execute um openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json isolado contra moonshot/kimi-k2.6. Verifique se o JSON informa Moonshot/K2.6 e se a transcrição do assistente armazena usage.cost normalizado.

# Executores específicos de QA

Estes comandos ficam ao lado das principais suítes de teste quando você precisa de realismo de QA Lab:

A CI executa QA Lab em fluxos de trabalho dedicados. A paridade agentic fica aninhada em QA-Lab - All Lanes e validação de release, não em um fluxo de trabalho de PR autônomo. Validações amplas devem usar Full Release Validation com rerun_group=qa-parity ou o grupo de QA de verificações de release. As verificações estáveis/padrão de release mantêm o soak exaustivo ao vivo/Docker atrás de run_release_soak=true; o perfil full força o soak. QA-Lab - All Lanes é executado todas as noites em main e por despacho manual com a lane de paridade mock, lane Matrix ao vivo, lane Telegram ao vivo gerenciada pelo Convex e lane Discord ao vivo gerenciada pelo Convex como jobs paralelos. QA agendado e verificações de release passam Matrix --profile fast explicitamente, enquanto a CLI Matrix e a entrada manual do fluxo de trabalho permanecem com padrão all; o despacho manual pode fragmentar all em jobs transport, media, e2ee-smoke, e2ee-deep e e2ee-cli. OpenClaw Release Checks executa paridade mais as lanes rápidas de Matrix e Telegram antes da aprovação de release, usando mock-openai/gpt-5.5 para verificações de transporte de release, para que elas permaneçam determinísticas e evitem a inicialização normal do Plugin de provedor. Esses Gateways de transporte ao vivo desativam a busca de memória; o comportamento de memória continua coberto pelas suítes de paridade de QA.

Os fragmentos de mídia ao vivo de release completo usam ghcr.io/openclaw/openclaw-live-media-runner:ubuntu-24.04, que já tem ffmpeg e ffprobe. Fragmentos Docker de modelos/backends ao vivo usam a imagem compartilhada ghcr.io/openclaw/openclaw-live-test:<sha> criada uma vez por commit selecionado, depois a puxam com OPENCLAW_SKIP_DOCKER_BUILD=1 em vez de reconstruir dentro de cada fragmento.

• pnpm openclaw qa suite
  • Executa cenários de QA baseados no repositório diretamente no host.
  • Executa vários cenários selecionados em paralelo por padrão com workers de gateway isolados. qa-channel usa concorrência 4 por padrão (limitada pela contagem de cenários selecionados). Use --concurrency <count> para ajustar a contagem de workers, ou --concurrency 1 para a lane serial anterior.
  • Sai com código diferente de zero quando qualquer cenário falha. Use --allow-failures quando você quiser artefatos sem um código de saída de falha.
  • Oferece suporte aos modos de provedor live-frontier, mock-openai e aimock. aimock inicia um servidor de provedor local baseado em AIMock para cobertura experimental de fixtures e mocks de protocolo sem substituir a lane mock-openai com reconhecimento de cenários.
• pnpm test:plugins:kitchen-sink-live
  • Executa o gauntlet do Plugin OpenAI Kitchen Sink ao vivo pelo QA Lab. Ele instala o pacote externo Kitchen Sink, verifica o inventário da superfície do SDK de Plugin, sonda /healthz e /readyz, registra evidências de CPU/RSS do gateway, executa um turno OpenAI ao vivo e verifica diagnósticos adversariais. Exige autenticação OpenAI ao vivo, como OPENAI_API_KEY. Em sessões Testbox hidratadas, ele carrega automaticamente o perfil de autenticação ao vivo do Testbox quando o helper openclaw-testbox-env está presente.
• pnpm test:gateway:cpu-scenarios
  • Executa o benchmark de inicialização do gateway mais um pequeno pacote de cenários mock do QA Lab (channel-chat-baseline, memory-failure-fallback, gateway-restart-inflight-run) e grava um resumo combinado de observação de CPU em .artifacts/gateway-cpu-scenarios/.
  • Sinaliza por padrão apenas observações sustentadas de CPU quente (--cpu-core-warn mais --hot-wall-warn-ms), então picos curtos de inicialização são registrados como métricas sem parecer a regressão de gateway travado por minutos.
  • Usa artefatos dist compilados; execute um build primeiro quando o checkout ainda não tiver uma saída de runtime atualizada.
• pnpm openclaw qa suite --runner multipass
  • Executa a mesma suíte de QA dentro de uma VM Linux Multipass descartável.
  • Mantém o mesmo comportamento de seleção de cenários que qa suite no host.
  • Reutiliza as mesmas flags de seleção de provedor/modelo que qa suite.
  • Execuções ao vivo encaminham as entradas de autenticação de QA compatíveis que são práticas para o guest: chaves de provedor baseadas em env, o caminho de configuração do provedor ao vivo de QA e CODEX_HOME quando presente.
  • Diretórios de saída devem permanecer sob a raiz do repositório para que o guest possa gravar de volta pelo workspace montado.
  • Grava o relatório + resumo normais de QA e os logs do Multipass em .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Inicia o site de QA baseado em Docker para trabalho de QA em estilo de operador.
• pnpm test:docker:npm-onboard-channel-agent
  • Cria um tarball npm a partir do checkout atual, instala-o globalmente no Docker, executa o onboarding não interativo com chave de API da OpenAI, configura Telegram por padrão, verifica que o runtime do Plugin empacotado carrega sem reparo de dependências na inicialização, executa doctor e executa um turno de agente local contra um endpoint OpenAI simulado.
  • Use OPENCLAW_NPM_ONBOARD_CHANNEL=discord para executar a mesma lane de instalação empacotada com Discord.
• pnpm test:docker:session-runtime-context
  • Executa um smoke Docker determinístico do app compilado para transcrições de contexto de runtime incorporado. Ele verifica que o contexto de runtime oculto do OpenClaw é persistido como uma mensagem customizada sem exibição em vez de vazar para o turno visível do usuário, então semeia um JSONL de sessão quebrada afetada e verifica que openclaw doctor --fix o reescreve para o branch ativo com um backup.
• pnpm test:docker:npm-telegram-live
  • Instala um candidato de pacote OpenClaw no Docker, executa onboarding de pacote instalado, configura Telegram pela CLI instalada e então reutiliza a lane de QA do Telegram ao vivo com esse pacote instalado como o Gateway SUT.
  • O padrão é OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta; defina OPENCLAW_NPM_TELEGRAM_PACKAGE_TGZ=/path/to/openclaw-current.tgz ou OPENCLAW_CURRENT_PACKAGE_TGZ para testar um tarball local resolvido em vez de instalar a partir do registro.
  • Usa as mesmas credenciais env do Telegram ou a fonte de credenciais Convex que pnpm openclaw qa telegram. Para automação de CI/release, defina OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex mais OPENCLAW_QA_CONVEX_SITE_URL e o segredo da função. Se OPENCLAW_QA_CONVEX_SITE_URL e um segredo de função Convex estiverem presentes no CI, o wrapper Docker seleciona Convex automaticamente.
  • O wrapper valida env de credenciais do Telegram ou Convex no host antes do trabalho de build/instalação do Docker. Defina OPENCLAW_NPM_TELEGRAM_SKIP_CREDENTIAL_PREFLIGHT=1 apenas ao depurar deliberadamente a configuração pré-credencial.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer substitui o OPENCLAW_QA_CREDENTIAL_ROLE compartilhado somente para esta lane.
  • GitHub Actions expõe esta lane como o workflow manual de mantenedor NPM Telegram Beta E2E. Ele não é executado no merge. O workflow usa o ambiente qa-live-shared e leases de credenciais Convex de CI.
• GitHub Actions também expõe Package Acceptance para prova de produto em execução lateral contra um pacote candidato. Ele aceita uma ref confiável, especificação npm publicada, URL HTTPS de tarball mais SHA-256, ou artefato de tarball de outra execução, faz upload do openclaw-current.tgz normalizado como package-under-test, então executa o agendador Docker E2E existente com perfis de lane smoke, pacote, produto, completo ou customizado. Defina telegram_mode=mock-openai ou live-frontier para executar o workflow de QA do Telegram contra o mesmo artefato package-under-test.
  • Prova de produto do beta mais recente:

gh workflow run package-acceptance.yml --ref main \
  -f source=npm \
  -f package_spec=openclaw@beta \
  -f suite_profile=product \
  -f telegram_mode=mock-openai

• Prova por URL exata de tarball exige um digest:

gh workflow run package-acceptance.yml --ref main \
  -f source=url \
  -f package_url=https://registry.npmjs.org/openclaw/-/openclaw-VERSION.tgz \
  -f package_sha256=<sha256> \
  -f suite_profile=package

• Prova por artefato baixa um artefato de tarball de outra execução do Actions:

gh workflow run package-acceptance.yml --ref main \
  -f source=artifact \
  -f artifact_run_id=<run-id> \
  -f artifact_name=<artifact-name> \
  -f suite_profile=smoke

• pnpm test:docker:plugins

  • Empacota e instala o build atual do OpenClaw no Docker, inicia o Gateway com OpenAI configurada e então habilita canais/plugins incluídos por meio de edições de config.
  • Verifica que a descoberta de setup deixa ausentes plugins baixáveis não configurados, que o primeiro reparo configurado do doctor instala explicitamente cada Plugin baixável ausente, e que uma segunda reinicialização não executa reparo oculto de dependências.
  • Também instala uma baseline npm antiga conhecida, habilita Telegram antes de executar openclaw update --tag <candidate> e verifica que o doctor pós-atualização do candidato limpa detritos de dependências legadas de Plugin sem um reparo postinstall do lado do harness.

• pnpm test:parallels:npm-update

  • Executa o smoke nativo de atualização de instalação empacotada entre guests Parallels. Cada plataforma selecionada primeiro instala o pacote baseline solicitado, depois executa o comando openclaw update instalado no mesmo guest e verifica a versão instalada, o status de atualização, a prontidão do gateway e um turno de agente local.

  • Use --platform macos, --platform windows ou --platform linux enquanto itera em um guest. Use --json para o caminho do artefato de resumo e o status por lane.

  • A lane OpenAI usa openai/gpt-5.5 para a prova de turno de agente ao vivo por padrão. Passe --model <provider/model> ou defina OPENCLAW_PARALLELS_OPENAI_MODEL ao validar deliberadamente outro modelo OpenAI.

  • Envolva execuções locais longas em um timeout do host para que travamentos de transporte do Parallels não consumam o restante da janela de testes:

    timeout --foreground 150m pnpm test:parallels:npm-update -- --json
    timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json
    

  • O script grava logs de lane aninhados em /tmp/openclaw-parallels-npm-update.*. Inspecione windows-update.log, macos-update.log ou linux-update.log antes de assumir que o wrapper externo travou.

  • A atualização do Windows pode passar de 10 a 15 minutos no doctor pós-atualização e no trabalho de atualização de pacote em um guest frio; isso ainda é saudável quando o log de depuração npm aninhado está avançando.

  • Não execute este wrapper agregado em paralelo com lanes smoke individuais do Parallels macOS, Windows ou Linux. Elas compartilham estado de VM e podem colidir na restauração de snapshot, no serviço de pacotes ou no estado do gateway do guest.

  • A prova pós-atualização executa a superfície normal de Plugin incluído porque facades de capacidade como fala, geração de imagem e entendimento de mídia são carregadas por APIs de runtime incluídas mesmo quando o turno do agente em si verifica apenas uma resposta de texto simples.

• pnpm openclaw qa aimock

  • Inicia somente o servidor de provedor AIMock local para testes smoke diretos de protocolo.

• pnpm openclaw qa matrix

  • Executa a lane de QA ao vivo do Matrix contra um homeserver Tuwunel descartável baseado em Docker. Somente checkout de origem - instalações empacotadas não distribuem qa-lab.
  • CLI completa, catálogo de perfis/cenários, env vars e layout de artefatos: QA do Matrix.

• pnpm openclaw qa telegram

  • Executa a lane de QA ao vivo do Telegram contra um grupo privado real usando os tokens do driver e do bot SUT vindos do env.
  • Exige OPENCLAW_QA_TELEGRAM_GROUP_ID, OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN e OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN. O id do grupo deve ser o id numérico do chat do Telegram.
  • Oferece suporte a --credential-source convex para credenciais compartilhadas em pool. Use o modo env por padrão, ou defina OPENCLAW_QA_CREDENTIAL_SOURCE=convex para optar por leases em pool.
  • Sai com código diferente de zero quando qualquer cenário falha. Use --allow-failures quando você quiser artefatos sem um código de saída de falha.
  • Exige dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário do Telegram.
  • Para observação estável de bot para bot, habilite Bot-to-Bot Communication Mode no @BotFather para ambos os bots e garanta que o bot driver possa observar o tráfego de bots do grupo.
  • Grava um relatório de QA do Telegram, resumo e artefato de mensagens observadas em .artifacts/qa-e2e/.... Cenários de resposta incluem RTT desde a solicitação de envio do driver até a resposta SUT observada.

Lanes de transporte ao vivo compartilham um contrato padrão para que novos transportes não desviem; a matriz de cobertura por lane fica em visão geral de QA → Cobertura de transporte ao vivo. qa-channel é a suíte sintética ampla e não faz parte dessa matriz.

# Credenciais compartilhadas do Telegram via Convex (v1)

Quando --credential-source convex (ou OPENCLAW_QA_CREDENTIAL_SOURCE=convex) está habilitado para openclaw qa telegram, o QA lab adquire um lease exclusivo de um pool baseado em Convex, envia heartbeats para esse lease enquanto a lane está em execução e libera o lease no desligamento.

Scaffold de projeto Convex de referência:

• qa/convex-credential-broker/

Env vars obrigatórias:

• OPENCLAW_QA_CONVEX_SITE_URL (por exemplo https://your-deployment.convex.site)
• Um segredo para a função selecionada:
  • OPENCLAW_QA_CONVEX_SECRET_MAINTAINER para maintainer
  • OPENCLAW_QA_CONVEX_SECRET_CI para ci
• Seleção de função de credencial:
  • CLI: --credential-role maintainer|ci
  • Padrão env: OPENCLAW_QA_CREDENTIAL_ROLE (padrão para ci em CI, maintainer caso contrário)

Env vars opcionais:

• OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS (padrão 1200000)
• OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS (padrão 30000)
• OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS (padrão 90000)
• OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS (padrão 15000)
• OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX (padrão /qa-credentials/v1)
• OPENCLAW_QA_CREDENTIAL_OWNER_ID (id de rastreamento opcional)
• OPENCLAW_QA_ALLOW_INSECURE_HTTP=1 permite URLs Convex http:// de local loopback para desenvolvimento somente local.

OPENCLAW_QA_CONVEX_SITE_URL deve usar https:// na operação normal.

Comandos administrativos de mantenedor (adicionar/remover/listar pool) exigem especificamente OPENCLAW_QA_CONVEX_SECRET_MAINTAINER.

Auxiliares de CLI para mantenedores:

pnpm openclaw qa credentials doctor
pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json
pnpm openclaw qa credentials list --kind telegram
pnpm openclaw qa credentials remove --credential-id <credential-id>

Use doctor antes de execuções live para verificar a URL do site Convex, os segredos do broker, o prefixo do endpoint, o tempo limite HTTP e a acessibilidade de admin/list sem imprimir valores secretos. Use --json para saída legível por máquina em scripts e utilitários de CI.

Contrato padrão de endpoint (OPENCLAW_QA_CONVEX_SITE_URL + /qa-credentials/v1):

• POST /acquire
  • Solicitação: { kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }
  • Sucesso: { status: "ok", credentialId, leaseToken, payload, leaseTtlMs?, heartbeatIntervalMs? }
  • Esgotado/repetível: { status: "error", code: "POOL_EXHAUSTED" | "NO_CREDENTIAL_AVAILABLE", ... }
• POST /heartbeat
  • Solicitação: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Sucesso: { status: "ok" } (ou 2xx vazio)
• POST /release
  • Solicitação: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Sucesso: { status: "ok" } (ou 2xx vazio)
• POST /admin/add (somente segredo de mantenedor)
  • Solicitação: { kind, actorId, payload, note?, status? }
  • Sucesso: { status: "ok", credential }
• POST /admin/remove (somente segredo de mantenedor)
  • Solicitação: { credentialId, actorId }
  • Sucesso: { status: "ok", changed, credential }
  • Proteção de lease ativo: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (somente segredo de mantenedor)
  • Solicitação: { kind?, status?, includePayload?, limit? }
  • Sucesso: { status: "ok", credentials, count }

Formato do payload para o tipo Telegram:

• { groupId: string, driverToken: string, sutToken: string }
• groupId deve ser uma string de id numérico de chat do Telegram.
• admin/add valida esse formato para kind: "telegram" e rejeita payloads malformados.

# Adicionar um canal ao QA

A arquitetura e os nomes dos auxiliares de cenário para novos adaptadores de canal ficam em Visão geral de QA → Adicionar um canal. O requisito mínimo: implementar o runner de transporte na seam compartilhada do host qa-lab, declarar qaRunners no manifesto do Plugin, montar como openclaw qa <runner> e criar cenários em qa/scenarios/.

# Suítes de teste (o que roda onde)

Pense nas suítes como "realismo crescente" (e instabilidade/custo crescentes):

# Unidade / integração (padrão)

• Comando: pnpm test
• Configuração: execuções sem alvo usam o conjunto de shards vitest.full-*.config.ts e podem expandir shards multiprojeto em configurações por projeto para agendamento paralelo
• Arquivos: inventários core/unit em src/**/*.test.ts, packages/**/*.test.ts e test/**/*.test.ts; testes unitários de UI rodam no shard dedicado unit-ui
• Escopo:
  • Testes unitários puros
  • Testes de integração em processo (autenticação do gateway, roteamento, ferramentas, parsing, configuração)
  • Regressões determinísticas para bugs conhecidos
• Expectativas:
  • Roda no CI
  • Nenhuma chave real exigida
  • Deve ser rápido e estável
  • Testes de resolvedor e loader de superfície pública devem provar comportamento amplo de fallback de api.js e runtime-api.js com fixtures minúsculas geradas de Plugin, não APIs reais de código-fonte de Plugin bundled. Carregamentos reais de API de Plugin pertencem a suítes de contrato/integração pertencentes ao Plugin.

# Estabilidade (gateway)

• Comando: pnpm test:stability:gateway
• Configuração: vitest.gateway.config.ts, forçada para um worker
• Escopo:
  • Inicia um Gateway real em loopback com diagnósticos habilitados por padrão
  • Conduz churn sintético de mensagens de gateway, memória e payloads grandes pelo caminho de eventos de diagnóstico
  • Consulta diagnostics.stability pelo RPC WS do Gateway
  • Cobre auxiliares de persistência de bundle de estabilidade de diagnóstico
  • Afirma que o gravador permanece limitado, amostras sintéticas de RSS ficam abaixo do orçamento de pressão e profundidades de fila por sessão drenam de volta para zero
• Expectativas:
  • Seguro para CI e sem chaves
  • Lane estreita para acompanhamento de regressão de estabilidade, não substituto para a suíte completa do Gateway

# E2E (smoke do gateway)

• Comando: pnpm test:e2e
• Configuração: vitest.e2e.config.ts
• Arquivos: src/**/*.e2e.test.ts, test/**/*.e2e.test.ts e testes E2E de Plugins empacotados em extensions/
• Padrões de tempo de execução:
  • Usa threads do Vitest com isolate: false, correspondendo ao restante do repositório.
  • Usa workers adaptativos (CI: até 2, local: 1 por padrão).
  • Executa em modo silencioso por padrão para reduzir a sobrecarga de E/S do console.
• Substituições úteis:
  • OPENCLAW_E2E_WORKERS=<n> para forçar a contagem de workers (limitada a 16).
  • OPENCLAW_E2E_VERBOSE=1 para reativar a saída detalhada do console.
• Escopo:
  • Comportamento ponta a ponta de Gateway com múltiplas instâncias
  • Superfícies WebSocket/HTTP, pareamento de Node e rede mais pesada
• Expectativas:
  • Executa em CI (quando habilitado no pipeline)
  • Não requer chaves reais
  • Mais partes móveis do que testes unitários (pode ser mais lento)

# E2E: verificação smoke do backend do OpenShell

• Comando: pnpm test:e2e:openshell
• Arquivo: extensions/openshell/src/backend.e2e.test.ts
• Escopo:
  • Inicia um Gateway OpenShell isolado no host via Docker
  • Cria um sandbox a partir de um Dockerfile local temporário
  • Exercita o backend OpenShell do OpenClaw por meio de sandbox ssh-config real + execução SSH
  • Verifica o comportamento do sistema de arquivos canônico remoto por meio da ponte fs do sandbox
• Expectativas:
  • Somente por adesão; não faz parte da execução padrão de pnpm test:e2e
  • Requer uma CLI local openshell e um daemon Docker funcional
  • Usa HOME / XDG_CONFIG_HOME isolados e depois destrói o Gateway e o sandbox de teste
• Substituições úteis:
  • OPENCLAW_E2E_OPENSHELL=1 para habilitar o teste ao executar manualmente a suíte e2e mais ampla
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell para apontar para um binário de CLI não padrão ou script wrapper

# Ao vivo (provedores reais + modelos reais)

• Comando: pnpm test:live
• Configuração: vitest.live.config.ts
• Arquivos: src/**/*.live.test.ts, test/**/*.live.test.ts e testes ao vivo de Plugins empacotados em extensions/
• Padrão: habilitado por pnpm test:live (define OPENCLAW_LIVE_TEST=1)
• Escopo:
  • "Este provedor/modelo realmente funciona hoje com credenciais reais?"
  • Capturar mudanças de formato de provedores, peculiaridades de chamada de ferramentas, problemas de autenticação e comportamento de limite de taxa
• Expectativas:
  • Não é estável para CI por design (redes reais, políticas reais de provedores, cotas, indisponibilidades)
  • Custa dinheiro / usa limites de taxa
  • Prefira executar subconjuntos reduzidos em vez de "tudo"
• Execuções ao vivo carregam ~/.profile para obter chaves de API ausentes.
• Por padrão, execuções ao vivo ainda isolam HOME e copiam material de configuração/autenticação para um home de teste temporário para que fixtures unitárias não possam alterar seu ~/.openclaw real.
• Defina OPENCLAW_LIVE_USE_REAL_HOME=1 somente quando você intencionalmente precisar que testes ao vivo usem seu diretório home real.
• pnpm test:live agora usa por padrão um modo mais silencioso: mantém a saída de progresso [live] ..., mas suprime o aviso extra de ~/.profile e silencia logs de bootstrap do Gateway/conversa do Bonjour. Defina OPENCLAW_LIVE_TEST_QUIET=0 se quiser os logs completos de inicialização de volta.
• Rotação de chaves de API (específica por provedor): defina *_API_KEYS com formato separado por vírgula/ponto e vírgula ou *_API_KEY_1, *_API_KEY_2 (por exemplo, OPENAI_API_KEYS, ANTHROPIC_API_KEYS, GEMINI_API_KEYS) ou substituição por execução ao vivo via OPENCLAW_LIVE_*_KEY; os testes tentam novamente em respostas de limite de taxa.
• Saída de progresso/Heartbeat:
  • Suítes ao vivo agora emitem linhas de progresso para stderr para que chamadas longas a provedores fiquem visivelmente ativas mesmo quando a captura de console do Vitest está silenciosa.
  • vitest.live.config.ts desabilita a interceptação de console do Vitest para que linhas de progresso do provedor/Gateway sejam transmitidas imediatamente durante execuções ao vivo.
  • Ajuste Heartbeats de modelo direto com OPENCLAW_LIVE_HEARTBEAT_MS.
  • Ajuste Heartbeats de Gateway/probe com OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

# Qual suíte devo executar?

Use esta tabela de decisão:

• Editando lógica/testes: execute pnpm test (e pnpm test:coverage se você mudou muita coisa)
• Alterando rede do Gateway / protocolo WS / pareamento: adicione pnpm test:e2e
• Depurando "meu bot está fora do ar" / falhas específicas de provedor / chamada de ferramentas: execute um pnpm test:live reduzido

# Testes ao vivo (que tocam a rede)

Para a matriz de modelos ao vivo, verificações smoke de backend da CLI, verificações smoke ACP, harness de servidor de aplicativo Codex e todos os testes ao vivo de provedores de mídia (Deepgram, BytePlus, ComfyUI, imagem, música, vídeo, harness de mídia) - além do tratamento de credenciais para execuções ao vivo - consulte Testando suítes ao vivo. Para a lista de verificação dedicada de atualização e validação de Plugin, consulte Testando atualizações e Plugins.

# Runners Docker (verificações opcionais de "funciona no Linux")

Estes runners Docker se dividem em dois grupos:

• Runners de modelos ao vivo: test:docker:live-models e test:docker:live-gateway executam apenas seu arquivo ao vivo correspondente de chave de perfil dentro da imagem Docker do repositório (src/agents/models.profiles.live.test.ts e src/gateway/gateway-models.profiles.live.test.ts), montando seu diretório de configuração local e workspace (e carregando ~/.profile se montado). Os pontos de entrada locais correspondentes são test:live:models-profiles e test:live:gateway-profiles.
• Runners Docker ao vivo usam por padrão um limite de smoke menor para manter uma varredura Docker completa prática: test:docker:live-models usa por padrão OPENCLAW_LIVE_MAX_MODELS=12, e test:docker:live-gateway usa por padrão OPENCLAW_LIVE_GATEWAY_SMOKE=1, OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8, OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000 e OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000. Substitua essas variáveis de ambiente quando você quiser explicitamente a varredura exaustiva maior.
• test:docker:all cria a imagem Docker ao vivo uma vez via test:docker:live-build, empacota o OpenClaw uma vez como um tarball npm por meio de scripts/package-openclaw-for-docker.mjs e depois cria/reutiliza duas imagens scripts/e2e/Dockerfile. A imagem básica é apenas o runner Node/Git para lanes de instalação/atualização/dependência de Plugin; essas lanes montam o tarball pré-criado. A imagem funcional instala o mesmo tarball em /app para lanes de funcionalidade do aplicativo criado. As definições de lanes Docker ficam em scripts/lib/docker-e2e-scenarios.mjs; a lógica do planejador fica em scripts/lib/docker-e2e-plan.mjs; scripts/test-docker-all.mjs executa o plano selecionado. O agregado usa um escalonador local ponderado: OPENCLAW_DOCKER_ALL_PARALLELISM controla slots de processo, enquanto limites de recursos impedem que lanes pesadas ao vivo, de instalação npm e multisserviço iniciem todas ao mesmo tempo. Se uma única lane for mais pesada que os limites ativos, o escalonador ainda pode iniciá-la quando o pool estiver vazio e então mantê-la rodando sozinha até que haja capacidade disponível novamente. Os padrões são 10 slots, OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9, OPENCLAW_DOCKER_ALL_NPM_LIMIT=10 e OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7; ajuste OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT ou OPENCLAW_DOCKER_ALL_DOCKER_LIMIT somente quando o host Docker tiver mais folga. O runner executa uma pré-verificação do Docker por padrão, remove contêineres E2E obsoletos do OpenClaw, imprime status a cada 30 segundos, armazena tempos de lanes bem-sucedidas em .artifacts/docker-tests/lane-timings.json e usa esses tempos para iniciar primeiro lanes mais longas em execuções posteriores. Use OPENCLAW_DOCKER_ALL_DRY_RUN=1 para imprimir o manifesto ponderado de lanes sem criar ou executar Docker, ou node scripts/test-docker-all.mjs --plan-json para imprimir o plano de CI para lanes selecionadas, necessidades de pacote/imagem e credenciais.
• Package Acceptance é o gate de pacote nativo do GitHub para "este tarball instalável funciona como um produto?" Ele resolve um pacote candidato a partir de source=npm, source=ref, source=url ou source=artifact, faz upload dele como package-under-test e então executa as lanes E2E Docker reutilizáveis contra esse tarball exato em vez de reempacotar a ref selecionada. Os perfis são ordenados por abrangência: smoke, package, product e full. Consulte Testando atualizações e Plugins para o contrato de pacote/atualização/Plugin, a matriz de sobrevivência de upgrade publicado, padrões de release e triagem de falhas.
• Verificações de build e release executam scripts/check-cli-bootstrap-imports.mjs após tsdown. A guarda percorre o grafo criado estático a partir de dist/entry.js e dist/cli/run-main.js e falha se a inicialização pré-dispatch importar dependências de pacote como Commander, interface de prompt, undici ou logging antes do dispatch de comando; ela também mantém o chunk de execução do Gateway empacotado dentro do orçamento e rejeita importações estáticas de caminhos frios conhecidos do Gateway. A verificação smoke da CLI empacotada também cobre ajuda raiz, ajuda de onboard, ajuda de doctor, status, esquema de configuração e um comando de listagem de modelos.
• A compatibilidade legada do Package Acceptance é limitada a 2026.4.25 (2026.4.25-beta.* incluído). Até esse corte, o harness tolera apenas lacunas de metadados de pacotes enviados: entradas omitidas de inventário privado de QA, ausência de gateway install --wrapper, ausência de arquivos de patch na fixture git derivada do tarball, ausência de update.channel persistido, locais legados de registros de instalação de Plugin, ausência de persistência de registros de instalação do marketplace e migração de metadados de configuração durante plugins update. Para pacotes após 2026.4.25, esses caminhos são falhas estritas.
• Runners de smoke de contêiner: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, test:docker:update-channel-switch, test:docker:upgrade-survivor, test:docker:published-upgrade-survivor, test:docker:session-runtime-context, test:docker:agents-delete-shared-workspace, test:docker:gateway-network, test:docker:browser-cdp-snapshot, test:docker:mcp-channels, test:docker:pi-bundle-mcp-tools, test:docker:cron-mcp-cleanup, test:docker:plugins, test:docker:plugin-update, test:docker:plugin-lifecycle-matrix e test:docker:config-reload inicializam um ou mais contêineres reais e verificam caminhos de integração de nível mais alto.

Os runners Docker de modelos ao vivo também montam por bind somente os homes de autenticação da CLI necessários (ou todos os compatíveis quando a execução não está reduzida), depois os copiam para o home do contêiner antes da execução para que o OAuth de CLI externa possa atualizar tokens sem modificar o armazenamento de autenticação do host:

• Modelos diretos: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
• Teste de fumaça de bind ACP: pnpm test:docker:live-acp-bind (script: scripts/test-live-acp-bind-docker.sh; cobre Claude, Codex e Gemini por padrão, com cobertura estrita de Droid/OpenCode via pnpm test:docker:live-acp-bind:droid e pnpm test:docker:live-acp-bind:opencode)
• Teste de fumaça do backend da CLI: pnpm test:docker:live-cli-backend (script: scripts/test-live-cli-backend-docker.sh)
• Teste de fumaça do harness do servidor de app do Codex: pnpm test:docker:live-codex-harness (script: scripts/test-live-codex-harness-docker.sh)
• Gateway + agente de desenvolvimento: pnpm test:docker:live-gateway (script: scripts/test-live-gateway-models-docker.sh)
• Teste de fumaça de observabilidade: pnpm qa:otel:smoke é uma lane privada de QA com checkout do código-fonte. Ela intencionalmente não faz parte das lanes de lançamento de pacote Docker porque o tarball npm omite o QA Lab.
• Teste de fumaça live do Open WebUI: pnpm test:docker:openwebui (script: scripts/e2e/openwebui-docker.sh)
• Assistente de onboarding (TTY, scaffolding completo): pnpm test:docker:onboard (script: scripts/e2e/onboard-docker.sh)
• Teste de fumaça de onboarding/canal/agente com tarball npm: pnpm test:docker:npm-onboard-channel-agent instala o tarball empacotado do OpenClaw globalmente no Docker, configura OpenAI via onboarding com referência de env mais Telegram por padrão, executa o doctor e executa uma rodada simulada de agente OpenAI. Reutilize um tarball pré-construído com OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz, ignore a reconstrução no host com OPENCLAW_NPM_ONBOARD_HOST_BUILD=0 ou troque o canal com OPENCLAW_NPM_ONBOARD_CHANNEL=discord ou OPENCLAW_NPM_ONBOARD_CHANNEL=slack.
• Teste de fumaça de troca de canal de atualização: pnpm test:docker:update-channel-switch instala o tarball empacotado do OpenClaw globalmente no Docker, troca de pacote stable para git dev, verifica o canal persistido e o funcionamento do Plugin após a atualização, depois troca de volta para pacote stable e verifica o status de atualização.
• Teste de fumaça de sobrevivência de upgrade: pnpm test:docker:upgrade-survivor instala o tarball empacotado do OpenClaw sobre uma fixture suja de usuário antigo com agentes, configuração de canal, allowlists de Plugin, estado obsoleto de dependências de Plugin e arquivos de workspace/sessão existentes. Ele executa a atualização do pacote mais o doctor não interativo sem provedor live nem chaves de canal, depois inicia um Gateway de loopback e verifica a preservação de configuração/estado mais orçamentos de inicialização/status.
• Teste de fumaça de sobrevivência de upgrade publicado: pnpm test:docker:published-upgrade-survivor instala openclaw@latest por padrão, semeia arquivos realistas de usuário existente, configura essa linha de base com uma receita de comando embutida, valida a configuração resultante, atualiza essa instalação publicada para o tarball candidato, executa o doctor não interativo, grava .artifacts/upgrade-survivor/summary.json, depois inicia um Gateway de loopback e verifica intents configuradas, preservação de estado, inicialização, /healthz, /readyz e orçamentos de status RPC. Substitua uma linha de base com OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, peça ao agendador agregado para expandir linhas de base locais exatas com OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS, como [email protected] [email protected] [email protected], e expanda fixtures no formato de issues com OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS, como reported-issues; o conjunto reported-issues inclui configured-plugin-installs para reparo automático de instalação de Plugin externo do OpenClaw. Package Acceptance expõe esses itens como published_upgrade_survivor_baseline, published_upgrade_survivor_baselines e published_upgrade_survivor_scenarios, resolve tokens meta de linha de base como last-stable-4 ou all-since-2026.4.23, e Full Release Validation expande o gate de pacote release-soak para last-stable-4 2026.4.23 2026.5.2 2026.4.15 mais reported-issues.
• Teste de fumaça de contexto de runtime de sessão: pnpm test:docker:session-runtime-context verifica a persistência oculta da transcrição de contexto de runtime mais o reparo pelo doctor de ramificações duplicadas afetadas de reescrita de prompt.
• Teste de fumaça de instalação global com Bun: bash scripts/e2e/bun-global-install-smoke.sh empacota a árvore atual, instala com bun install -g em uma home isolada e verifica que openclaw infer image providers --json retorna provedores de imagem integrados em vez de travar. Reutilize um tarball pré-construído com OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz, ignore a build do host com OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0 ou copie dist/ de uma imagem Docker construída com OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local.
• Teste de fumaça do instalador no Docker: bash scripts/test-install-sh-docker.sh compartilha um cache npm entre seus contêineres root, update e direct-npm. O teste de fumaça de atualização usa por padrão npm latest como a linha de base stable antes de fazer upgrade para o tarball candidato. Substitua com OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 localmente, ou com a entrada update_baseline_version do fluxo de trabalho Install Smoke no GitHub. Verificações de instalador sem root mantêm um cache npm isolado para que entradas de cache pertencentes ao root não mascarem o comportamento de instalação local do usuário. Defina OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache para reutilizar o cache root/update/direct-npm em novas execuções locais.
• Install Smoke CI ignora a atualização global direct-npm duplicada com OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1; execute o script localmente sem essa env quando for necessária cobertura direta de npm install -g.
• Teste de fumaça da CLI para excluir workspace compartilhado de agentes: pnpm test:docker:agents-delete-shared-workspace (script: scripts/e2e/agents-delete-shared-workspace-docker.sh) constrói a imagem do Dockerfile raiz por padrão, semeia dois agentes com um workspace em uma home de contêiner isolada, executa agents delete --json e verifica JSON válido mais o comportamento de workspace preservado. Reutilize a imagem install-smoke com OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE=openclaw-dockerfile-smoke:local OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD=1.
• Rede do Gateway (dois contêineres, autenticação WS + integridade): pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
• Teste de fumaça de snapshot CDP do navegador: pnpm test:docker:browser-cdp-snapshot (script: scripts/e2e/browser-cdp-snapshot-docker.sh) constrói a imagem E2E de origem mais uma camada do Chromium, inicia o Chromium com CDP bruto, executa browser doctor --deep e verifica que os snapshots de papéis do CDP cobrem URLs de links, clicáveis promovidos por cursor, refs de iframe e metadados de frame.
• Regressão de raciocínio mínimo com OpenAI Responses web_search: pnpm test:docker:openai-web-search-minimal (script: scripts/e2e/openai-web-search-minimal-docker.sh) executa um servidor OpenAI simulado pelo Gateway, verifica que web_search eleva reasoning.effort de minimal para low, depois força a rejeição do schema do provedor e verifica que o detalhe bruto aparece nos logs do Gateway.
• Ponte de canal MCP (Gateway semeado + ponte stdio + teste de fumaça de frame de notificação Claude bruto): pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)
• Ferramentas MCP do pacote Pi (servidor MCP stdio real + teste de fumaça allow/deny do perfil Pi incorporado): pnpm test:docker:pi-bundle-mcp-tools (script: scripts/e2e/pi-bundle-mcp-tools-docker.sh)
• Limpeza de MCP Cron/subagente (Gateway real + desmontagem de filho MCP stdio após cron isolado e execuções únicas de subagente): pnpm test:docker:cron-mcp-cleanup (script: scripts/e2e/cron-mcp-cleanup-docker.sh)
• Plugins (teste de fumaça de instalação/atualização para caminho local, file:, registro npm com dependências hoisted, refs móveis do git, kitchen-sink do ClawHub, atualizações de marketplace e habilitação/inspeção do pacote Claude): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh) Defina OPENCLAW_PLUGINS_E2E_CLAWHUB=0 para ignorar o bloco do ClawHub, ou substitua o par padrão pacote/runtime kitchen-sink com OPENCLAW_PLUGINS_E2E_CLAWHUB_SPEC e OPENCLAW_PLUGINS_E2E_CLAWHUB_ID. Sem OPENCLAW_CLAWHUB_URL/CLAWHUB_URL, o teste usa um servidor local hermético de fixture do ClawHub.
• Teste de fumaça de atualização inalterada de Plugin: pnpm test:docker:plugin-update (script: scripts/e2e/plugin-update-unchanged-docker.sh)
• Teste de fumaça da matriz de ciclo de vida de Plugin: pnpm test:docker:plugin-lifecycle-matrix instala o tarball empacotado do OpenClaw em um contêiner limpo, instala um Plugin npm, alterna habilitar/desabilitar, faz upgrade e downgrade dele por um registro npm local, exclui o código instalado, depois verifica que a desinstalação ainda remove estado obsoleto enquanto registra métricas de RSS/CPU para cada fase do ciclo de vida.
• Teste de fumaça de metadados de recarregamento de configuração: pnpm test:docker:config-reload (script: scripts/e2e/config-reload-source-docker.sh)
• Plugins: pnpm test:docker:plugins cobre teste de fumaça de instalação/atualização para caminho local, file:, registro npm com dependências hoisted, refs móveis do git, fixtures do ClawHub, atualizações de marketplace e habilitação/inspeção do pacote Claude. pnpm test:docker:plugin-update cobre o comportamento de atualização inalterada para Plugins instalados. pnpm test:docker:plugin-lifecycle-matrix cobre instalação, habilitação, desabilitação, upgrade, downgrade e desinstalação com código ausente de Plugin npm com rastreamento de recursos.

Para pré-construir e reutilizar manualmente a imagem funcional compartilhada:

OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local pnpm test:docker:e2e-build
OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e-functional:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels

Substituições de imagem específicas da suíte, como OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE, ainda têm precedência quando definidas. Quando OPENCLAW_SKIP_DOCKER_BUILD=1 aponta para uma imagem compartilhada remota, os scripts fazem pull dela se ainda não estiver local. Os testes Docker de QR e instalador mantêm seus próprios Dockerfiles porque validam comportamento de pacote/instalação em vez do runtime de app construído compartilhado.

Os executores Docker de modelos live também montam o checkout atual como somente leitura e o preparam em um diretório de trabalho temporário dentro do contêiner. Isso mantém a imagem de runtime enxuta, enquanto ainda executa o Vitest contra exatamente o seu código-fonte/configuração local. A etapa de preparação ignora caches grandes apenas locais e saídas de build de apps, como .pnpm-store, .worktrees, __openclaw_vitest__ e diretórios de saída .build locais do app ou do Gradle, para que execuções live no Docker não passem minutos copiando artefatos específicos da máquina. Elas também definem OPENCLAW_SKIP_CHANNELS=1 para que sondagens live do gateway não iniciem workers de canal reais de Telegram/Discord/etc. dentro do contêiner. test:docker:live-models ainda executa pnpm test:live, então repasse também OPENCLAW_LIVE_GATEWAY_* quando você precisar restringir ou excluir a cobertura live do gateway dessa lane Docker. test:docker:openwebui é um smoke de compatibilidade de nível mais alto: ele inicia um contêiner do gateway OpenClaw com os endpoints HTTP compatíveis com OpenAI habilitados, inicia um contêiner fixado do Open WebUI contra esse gateway, faz login pelo Open WebUI, verifica se /api/models expõe openclaw/default e então envia uma solicitação de chat real pelo proxy /api/chat/completions do Open WebUI. A primeira execução pode ser visivelmente mais lenta porque o Docker pode precisar baixar a imagem do Open WebUI e o Open WebUI pode precisar concluir sua própria configuração de inicialização a frio. Essa lane espera uma chave de modelo live utilizável, e OPENCLAW_PROFILE_FILE (~/.profile por padrão) é a principal forma de fornecê-la em execuções dockerizadas. Execuções bem-sucedidas imprimem um pequeno payload JSON como { "ok": true, "model": "openclaw/default", ... }. test:docker:mcp-channels é intencionalmente determinístico e não precisa de uma conta real de Telegram, Discord ou iMessage. Ele inicializa um contêiner Gateway semeado, inicia um segundo contêiner que cria openclaw mcp serve e então verifica descoberta de conversas roteadas, leituras de transcrições, metadados de anexos, comportamento da fila de eventos live, roteamento de envio de saída e notificações de canal + permissão no estilo Claude pela ponte MCP stdio real. A verificação de notificações inspeciona diretamente os frames MCP stdio brutos, para que o smoke valide o que a ponte realmente emite, não apenas o que um SDK de cliente específico por acaso expõe. test:docker:pi-bundle-mcp-tools é determinístico e não precisa de uma chave de modelo live. Ele constrói a imagem Docker do repositório, inicia um servidor de sonda MCP stdio real dentro do contêiner, materializa esse servidor pelo runtime MCP do pacote Pi embutido, executa a ferramenta e então verifica se coding e messaging mantêm ferramentas bundle-mcp, enquanto minimal e tools.deny: ["bundle-mcp"] as filtram. test:docker:cron-mcp-cleanup é determinístico e não precisa de uma chave de modelo live. Ele inicia um Gateway semeado com um servidor de sonda MCP stdio real, executa um turno cron isolado e um turno filho único de /subagents spawn, e então verifica se o processo filho MCP termina após cada execução.

Smoke manual de thread ACP em linguagem simples (não CI):

• bun scripts/dev/discord-acp-plain-language-smoke.ts --channel <discord-channel-id> ...
• Mantenha este script para fluxos de regressão/debug. Ele pode ser necessário novamente para validação de roteamento de threads ACP, então não o exclua.

Variáveis de ambiente úteis:

• OPENCLAW_CONFIG_DIR=... (padrão: ~/.openclaw) montado em /home/node/.openclaw
• OPENCLAW_WORKSPACE_DIR=... (padrão: ~/.openclaw/workspace) montado em /home/node/.openclaw/workspace
• OPENCLAW_PROFILE_FILE=... (padrão: ~/.profile) montado em /home/node/.profile e carregado antes de executar os testes
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 para verificar somente variáveis de ambiente carregadas de OPENCLAW_PROFILE_FILE, usando diretórios temporários de configuração/workspace e sem montagens externas de autenticação da CLI
• OPENCLAW_DOCKER_CLI_TOOLS_DIR=... (padrão: ~/.cache/openclaw/docker-cli-tools) montado em /home/node/.npm-global para instalações de CLI em cache dentro do Docker
• Diretórios/arquivos externos de autenticação de CLI em $HOME são montados como somente leitura em /host-auth... e então copiados para /home/node/... antes do início dos testes
  • Diretórios padrão: .minimax
  • Arquivos padrão: ~/.codex/auth.json, ~/.codex/config.toml, .claude.json, ~/.claude/.credentials.json, ~/.claude/settings.json, ~/.claude/settings.local.json
  • Execuções restritas por provedor montam somente os diretórios/arquivos necessários inferidos de OPENCLAW_LIVE_PROVIDERS / OPENCLAW_LIVE_GATEWAY_PROVIDERS
  • Sobrescreva manualmente com OPENCLAW_DOCKER_AUTH_DIRS=all, OPENCLAW_DOCKER_AUTH_DIRS=none ou uma lista separada por vírgulas como OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex
• OPENCLAW_LIVE_GATEWAY_MODELS=... / OPENCLAW_LIVE_MODELS=... para restringir a execução
• OPENCLAW_LIVE_GATEWAY_PROVIDERS=... / OPENCLAW_LIVE_PROVIDERS=... para filtrar provedores dentro do contêiner
• OPENCLAW_SKIP_DOCKER_BUILD=1 para reutilizar uma imagem openclaw:local-live existente em novas execuções que não precisam de rebuild
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para garantir que as credenciais venham do armazenamento de perfil (não do env)
• OPENCLAW_OPENWEBUI_MODEL=... para escolher o modelo exposto pelo gateway para o smoke do Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... para sobrescrever o prompt de verificação de nonce usado pelo smoke do Open WebUI
• OPENWEBUI_IMAGE=... para sobrescrever a tag fixada da imagem do Open WebUI

# Sanidade da documentação

Execute verificações da documentação após edições em docs: pnpm check:docs. Execute a validação completa de âncoras do Mintlify quando também precisar de verificações de headings na página: pnpm docs:check-links:anchors.

# Regressão offline (segura para CI)

Estas são regressões de "pipeline real" sem provedores reais:

• Chamada de ferramenta do Gateway (OpenAI mock, gateway real + loop de agente): src/gateway/gateway.test.ts (caso: "runs a mock OpenAI tool call end-to-end via gateway agent loop")
• Assistente de configuração do Gateway (WS wizard.start/wizard.next, grava configuração + autenticação aplicada): src/gateway/gateway.test.ts (caso: "runs wizard over ws and writes auth token config")

# Avaliações de confiabilidade de agentes (skills)

Já temos alguns testes seguros para CI que se comportam como "avaliações de confiabilidade de agentes":

• Chamada de ferramenta mock pelo gateway real + loop de agente (src/gateway/gateway.test.ts).
• Fluxos de assistente de configuração de ponta a ponta que validam a fiação de sessão e os efeitos de configuração (src/gateway/gateway.test.ts).

O que ainda falta para Skills (consulte Skills):

• Tomada de decisão: quando skills são listadas no prompt, o agente escolhe a skill certa (ou evita as irrelevantes)?
• Conformidade: o agente lê SKILL.md antes do uso e segue as etapas/args obrigatórios?
• Contratos de fluxo de trabalho: cenários multi-turno que verificam ordem de ferramentas, preservação de histórico de sessão e limites de sandbox.

Avaliações futuras devem continuar priorizando determinismo:

• Um executor de cenários usando provedores mock para verificar chamadas de ferramentas + ordem, leituras de arquivos de skill e fiação de sessão.
• Uma pequena suíte de cenários focados em skills (usar vs evitar, gating, injeção de prompt).
• Avaliações live opcionais (opt-in, protegidas por env) somente depois que a suíte segura para CI estiver implementada.

# Testes de contrato (forma de plugin e canal)

Testes de contrato verificam se todo plugin e canal registrado está em conformidade com seu contrato de interface. Eles iteram por todos os plugins descobertos e executam uma suíte de asserções de forma e comportamento. A lane unitária padrão de pnpm test intencionalmente ignora esses arquivos de smoke e de seam compartilhada; execute os comandos de contrato explicitamente quando tocar em superfícies compartilhadas de canal ou provedor.

# Comandos

• Todos os contratos: pnpm test:contracts
• Somente contratos de canal: pnpm test:contracts:channels
• Somente contratos de provedor: pnpm test:contracts:plugins

# Contratos de canal

Localizados em src/channels/plugins/contracts/*.contract.test.ts:

• plugin - Forma básica do plugin (id, nome, capacidades)
• setup - Contrato do assistente de configuração
• session-binding - Comportamento de vinculação de sessão
• outbound-payload - Estrutura do payload de mensagem
• inbound - Tratamento de mensagens de entrada
• actions - Handlers de ações de canal
• threading - Tratamento de ID de thread
• directory - API de diretório/lista
• group-policy - Aplicação de política de grupo

# Contratos de status de provedor

Localizados em src/plugins/contracts/*.contract.test.ts.

• status - Sondagens de status de canal
• registry - Forma do registro de plugins

# Contratos de provedor

Localizados em src/plugins/contracts/*.contract.test.ts:

• auth - Contrato de fluxo de autenticação
• auth-choice - Escolha/seleção de autenticação
• catalog - API de catálogo de modelos
• discovery - Descoberta de plugins
• loader - Carregamento de plugins
• runtime - Runtime do provedor
• shape - Forma/interface do plugin
• wizard - Assistente de configuração

# Quando executar

• Depois de alterar exports ou subpaths do plugin-sdk
• Depois de adicionar ou modificar um plugin de canal ou provedor
• Depois de refatorar registro ou descoberta de plugins

Testes de contrato executam em CI e não exigem chaves de API reais.

# Adicionando regressões (orientação)

Quando você corrige um problema de provedor/modelo descoberto em live:

• Adicione uma regressão segura para CI se possível (provedor mock/stub ou capture a transformação exata do formato da solicitação)
• Se for inerentemente apenas live (limites de taxa, políticas de autenticação), mantenha o teste live restrito e opt-in via variáveis de ambiente
• Prefira mirar na menor camada que detecta o bug:
  • bug de conversão/replay de solicitação do provedor → teste direto de modelos
  • bug de sessão/histórico/pipeline de ferramentas do gateway → smoke live do gateway ou teste mock do gateway seguro para CI
• Guardrail de travessia de SecretRef:
  • src/secrets/exec-secret-ref-id-parity.test.ts deriva um alvo amostrado por classe de SecretRef a partir dos metadados do registro (listSecretTargetRegistryEntries()) e então verifica se ids de exec com segmento de travessia são rejeitados.
  • Se você adicionar uma nova família de alvos SecretRef includeInPlan em src/secrets/target-registry-data.ts, atualize classifyTargetClass nesse teste. O teste falha intencionalmente em ids de alvo não classificados para que novas classes não possam ser ignoradas silenciosamente.

# Relacionado

• Testando live
• Testando atualizações e plugins
• CI