Testes: atualizações e plugins

Checklist de validação de atualização e plugins: comprove que o pacote instalável pode atualizar o estado real do usuário, reparar estados legados obsoletos por meio do doctor e ainda instalar, carregar, atualizar e desinstalar plugins de todas as fontes compatíveis.

Para o panorama mais amplo do executor de testes, consulte Testes. Para chaves de provedores reais e suítes que acessam a rede, consulte Testes em ambiente real.

O que protegemos

• Um tarball de pacote está completo, tem um dist/postinstall-inventory.json válido e não depende de arquivos descompactados do repositório.
• Um usuário pode migrar de um pacote publicado mais antigo para o pacote candidato sem perder configurações, agentes, sessões, espaços de trabalho, listas de permissões de plugins ou configurações de canais.
• openclaw doctor --fix --non-interactive é responsável pelos caminhos de limpeza e reparo legados. A inicialização não deve acumular migrações de compatibilidade ocultas para estados obsoletos de plugins.
• As instalações de plugins funcionam a partir de diretórios locais, repositórios git, pacotes npm e do caminho de registro do ClawHub.
• As dependências npm dos plugins são instaladas em um projeto npm gerenciado por plugin, são verificadas antes da concessão de confiança e são removidas por meio de npm uninstall durante a desinstalação do plugin, para que dependências içadas não permaneçam.
• A atualização de plugins não realiza nenhuma operação quando nada mudou: os registros de instalação, a fonte resolvida, o layout das dependências instaladas e o estado de ativação permanecem intactos.

Comprovação local durante o desenvolvimento

Comece pelo escopo mais restrito:

pnpm changed:lanes --jsonpnpm check:changedpnpm test:changed

Para alterações na instalação, desinstalação ou dependências de plugins, ou no inventário de pacotes, também execute os testes direcionados que abrangem a interface editada:

pnpm test src/plugins/uninstall.test.ts src/infra/package-dist-inventory.test.ts test/scripts/package-acceptance-workflow.test.ts

Antes que qualquer fluxo Docker de pacote consuma um tarball, valide o artefato do pacote:

pnpm release:check

release:check executa verificações de divergência de configuração/documentação/API (esquema de configuração, linha de base da documentação de configuração, linha de base e exportações da API do SDK de plugins, versões/inventário de plugins), grava o inventário de distribuição do pacote, executa npm pack --dry-run, rejeita arquivos empacotados proibidos, instala o tarball em um prefixo temporário, executa o pós-instalação e realiza testes rápidos nos pontos de entrada dos canais incluídos.

Fluxos Docker

Os fluxos Docker são a comprovação no nível do produto. Eles instalam ou atualizam um pacote real em contêineres Linux e verificam o comportamento por meio de comandos da CLI, inicialização do Gateway, sondagens HTTP, status de RPC e estado do sistema de arquivos.

Use fluxos direcionados durante as iterações:

pnpm test:docker:pluginspnpm test:docker:plugin-lifecycle-matrixpnpm test:docker:plugin-updatepnpm test:docker:upgrade-survivorpnpm test:docker:published-upgrade-survivorpnpm test:docker:update-restart-authpnpm test:docker:update-migration

Fluxos importantes:

• test:docker:plugins abrange testes rápidos de instalação de plugins, instalações de pastas locais, comportamento de ignorar atualizações de pastas locais, pastas locais com dependências pré-instaladas, instalações de pacotes file:, instalações via git com execução da CLI, atualizações de referências móveis do git, instalações do registro npm com dependências transitivas içadas, atualizações npm sem operações, rejeição de metadados malformados de pacotes npm, instalações a partir de fixture local do ClawHub e atualizações sem operações, comportamento de atualização do marketplace e ativação/inspeção do pacote Claude. Defina OPENCLAW_PLUGINS_E2E_CLAWHUB=0 para manter o bloco do ClawHub hermético e sem acesso à rede.
• test:docker:plugin-lifecycle-matrix instala o pacote candidato em um contêiner vazio e conduz um plugin npm pelas etapas de instalação, inspeção, desativação, ativação, upgrade explícito, downgrade explícito e desinstalação após excluir o código do plugin. Ele registra métricas de RSS e CPU por fase.
• test:docker:plugin-update valida que um plugin instalado e inalterado não seja reinstalado nem perca metadados de instalação durante openclaw plugins update.
• test:docker:upgrade-survivor instala o tarball candidato sobre uma fixture antiga e inconsistente de usuário, executa a atualização do pacote e o doctor não interativo e, em seguida, inicia um Gateway em local loopback e verifica a preservação do estado.
• test:docker:published-upgrade-survivor primeiro instala uma linha de base publicada, configura-a por meio de uma receita integrada de openclaw config set, atualiza-a para o tarball candidato, executa o doctor, verifica a limpeza legada, inicia o Gateway e sonda /healthz, /readyz e o status de RPC.
• test:docker:update-restart-auth instala o pacote candidato, inicia um Gateway gerenciado com autenticação por token, remove do ambiente a autenticação do Gateway do chamador para openclaw update --yes --json e exige que o comando de atualização candidato reinicie o Gateway antes das sondagens normais.
• test:docker:update-migration é o fluxo de atualização publicada com foco intensivo em limpeza. Ele parte de um estado de usuário configurado no estilo Discord/Telegram, executa o doctor da linha de base para permitir que as dependências de plugins configuradas sejam materializadas, cria resíduos legados de dependências de plugin para um plugin empacotado configurado, atualiza para o tarball candidato e exige que o doctor pós-atualização remova as raízes de dependências legadas.

