Testes

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 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 live descobrem credenciais e selecionam modelos/provedores.
• Como adicionar regressões para problemas reais de modelos/provedores.

​

Início rápido

• Gate completo (esperado antes de push): pnpm build && pnpm check && pnpm check:test-types && pnpm test
• Execução local mais rápida da suíte completa em uma máquina espaçosa: pnpm test:max
• Loop direto de observação do Vitest: pnpm test:watch
• O direcionamento direto de arquivos agora também roteia caminhos de extensão/canal: 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 suporte do Docker: pnpm qa:lab:up
• Faixa de QA com suporte de VM Linux: pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline

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

• Suíte live (modelos + sondas de ferramenta/imagem do Gateway): pnpm test:live
• Direcione um arquivo live silenciosamente: 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 de agente openai/gpt-5.4 real ou deep_profile=true para artefatos de CPU/heap/trace do Kova. Execuções agendadas diárias publicam artefatos das faixas mock-provider, deep-profile e GPT 5.4 em openclaw/clawgrit-reports quando CLAWGRIT_REPORTS_TOKEN está configurado. O relatório mock-provider também inclui números de boot do Gateway em nível de origem, memória, pressão de Plugin, hello-loop repetido de modelo falso e inicialização da CLI.
• Varredura live de modelos no Docker: pnpm test:docker:live-models
  • Cada modelo selecionado agora executa uma rodada de texto mais uma pequena sonda no estilo de leitura de arquivo. Modelos cujos metadados anunciam entrada image também executam uma pequena rodada de imagem. Desabilite 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 live/E2E com include_live_suites: true, que inclui jobs separados de matriz de modelos live no Docker fragmentados por provedor.
  • Para reexecuções focadas de CI, 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 faixa live no Docker contra o caminho do app-server do Codex, vincula uma DM sintética do Slack com /codex bind, exercita /codex fast e /codex permissions, então verifica uma resposta simples e um anexo de imagem roteados pela vinculação nativa do Plugin em vez de ACP.
• Smoke do harness do app-server do Codex: pnpm test:docker:live-codex-harness
  • Executa rodadas de agente do Gateway pelo harness do app-server do Codex pertencente ao Plugin, verifica /codex status e /codex models e, por padrão, exercita sondas de imagem, MCP de Cron, subagente e Guardian. Desabilite a sonda de subagente com OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_PROBE=0 ao isolar outras falhas do app-server do Codex. Para uma verificação focada de subagente, desabilite 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 após a sonda de subagente, a menos que OPENCLAW_LIVE_CODEX_HARNESS_SUBAGENT_ONLY=0 esteja definido.
• Smoke de instalação sob demanda do Codex: pnpm test:docker:codex-on-demand
  • Instala o tarball empacotado do OpenClaw no Docker, executa o onboarding com chave de API da OpenAI e verifica que o Plugin Codex e a dependência @openai/codex foram baixados sob demanda para a raiz npm gerenciada.
• Smoke live de dependência de ferramenta de Plugin: pnpm test:docker:live-plugin-tool
  • Empacota um Plugin fixture com uma dependência real slugify, instala-o por npm-pack:, verifica a dependência sob a raiz npm gerenciada e então pede a um modelo OpenAI live para chamar a ferramenta do Plugin e retornar o slug oculto.
• Smoke do comando de resgate do Crestodian: pnpm test:live:crestodian-rescue-channel
  • Verificação opcional de cinto e suspensórios para a superfície do comando de resgate do canal de mensagens. Ele 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 em PATH e verifica que o fallback de planejador fuzzy se traduz em uma gravação de configuração tipada auditada.
• Smoke Docker de primeira execução do Crestodian: pnpm test:docker:crestodian-first-run
  • Começa de um diretório de estado vazio do OpenClaw, roteia openclaw simples para Crestodian, aplica setup/modelo/agente/Plugin Discord + gravações SecretRef, valida a configuração e verifica entradas de auditoria. O mesmo caminho de setup 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, então 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

• pnpm openclaw qa suite
  • Executa cenários de QA apoiados pelo 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 faixa serial mais antiga.
  • 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 faixa mock-openai ciente de cenários.
