Diagnóstico e testes
Investigue falhas por fase, reconheça códigos reais e valide montagem, comunicação e limpeza no navegador.
Veja versões, mudanças e requisitos em Framework 4.0 e CLI 1.2.
Comece pela fase que falhou
console.log(wu.version);
console.log(wu.getStats());
console.log(wu.getAppInfo('catalog'));
console.log(wu.getSandboxInfo('catalog'));
console.table(wu.getManifestDiagnostics());
console.log(wu.inspect({ events: 20 }));Registro, carregamento, montagem, atualização e encerramento têm causas diferentes. Guarde o nome da app, URL, entrada resolvida, seletor, modo real e erro original. Uma captura de tela vazia não permite distinguir um carregamento malsucedido de uma raiz montada que depois foi apagada pelo renderizador do shell.
Tabela de sintomas
| Sintoma | Verificação concreta | Solução |
|---|---|---|
| App não registrada | init terminou; nome idêntico em shell/manifesto/define |
Aguardar init e corrigir a identidade |
WU_MANIFEST_LOAD_FAILED |
Status, CORS, resposta de /wu.json |
Servir JSON real a partir da base registrada |
WU_MANIFEST_NAME_MISMATCH |
Nome baixado versus configuração | Publicar o manifesto dessa app |
WU_MANIFEST_INVALID |
Campos, JSON, entrada e permissões | Corrigir o manifesto; não esconder a falha com valores padrão |
WU_PERMISSION_REQUIRED |
Solicitação obrigatória sem cobertura | Ajustar deliberadamente a solicitação ou a concessão do host |
WU_CAPABILITY_DENIED |
Operação com escopo e recurso efetivo | Usar caminho/canal autorizado |
emit retorna false |
Identidade, concessões e namespace | Consultar callback/fachada com escopo, não pressupor exceção |
WU_APP_SCOPE_REVOKED |
A API é mantida após unmount | Cancelar o trabalho e obter um novo contexto ao montar |
Container not found |
O seletor é resolvido a partir de document |
Slot no light DOM existente antes de mount |
| Failed dynamically imported module | Entrada, chunks, MIME e CORS | Alinhar o manifesto ao build real |
| App vazia sem erro | O host reconcilia os filhos do slot | Separar o nó de montagem do indicador de carregamento |
| Hook React inválido | Duas cópias de React ou ReactDOM diferente | Injetar o runtime coerente no adaptador |
| Vue não atualiza o estado | Runtime Vue indisponível ao criar ref | Instalar plugin/namespace e conectar a inscrição |
| Erro RPC sem handler | Provedor ainda não montado | Ordenar o ciclo de vida ou usar um estado de espera |
Resolver conflitos de identidade e inicialização
WU_APP_EXISTS indica que o registro tenta ocupar um nome que já existe. Consulte wu.getAppInfo(name) e revise qual bootstrap registra essa identidade. A configuração de uma app existente mantém as concessões do host; criar outro wrapper não é uma forma de substituí-las.
Para verificar configuração e montagem separadamente, use uma inicialização explícita:
import { wu } from 'wu-framework';
await wu.init({ apps: [{ name: 'catalog', url: '/apps/catalog' }] });
console.log(wu.getAppInfo('catalog'));
try {
await wu.mount('catalog', '#catalog-slot');
} catch (error) {
console.error('No se pudo montar catalog', error);
console.log(wu.getSandboxInfo('catalog'));
throw error;
}whenReady() aguarda uma inicialização já iniciada; não inicia o runtime. Em integrações com efeitos de pai/filho, coordene primeiro a inicialização e depois a montagem. wu.app() realiza o registro adiado ao montar e compartilha esse registro entre mounts concorrentes do mesmo wrapper; consulte ciclo de vida para seu contrato de referências e limpeza.
Evite usar WuApp.destroy() e recriar o mesmo nome como mecanismo de atualização da configuração: esse método não limpa todos os registros relacionados. Desmonte o renderizador para uma transição normal ou reinicialize o core completo quando o shell precisar substituir sua composição.
Recuperação de montagem
O error boundary tem handlers de rede, carregamento de scripts, montagem, timeout e fallback genérico. O core interpreta solicitações de nova tentativa e executa a montagem novamente com limpeza; preserva a definição porque um módulo ESM em cache não é reavaliado ao ser importado outra vez.
O core reconhece retry e retry-with-longer-timeout no caminho de nova tentativa. O nome de uma ação retornada por um handler não altera uma URL ou um timeout por si só: configure e verifique o comportamento consumido pelo core. A classificação também usa nomes e fragmentos de mensagens de erro; mantenha o erro completo para poder diagnosticá-lo.
A função genérica registrada ao final dos handlers padrão aceita tudo. register() adiciona ao final, então um handler adicionado depois pode ficar atrás do genérico e não ser executado como o usuário esperava. Verifique a ordem antes de basear a recuperação de negócio em extensões desse sistema.
Testes do repositório
As suítes separam unidades do runtime, integração entre subsistemas e limites de segurança. Escolha o nível correspondente ao contrato que você está alterando:
npm run test:unit
npm run test:integration
npm run test:security
npm run test:coveragetest:package compila e executa o contrato de distribuição. test:mcp executa o pacote MCP separado. Uma suíte que importa src não comprova por si só que o pacote dist entrega as exportações/chunks corretos.
Uma regressão de registro deve executar WuCore e sua validação real. Você pode substituir o download do manifesto e o renderizador para controlar o cenário, mas um mock completo do core não verifica identidade, concessões nem limpeza. Para concorrência, adie a resposta do manifesto e inicie duas montagens antes de resolvê-la; verifique tanto o registro único quanto as referências de montagem.
Antes de publicar alterações do runtime, execute a suíte relevante e os testes de pacote no build que distribuirá.
Aceitação no navegador
Um teste útil do sistema poliglota monta pelo menos dois renderizadores, altera um estado compartilhado e verifica se ambos refletem o dado. Depois, desmonta um deles, emite novamente e confirma que seus callbacks não são executados. Por fim, remonta e verifica se não há listeners duplicados.
Para falhas de CSS, compare styleMode, folhas do ShadowRoot e propriedade. Para HMR ou produção, teste tanto o servidor Vite quanto os assets compilados. Para SSR, confirme que há conteúdo na primeira resposta e que a hidratação mantém esse DOM sem duplicá-lo.
Referência de implementação
Inspeção: src/core/wu-core.js; recuperação: src/core/wu-core.js; error boundary: src/core/wu-error-boundary.js e src/core/wu-error-boundary.js; wrapper: src/core/wu-app.js; detecção de duplicado: src/core/wu-core.js; scripts: package.json. Testes: tests/unit/final-hardening-regressions.test.js, tests/unit/shared-container-navigation.test.js, tests/unit/props-channel.test.js, tests/integration/multi-app-isolation.test.js.
Ao atualizar para 4.0, compare error.code, não textos de mensagens: erros do core usam códigos como WU_APP_NOT_REGISTERED, WU_CONTAINER_NOT_FOUND, WU_APP_NOT_DEFINED, WU_DEFINE_TIMEOUT e WU_CONTAINER_OCCUPIED. Contratos usam WU_CAPABILITY_*. O error boundary envia falhas irrecuperáveis diretamente ao fallback; não decide tentativas buscando palavras na mensagem.