Variantes úteis de sobrevivência à atualização publicada:

OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@2026.4.23 \OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=versioned-runtime-deps \pnpm test:docker:published-upgrade-survivor OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC=openclaw@latest \OPENCLAW_UPGRADE_SURVIVOR_SCENARIO=bootstrap-persona \pnpm test:docker:published-upgrade-survivor

Cenários disponíveis: base, acpx-openclaw-tools-bridge, feishu-channel, bootstrap-persona, channel-post-core-restore, plugin-deps-cleanup, configured-plugin-installs, stale-source-plugin-shadow, tilde-log-path e versioned-runtime-deps. Em execuções agregadas, OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues (alias far-reaching) expande para todos os cenários, incluindo a migração de instalação de plugins configurados.

A migração completa de atualização é intencionalmente separada da CI de versão completa. Use o fluxo manual Update Migration quando a questão da versão for "todas as versões estáveis publicadas a partir de 2026.4.23 conseguem atualizar para este candidato e limpar resíduos de dependências de plugins?":

gh workflow run update-migration.yml \  --ref main \  -f workflow_ref=main \  -f package_ref=main \  -f baselines=all-since-2026.4.23 \  -f scenarios=plugin-deps-cleanup

Aceitação de pacotes

A Aceitação de Pacotes é a barreira de pacote nativa do GitHub. Ela resolve um pacote candidato em um tarball package-under-test, registra a versão e o SHA-256 e, em seguida, executa fluxos Docker E2E reutilizáveis com esse tarball exato. A referência do mecanismo do fluxo é separada da referência de origem do pacote, permitindo que a lógica de testes atual valide versões confiáveis mais antigas.

Fontes de candidatos:

• source=npm: valide openclaw@extended-stable, openclaw@beta, openclaw@latest ou uma versão publicada exata.
• source=ref: empacote uma ramificação, tag ou commit confiável com o mecanismo atual selecionado.
• source=url: valide um tarball HTTPS público com package_sha256 obrigatório. Esse caminho rejeita credenciais em URLs, portas HTTPS não padrão, nomes de host ou resultados de DNS/IP privados/internos, espaços de IP de uso especial e redirecionamentos inseguros.
• source=trusted-url: valide um tarball HTTPS com package_sha256 e trusted_source_id obrigatórios em relação à política pertencente aos mantenedores em .github/package-trusted-sources.json. Use isso para espelhos empresariais/privados em vez de enfraquecer source=url com uma opção de entrada que permita acesso privado. Quando configurada pela política, a autenticação Bearer usa o segredo fixo OPENCLAW_TRUSTED_PACKAGE_TOKEN.
• source=artifact: reutilize um tarball enviado por outra execução do Actions.

A Validação Completa de Versão usa source=artifact por padrão, criado a partir do SHA resolvido da versão. Para comprovação pós-publicação, passe package_acceptance_package_spec=openclaw@YYYY.M.PATCH para que a mesma matriz de atualização tenha como alvo o pacote npm disponibilizado.

As verificações de versão chamam a Aceitação de Pacotes com o conjunto de pacote/atualização/reinicialização/plugins:

doctor-switch update-channel-switch skill-install update-corrupt-plugin upgrade-survivor published-upgrade-survivor root-managed-vps-upgrade update-restart-auth plugins-offline plugin-update plugin-binding-command-escape

Quando o período de estabilização da versão está ativado (obrigatoriamente para release_profile=stable e full), elas também passam:

published_upgrade_survivor_baselines=last-stable-4 2026.4.23 2026.5.2 2026.4.15published_upgrade_survivor_scenarios=reported-issuestelegram_mode=mock-openai

Isso mantém a migração de pacotes, a troca de canal de atualização, a tolerância a plugins gerenciados corrompidos, a limpeza de dependências obsoletas de plugins, a cobertura de plugins sem acesso à rede, o comportamento de atualização de plugins e o controle de qualidade do pacote do Telegram no mesmo artefato resolvido, sem fazer com que a barreira padrão de pacote da versão percorra todas as versões publicadas.

last-stable-4 é resolvido para as quatro versões estáveis mais recentes do OpenClaw publicadas no npm. A aceitação de pacote da versão fixa 2026.4.23 como o primeiro limite de compatibilidade de atualização de plugins, 2026.5.2 como um limite de mudanças intensas na arquitetura de plugins e 2026.4.15 como uma linha de base mais antiga de atualização publicada da série 2026.4.1x; o resolvedor remove duplicatas de versões fixadas que já estejam entre as quatro mais recentes. Para uma cobertura exaustiva da migração de atualizações publicadas, use all-since-2026.4.23 no fluxo separado de Migração de Atualização, em vez da CI de Versão Completa. release-history continua disponível para uma amostragem manual mais ampla quando você também quiser a âncora legada anterior à data.