• pnpm test:plugins:kitchen-sink-live
  • Executa a bateria do Plugin Kitchen Sink OpenAI ao vivo pelo QA Lab. Ele instala o pacote externo Kitchen Sink, verifica o inventário da superfície do SDK de Plugin, testa /healthz e /readyz, registra evidências de CPU/RSS do Gateway, executa um turno OpenAI ao vivo e verifica diagnósticos adversariais. Requer 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 apenas observações sustentadas de CPU alta por padrão (--cpu-core-warn mais --hot-wall-warn-ms), então rajadas curtas de inicialização são registradas como métricas sem parecer a regressão de Gateway travado por minutos.
  • Usa artefatos dist compilados; execute uma build primeiro quando o checkout ainda não tiver saída de runtime recente.
• 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 mais logs do Multipass em .artifacts/qa-e2e/....
• pnpm qa:lab:up
  • Inicia o site de QA apoiado por Docker para trabalho de QA no estilo operador.
• pnpm test:docker:npm-onboard-channel-agent
  • Cria um tarball npm a partir do checkout atual, instala-o globalmente no Docker, executa onboarding não interativo com chave de API OpenAI, configura Telegram por padrão, verifica se o runtime do Plugin empacotado carrega sem reparo de dependência 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 faixa de instalação empacotada com Discord.
• pnpm test:docker:session-runtime-context
  • Executa um smoke determinístico de app compilado no Docker para transcritos de contexto de runtime embutido. Ele verifica que o contexto de runtime oculto do OpenClaw é persistido como uma mensagem personalizada não exibida em vez de vazar para o turno visível do usuário, depois 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 pacote candidato do OpenClaw no Docker, executa onboarding de pacote instalado, configura Telegram pela CLI instalada e então reutiliza a faixa de QA ao vivo do Telegram com esse pacote instalado como o Gateway SUT.
  • O wrapper monta apenas o código-fonte do harness qa-lab do checkout; o pacote instalado é dono de dist, openclaw/plugin-sdk e do runtime de Plugin agrupado, para que a faixa não misture plugins do checkout atual ao pacote em teste.
  • 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 registry.
  • Usa as mesmas credenciais env do Telegram ou a mesma 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 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é-credenciais.
  • OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer sobrescreve o OPENCLAW_QA_CREDENTIAL_ROLE compartilhado apenas para esta faixa.
  • GitHub Actions expõe esta faixa como o workflow manual de mantenedores NPM Telegram Beta E2E. Ele não é executado em merge. O workflow usa o ambiente qa-live-shared e leases de credenciais CI Convex.
• 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 e então executa o agendador Docker E2E existente com perfis de faixa smoke, pacote, produto, completo ou personalizado. 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 da 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 com URL exata de tarball requer 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 de 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 a build atual do OpenClaw no Docker, inicia o Gateway com OpenAI configurado e então habilita canais/plugins agrupados via edições de configuração.
  • Verifica que a descoberta de configuração 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 de dependência oculto.
  • Também instala uma linha de base npm mais antiga conhecida, habilita Telegram antes de executar openclaw update --tag <candidate> e verifica que o doctor pós-atualização do candidato limpa resíduos de dependência de Plugin legado sem um reparo postinstall do lado do harness.
• pnpm test:parallels:npm-update
  • Executa o smoke nativo de atualização de instalação empacotada em guests Parallels. Cada plataforma selecionada primeiro instala o pacote de linha de base solicitado e então 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 ao iterar em um guest. Use --json para o caminho do artefato de resumo e o status por faixa.
  • A faixa 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 faixa aninhados em /tmp/openclaw-parallels-npm-update.*. Inspecione windows-update.log, macos-update.log ou linux-update.log antes de presumir 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 está saudável quando o log de debug npm aninhado está avançando.
  • Não execute este wrapper agregado em paralelo com faixas de smoke individuais do Parallels macOS, Windows ou Linux. Elas compartilham estado da 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 plugins agrupados porque fachadas de capacidade como fala, geração de imagens e compreensão de mídia são carregadas por APIs de runtime agrupadas mesmo quando o turno do agente em si verifica apenas uma resposta de texto simples.
• pnpm openclaw qa aimock
  • Inicia apenas o servidor de provedor AIMock local para testes smoke diretos de protocolo.
• pnpm openclaw qa matrix
  • Executa a faixa de QA ao vivo do Matrix contra um homeserver Tuwunel descartável apoiado por Docker. Somente checkout de código-fonte - instalações empacotadas não incluem qa-lab.
  • CLI completa, catálogo de perfis/cenários, variáveis env e layout de artefatos: QA do Matrix.
• pnpm openclaw qa telegram
  • Executa a faixa de QA ao vivo do Telegram contra um grupo privado real usando os tokens do driver e do bot SUT vindos do env.
  • Requer 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 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.
  • Os padrões cobrem canary, bloqueio por menção, endereçamento por comando, /status, respostas mencionadas de bot para bot e respostas de comando nativo do core. Os padrões mock-openai também cobrem regressões determinísticas de cadeia de respostas e streaming de mensagem final do Telegram. Use --list-scenarios para sondas opcionais como session_status.
  • 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.
  • Requer dois bots distintos no mesmo grupo privado, com o bot SUT expondo um nome de usuário Telegram.
  • Para observação estável de bot para bot, habilite Bot-to-Bot Communication Mode em @BotFather para ambos os bots e garanta que o bot driver possa observar tráfego de bots no grupo.
  • Grava um relatório de QA do Telegram, resumo e artefato de mensagens observadas em .artifacts/qa-e2e/.... Cenários com resposta incluem RTT desde a solicitação de envio do driver até a resposta observada do SUT.

@Mantis telegram
@Mantis telegram scenario=telegram-status-command
@Mantis telegram scenarios=telegram-status-command,telegram-mentioned-message-reply

@Mantis telegram desktop proof

• pnpm openclaw qa mantis telegram-desktop-builder
  • Aluga ou reutiliza um desktop Linux do Crabbox, instala o Telegram Desktop nativo, configura o OpenClaw com um token de bot SUT do Telegram alugado, inicia o Gateway e grava evidências de screenshot/MP4 a partir do desktop VNC visível.
  • O padrão é --credential-source convex, para que os workflows precisem apenas do segredo do broker Convex. Use --credential-source env com as mesmas variáveis OPENCLAW_QA_TELEGRAM_* de pnpm openclaw qa telegram.
  • O Telegram Desktop ainda precisa de um login/perfil de usuário. O token do bot configura apenas o OpenClaw. Use --telegram-profile-archive-env <name> para um arquivo de perfil .tgz em base64, ou use --keep-lease e faça login manualmente pelo VNC uma vez.
  • Escreve mantis-telegram-desktop-builder-report.md, mantis-telegram-desktop-builder-summary.json, telegram-desktop-builder.png e telegram-desktop-builder.mp4 no diretório de saída.

​

Credenciais compartilhadas do Telegram via Convex (v1)

• qa/convex-credential-broker/

• 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 da função da credencial:
  • CLI: --credential-role maintainer|ci
  • Padrão de env: OPENCLAW_QA_CREDENTIAL_ROLE (o padrão é ci em CI, caso contrário maintainer)

• 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 loopback para desenvolvimento somente local.

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>

• POST /acquire
  • Requisiçã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 /payload-chunk
  • Requisição: { kind, ownerId, actorRole, credentialId, leaseToken, index }
  • Sucesso: { status: "ok", index, data }
• POST /heartbeat
  • Requisição: { kind, ownerId, actorRole, credentialId, leaseToken, leaseTtlMs }
  • Sucesso: { status: "ok" } (ou 2xx vazio)
• POST /release
  • Requisição: { kind, ownerId, actorRole, credentialId, leaseToken }
  • Sucesso: { status: "ok" } (ou 2xx vazio)
• POST /admin/add (somente segredo de mantenedor)
  • Requisição: { kind, actorId, payload, note?, status? }
  • Sucesso: { status: "ok", credential }
• POST /admin/remove (somente segredo de mantenedor)
  • Requisição: { credentialId, actorId }
  • Sucesso: { status: "ok", changed, credential }
  • Guarda de lease ativo: { status: "error", code: "LEASE_ACTIVE", ... }
• POST /admin/list (somente segredo de mantenedor)
  • Requisição: { kind?, status?, includePayload?, limit? }
  • Sucesso: { status: "ok", credentials, count }

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