Quando várias linhas de base de sobrevivência à atualização publicada são selecionadas, o fluxo Docker reutilizável divide cada linha de base em sua própria tarefa direcionada do executor. Cada fragmento de linha de base ainda executa o conjunto de cenários selecionado, mas os logs e artefatos permanecem separados por linha de base, e o tempo total fica limitado pelo fragmento mais lento, em vez de uma única tarefa serial extensa.

Execute manualmente um perfil de pacote ao validar um candidato antes da versão:

gh workflow run package-acceptance.yml \  --ref main \  -f workflow_ref=main \  -f source=npm \  -f package_spec=openclaw@beta \  -f suite_profile=package \  -f published_upgrade_survivor_baselines="last-stable-4 2026.4.23 2026.5.2 2026.4.15" \  -f published_upgrade_survivor_scenarios=reported-issues \  -f telegram_mode=mock-openai

Para um canário extended-stable publicado, defina package_spec=openclaw@extended-stable. A Aceitação de Pacotes resolve esse seletor em um tarball exato antes da execução dos fluxos Docker.

Use suite_profile=product quando a questão da versão incluir canais MCP, limpeza de cron/subagentes, pesquisa na web da OpenAI ou OpenWebUI. Use suite_profile=full somente quando precisar de cobertura completa do caminho de versão no Docker.

Padrão de versão

Para candidatos a versão, a pilha padrão de comprovação é:

1. pnpm check:changed e pnpm test:changed para regressões no nível do código-fonte.
2. pnpm release:check para a integridade do artefato do pacote.
3. O perfil package da Aceitação de Pacotes ou os fluxos personalizados de pacote das verificações de versão para contratos de instalação/atualização/reinicialização/plugins.
4. Verificações de versão entre sistemas operacionais para comportamentos de instalador, integração inicial e plataforma específicos do sistema operacional.
5. Suítes em ambiente real somente quando a superfície alterada afetar o comportamento do provedor ou do serviço hospedado.

Nas máquinas dos mantenedores, barreiras amplas e a comprovação de produto no Docker/pacote devem ser executadas no Testbox, a menos que uma comprovação local esteja sendo feita explicitamente.

Compatibilidade legada

A tolerância de compatibilidade é restrita e tem prazo limitado:

• Pacotes até 2026.4.25, incluindo 2026.4.25-beta.*, podem tolerar lacunas de metadados de pacote já disponibilizadas na Aceitação de Pacotes.
• O pacote publicado 2026.4.26 pode emitir avisos sobre arquivos de carimbo de metadados de compilação local já disponibilizados.
• Pacotes posteriores devem atender aos contratos modernos. As mesmas lacunas causam falha, em vez de aviso ou omissão.

Não adicione novas migrações de inicialização para esses formatos antigos. Adicione ou estenda um reparo do doctor e, em seguida, comprove-o com upgrade-survivor, published-upgrade-survivor ou update-restart-auth quando o comando de atualização for responsável pela reinicialização.

Adição de cobertura

Ao alterar o comportamento de atualização ou de plugins, adicione cobertura na camada mais baixa que possa falhar pelo motivo correto:

• Lógica pura de caminho ou metadados: teste unitário ao lado do código-fonte.
• Inventário do pacote ou comportamento dos arquivos empacotados: teste package-dist-inventory ou do verificador de tarball.
• Comportamento de instalação/atualização da CLI: asserção ou fixture da lane do Docker.
• Comportamento de migração de versão publicada: cenário published-upgrade-survivor.
• Comportamento de reinicialização controlado pela atualização: update-restart-auth.
• Comportamento da fonte de registro/pacote: fixture test:docker:plugins ou servidor de fixture do ClawHub.
• Comportamento do layout ou da limpeza de dependências: valide tanto a execução em tempo de execução quanto o limite do sistema de arquivos. As dependências npm podem ser içadas dentro do projeto npm gerenciado do plugin; portanto, os testes devem comprovar que esse projeto é verificado/limpo, em vez de presumir apenas a árvore node_modules local do pacote do plugin.

Mantenha as novas fixtures do Docker herméticas por padrão. Use registros de fixtures locais e pacotes falsos, a menos que o objetivo do teste seja o comportamento do registro em tempo real.

Triagem de falhas

Comece pela identidade do artefato:

• Resumo resolve_package da Aceitação de Pacotes: origem, versão, SHA-256 e nome do artefato.
• Artefatos do Docker: .artifacts/docker-tests/**/summary.json, failures.json, logs da lane e comandos de nova execução.
• Resumo de sobrevivência à atualização: .artifacts/upgrade-survivor/summary.json, incluindo versão de referência, versão candidata, cenário, tempos das fases e cobertura da receita de configuração.

Prefira executar novamente a lane exata que falhou com o mesmo artefato de pacote, em vez de executar novamente todo o conjunto de testes da versão.