• { groupId: string, sutToken: string, testerUserId: string, testerUsername: string, telegramApiId: string, telegramApiHash: string, tdlibDatabaseEncryptionKey: string, tdlibArchiveBase64: string, tdlibArchiveSha256: string, desktopTdataArchiveBase64: string, desktopTdataArchiveSha256: string }
• groupId, testerUserId e telegramApiId devem ser strings numéricas.
• tdlibArchiveSha256 e desktopTdataArchiveSha256 devem ser strings hexadecimais SHA-256.
• kind: "telegram-user" representa uma conta burner do Telegram. Trate o lease como abrangente para a conta: o driver CLI TDLib e a testemunha visual do Telegram Desktop restauram a partir do mesmo payload, e apenas um job deve manter o lease por vez.

tmp=$(mktemp -d /tmp/openclaw-telegram-user.XXXXXX)
node --import tsx scripts/e2e/telegram-user-credential.ts lease-restore \
  --user-driver-dir "$tmp/user-driver" \
  --desktop-workdir "$tmp/desktop" \
  --lease-file "$tmp/lease.json"
TELEGRAM_USER_DRIVER_STATE_DIR="$tmp/user-driver" \
  uv run ~/.codex/skills/custom/telegram-e2e-bot-to-bot/scripts/user-driver.py status --json
node --import tsx scripts/e2e/telegram-user-credential.ts release --lease-file "$tmp/lease.json"

pnpm qa:telegram-user:crabbox -- start \
  --tdlib-url http://artifacts.openclaw.ai/tdlib-v1.8.0-linux-x64.tgz \
  --output-dir .artifacts/qa-e2e/telegram-user-crabbox/pr-review
pnpm qa:telegram-user:crabbox -- send \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json \
  --text /status
pnpm qa:telegram-user:crabbox -- finish \
  --session .artifacts/qa-e2e/telegram-user-crabbox/pr-review/session.json

• send --session <file> --text <message> envia pelo usuário TDLib real e aguarda a resposta do SUT.
• run --session <file> -- <remote command> executa um comando arbitrário no Crabbox e salva sua saída, por exemplo bash -lc 'source /tmp/openclaw-telegram-user-crabbox/env.sh && python3 /tmp/openclaw-telegram-user-crabbox/user-driver.py transcript --limit 20 --json'.
• screenshot --session <file> captura o desktop visível atual.
• status --session <file> imprime o lease e o comando WebVNC.
• finish --session <file> interrompe o gravador, captura artefatos de screenshot/vídeo/motion-trim, libera a credencial Convex, interrompe os processos SUT locais e interrompe o lease Crabbox, a menos que --keep-box seja passado.
• publish --session <file> --pr <number> publica um comentário de PR somente com GIF por padrão. Passe --full-artifacts apenas quando logs ou artefatos JSON forem intencionalmente necessários.

pnpm qa:telegram-user:crabbox -- --text /status

• Discord: { guildId: string, channelId: string, driverBotToken: string, sutBotToken: string, sutApplicationId: string, voiceChannelId?: string }
• WhatsApp: { driverPhoneE164: string, sutPhoneE164: string, driverAuthArchiveBase64: string, sutAuthArchiveBase64: string, groupJid?: string }

​

Adicionando um canal à QA

​

Suítes de teste (o que roda onde)

​

Unitário / integração (padrão)

• Comando: pnpm test
• Configuração: execuções não direcionadas 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 da UI rodam no shard dedicado unit-ui
• Escopo:
  • Testes puramente unitários
  • Testes de integração no processo (autenticação do Gateway, roteamento, ferramentas, parsing, configuração)
  • Regressões determinísticas para bugs conhecidos
• Expectativas:
  • Roda em CI
  • Não exige chaves reais
  • Deve ser rápido e estável
  • Testes de resolver e loader de superfície pública devem comprovar comportamento amplo de fallback de api.js e runtime-api.js com fixtures de Plugin minúsculas geradas, não com APIs de código-fonte reais de Plugin empacotado. Carregamentos de API de Plugin real pertencem a suítes de contrato/integração pertencentes ao Plugin.

• Instalações de teste padrão ignoram builds nativas opcionais do opus do Discord. O recebimento de voz do Discord usa o decodificador opusscript em JS puro, e @discordjs/opus permanece desabilitado em allowBuilds para que testes locais e lanes do Testbox não compilem o addon nativo.
• Use uma lane dedicada de desempenho de voz do Discord ou uma lane live se você precisar intencionalmente comparar uma build nativa do opus. Não defina @discordjs/opus como true no allowBuilds padrão; isso faz loops de instalação/teste não relacionados compilarem código nativo.

​

Estabilidade (gateway)

• Comando: pnpm test:stability:gateway
• Configuração: vitest.gateway.config.ts, forçada para um worker
• Escopo:
  • Inicia um Gateway loopback real com diagnósticos habilitados por padrão
  • Conduz churn sintético de mensagem de gateway, memória e payload grande pelo caminho de eventos de diagnóstico
  • Consulta diagnostics.stability pelo RPC WS do Gateway
  • Cobre helpers de persistência do pacote de estabilidade de diagnóstico
  • Afirma que o gravador permanece limitado, que amostras sintéticas de RSS ficam abaixo do orçamento de pressão e que 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 um substituto para a suite completa do Gateway

​

E2E (smoke de 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 runtime:
  • Usa threads do Vitest com isolate: false, correspondendo ao restante do repo.
  • Usa workers adaptativos (CI: até 2, local: 1 por padrão).
  • Roda em modo silencioso por padrão para reduzir overhead 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 reabilitar 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 networking mais pesado
• Expectativas:
  • Roda no CI (quando habilitado no pipeline)
  • Nenhuma chave real necessária
  • Mais partes móveis que testes unitários (pode ser mais lento)

​

E2E: smoke do backend 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 sobre sandbox ssh-config real + SSH exec
  • Verifica o comportamento de sistema de arquivos remoto-canônico pela ponte fs do sandbox
• Expectativas:
  • Somente opt-in; não faz parte da execução padrão de pnpm test:e2e
  • Requer uma CLI openshell local mais um daemon Docker funcional
  • Usa HOME / XDG_CONFIG_HOME isolados, 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 suite e2e mais ampla
  • OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell para apontar para um binário CLI não padrão ou script wrapper

​

Live (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 live 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?”
  • Detectar mudanças de formato do provedor, peculiaridades de chamada de ferramentas, problemas de autenticação e comportamento de limite de taxa
• Expectativas:
  • Não é estável para CI por definição (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 live carregam ~/.profile para obter chaves de API ausentes.
• Por padrão, execuções live ainda isolam HOME e copiam material de configuração/autenticação para uma home de teste temporária para que fixtures de unidade não possam modificar seu ~/.openclaw real.
• Defina OPENCLAW_LIVE_USE_REAL_HOME=1 somente quando você precisar intencionalmente que testes live 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 do 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 live via OPENCLAW_LIVE_*_KEY; os testes tentam novamente em respostas de limite de taxa.
• Saída de progresso/Heartbeat:
  • Suites live agora emitem linhas de progresso para stderr para que chamadas longas a provedores fiquem visivelmente ativas mesmo quando a captura de console do Vitest estiver silenciosa.
  • vitest.live.config.ts desabilita a interceptação de console do Vitest para que linhas de progresso de provedor/Gateway sejam transmitidas imediatamente durante execuções live.
  • Ajuste Heartbeats de modelo direto com OPENCLAW_LIVE_HEARTBEAT_MS.
  • Ajuste Heartbeats de Gateway/probe com OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS.

​

Qual suite devo executar?

• Editando lógica/testes: execute pnpm test (e pnpm test:coverage se você mudou muita coisa)
• Tocando networking 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 live (que acessam a rede)

​

Executores Docker (verificações opcionais de “funciona no Linux”)

• Executores de modelo live: test:docker:live-models e test:docker:live-gateway executam somente o arquivo live de profile-key correspondente 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 entrypoints locais correspondentes são test:live:models-profiles e test:live:gateway-profiles.
• Executores Docker live usam por padrão um limite de smoke menor para que uma varredura Docker completa continue 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 constrói a imagem Docker live 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 então constrói/reutiliza duas imagens scripts/e2e/Dockerfile. A imagem básica é apenas o executor Node/Git para lanes de instalação/atualização/dependências de Plugin; essas lanes montam o tarball pré-construído. A imagem funcional instala o mesmo tarball em /app para lanes de funcionalidade do app construído. 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 agendador local ponderado: OPENCLAW_DOCKER_ALL_PARALLELISM controla slots de processo, enquanto limites de recursos impedem que lanes live pesadas, de instalação npm e multi-serviço comecem todas de uma vez. Se uma única lane for mais pesada que os limites ativos, o agendador ainda poderá iniciá-la quando o pool estiver vazio e então mantê-la rodando sozinha até que a capacidade esteja 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 executor faz um preflight do Docker por padrão, remove contêineres E2E obsoletos do OpenClaw, imprime status a cada 30 segundos, armazena temporizações de lanes bem-sucedidas em .artifacts/docker-tests/lane-timings.json e usa essas temporizações para iniciar lanes mais longas primeiro em execuções posteriores. Use OPENCLAW_DOCKER_ALL_DRY_RUN=1 para imprimir o manifesto ponderado de lanes sem construir 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 produto?” Ele resolve um pacote candidato a partir de source=npm, source=ref, source=url ou source=artifact, envia-o como package-under-test e então executa as lanes Docker E2E 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, 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 o tsdown. A proteção percorre o grafo construído 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, UI de prompt, undici ou logging antes do dispatch do comando; ela também mantém o chunk empacotado de execução do Gateway dentro do orçamento e rejeita importações estáticas de caminhos conhecidos frios do Gateway. O smoke da CLI empacotada também cobre ajuda raiz, ajuda de onboard, ajuda de doctor, status, schema de configuração e um comando de lista de modelos.
• A compatibilidade legada do Package Acceptance é limitada a 2026.4.25 (2026.4.25-beta.* incluído). Até esse limite, o harness tolera apenas lacunas de metadados de pacote já enviado: entradas omitidas de inventário privado de QA, gateway install --wrapper ausente, arquivos de patch ausentes na fixture git derivada do tarball, update.channel persistido ausente, locais legados de registro de instalação de Plugin, persistência ausente de registro 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.
• Executores de smoke em contêiner: test:docker:openwebui, test:docker:onboard, test:docker:npm-onboard-channel-agent, test:docker:skill-install, 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.

• Modelos diretos: pnpm test:docker:live-models (script: scripts/test-live-models-docker.sh)
• Smoke de vinculação 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)
• Smoke de backend da CLI: pnpm test:docker:live-cli-backend (script: scripts/test-live-cli-backend-docker.sh)
• Smoke do harness app-server 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)
• Smoke de observabilidade: pnpm qa:otel:smoke é uma trilha privada de QA com checkout do código-fonte. Ela intencionalmente não faz parte das trilhas de lançamento Docker do pacote porque o tarball npm omite o QA Lab.
• Smoke 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)
• Smoke de onboarding/canal/agente do tarball npm: pnpm test:docker:npm-onboard-channel-agent instala o tarball OpenClaw empacotado globalmente no Docker, configura o OpenAI via onboarding com referência de env mais Telegram por padrão, executa o doctor e executa uma interação de agente OpenAI simulada. Reutilize um tarball pré-compilado com OPENCLAW_CURRENT_PACKAGE_TGZ=/path/to/openclaw-*.tgz, ignore a recompilaçã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.
• Smoke de instalação de Skills: pnpm test:docker:skill-install instala o tarball OpenClaw empacotado globalmente no Docker, desabilita instalações de arquivos enviados na configuração, resolve o slug da Skill live atual do ClawHub a partir da busca, instala-a com openclaw skills install e verifica a Skill instalada mais metadados de origem/bloqueio de .clawhub.
• Smoke de troca de canal de atualização: pnpm test:docker:update-channel-switch instala o tarball OpenClaw empacotado globalmente no Docker, troca do pacote stable para git dev, verifica o canal persistido e o funcionamento de Plugin pós-atualização, depois volta para o pacote stable e verifica o status de atualização.
• Smoke de sobrevivência a upgrade: pnpm test:docker:upgrade-survivor instala o tarball OpenClaw empacotado sobre uma fixture suja de usuário antigo com agentes, configuração de canal, allowlists de plugins, estado obsoleto de dependências de plugins e arquivos existentes de workspace/sessão. 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 preservação de configuração/estado mais orçamentos de inicialização/status.
• Smoke de sobrevivência a upgrade publicado: pnpm test:docker:published-upgrade-survivor instala openclaw@latest por padrão, semeia arquivos realistas de usuário existente, configura essa baseline com uma receita de comando incorporada, 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 intenções configuradas, preservação de estado, inicialização, /healthz, /readyz e orçamentos de status RPC. Sobrescreva uma baseline com OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC, peça ao agendador agregado para expandir baselines locais exatas com OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS, como openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15, 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 OpenClaw externo. A Aceitação de Pacote expõe isso como published_upgrade_survivor_baseline, published_upgrade_survivor_baselines e published_upgrade_survivor_scenarios, resolve tokens de baseline meta como last-stable-4 ou all-since-2026.4.23, e a Validação de Lançamento Completa expande o gate de soak de pacote de lançamento para last-stable-4 2026.4.23 2026.5.2 2026.4.15 mais reported-issues.
• Smoke de contexto de runtime da sessão: pnpm test:docker:session-runtime-context verifica a persistência oculta do transcript de contexto de runtime mais o reparo pelo doctor de ramificações afetadas duplicadas de reescrita de prompt.
• Smoke de instalação global do Bun: bash scripts/e2e/bun-global-install-smoke.sh empacota a árvore atual, instala-a com bun install -g em uma home isolada e verifica se openclaw infer image providers --json retorna provedores de imagem incluídos em vez de travar. Reutilize um tarball pré-compilado com OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz, ignore a compilação no host com OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0 ou copie dist/ de uma imagem Docker compilada com OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local.
• Smoke Docker do instalador: bash scripts/test-install-sh-docker.sh compartilha um cache npm entre seus contêineres root, update e direct-npm. O smoke de atualização usa por padrão o npm latest como baseline estável antes de atualizar para o tarball candidato. Sobrescreva com OPENCLAW_INSTALL_SMOKE_UPDATE_BASELINE=2026.4.22 localmente ou com a entrada update_baseline_version do workflow Install Smoke no GitHub. As verificações do instalador não 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 reexecuções locais.
• O CI Install Smoke 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.
• Smoke de CLI para exclusão de workspace compartilhado por agentes: pnpm test:docker:agents-delete-shared-workspace (script: scripts/e2e/agents-delete-shared-workspace-docker.sh) compila 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 comportamento de workspace retido. 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 + saúde): pnpm test:docker:gateway-network (script: scripts/e2e/gateway-network-docker.sh)
• Smoke de snapshot CDP do navegador: pnpm test:docker:browser-cdp-snapshot (script: scripts/e2e/browser-cdp-snapshot-docker.sh) compila a imagem E2E de código-fonte mais uma camada Chromium, inicia o Chromium com CDP bruto, executa browser doctor --deep e verifica se os snapshots de função CDP cobrem URLs de links, clicáveis promovidos por cursor, refs de iframe e metadados de frame.
• Regressão de raciocínio mínimo de web_search do OpenAI Responses: pnpm test:docker:openai-web-search-minimal (script: scripts/e2e/openai-web-search-minimal-docker.sh) executa um servidor OpenAI simulado pelo Gateway, verifica se web_search eleva reasoning.effort de minimal para low, depois força a rejeição do esquema do provedor e verifica se o detalhe bruto aparece nos logs do Gateway.
• Ponte de canal MCP (Gateway semeado + ponte stdio + smoke de frame de notificação bruta do Claude): pnpm test:docker:mcp-channels (script: scripts/e2e/mcp-channels-docker.sh)
• Ferramentas MCP do pacote Pi (servidor MCP stdio real + smoke de permissão/negação do perfil Pi incorporado): pnpm test:docker:pi-bundle-mcp-tools (script: scripts/e2e/pi-bundle-mcp-tools-docker.sh)
• Limpeza MCP de Cron/subagente (Gateway real + encerramento de filho MCP stdio após execuções isoladas de cron e subagente one-shot): pnpm test:docker:cron-mcp-cleanup (script: scripts/e2e/cron-mcp-cleanup-docker.sh)
• Plugins (smoke de instalação/atualização para caminho local, file:, registro npm com dependências hoisted, refs móveis de git, ClawHub kitchen-sink, atualizações de marketplace e habilitação/inspeção de pacote Claude): pnpm test:docker:plugins (script: scripts/e2e/plugins-docker.sh) Defina OPENCLAW_PLUGINS_E2E_CLAWHUB=0 para ignorar o bloco ClawHub ou sobrescreva o par padrão de 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 de fixture ClawHub local hermético.
• Smoke de atualização inalterada de Plugin: pnpm test:docker:plugin-update (script: scripts/e2e/plugin-update-unchanged-docker.sh)
• Smoke de matriz de ciclo de vida de Plugin: pnpm test:docker:plugin-lifecycle-matrix instala o tarball OpenClaw empacotado em um contêiner vazio, instala um Plugin npm, alterna habilitar/desabilitar, faz upgrade e downgrade dele por meio de um registro npm local, exclui o código instalado e então verifica se a desinstalação ainda remove estado obsoleto enquanto registra métricas RSS/CPU para cada fase do ciclo de vida.
• Smoke 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 smoke de instalação/atualização para caminho local, file:, registro npm com dependências hoisted, refs móveis de git, fixtures ClawHub, atualizações de marketplace e habilitação/inspeção de 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 recursos rastreados.

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

• 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 thread ACP, portanto não o exclua.

• 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 testes
• OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1 para verificar apenas 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 restringidas por provedor montam apenas 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 reexecuções que não precisam de rebuild
• OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1 para garantir que as credenciais venham do armazenamento de perfis (não do ambiente)
• OPENCLAW_OPENWEBUI_MODEL=... para escolher o modelo exposto pelo gateway para o smoke do Open WebUI
• OPENCLAW_OPENWEBUI_PROMPT=... para substituir o prompt de verificação de nonce usado pelo smoke do Open WebUI
• OPENWEBUI_IMAGE=... para substituir a tag fixada da imagem do Open WebUI

​

Sanidade da documentação

​

Regressão offline (segura para CI)

• Chamada de ferramenta do Gateway (OpenAI mockado, 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 do agente (skills)

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

• 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/argumentos exigidos?
• Contratos de workflow: cenários multi-turno que verificam ordem de ferramentas, preservação do histórico da sessão e limites do sandbox.

• Um executor de cenários usando provedores mockados para verificar chamadas de ferramenta + ordem, leituras de arquivos de skill e ligação de sessão.
• Uma pequena suíte de cenários focados em skill (usar vs evitar, bloqueios, injeção de prompt).
• Avaliações ao vivo opcionais (opt-in, controladas por env) apenas depois que a suíte segura para CI estiver pronta.

​

Testes de contrato (formato de plugin e canal)

​

Comandos

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

​

Contratos de canal

• plugin - Formato básico 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ção 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

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

​

Contratos de provedor

• auth - Contrato do 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 - Formato/interface do plugin
• wizard - Assistente de configuração

​

Quando executar

• Após alterar exports ou subcaminhos do plugin-sdk
• Após adicionar ou modificar um plugin de canal ou provedor
• Após refatorar registro ou descoberta de plugins

​

Como adicionar regressões (orientação)

• Adicione uma regressão segura para CI se possível (provedor mock/stub, ou capture a transformação exata do formato da requisição)
• Se for inerentemente apenas ao vivo (limites de taxa, políticas de autenticação), mantenha o teste ao vivo restrito e opt-in por variáveis de ambiente
• Prefira direcionar à menor camada que captura o bug:
  • bug de conversão/reprodução de requisição do provedor → teste direto de modelos
  • bug de sessão/histórico/pipeline de ferramentas do gateway → smoke ao vivo do gateway ou teste mockado de gateway seguro para CI
• Proteção de travessia SecretRef:
  • src/secrets/exec-secret-ref-id-parity.test.ts deriva um alvo amostrado por classe SecretRef a partir dos metadados do registro (listSecretTargetRegistryEntries()) e então afirma que ids de execução com segmentos 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

• Teste ao vivo
• Teste de atualizações e plugins
• CI