# 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](/pt/docs/guides/releases/).


<span id="empieza-por-la-fase-que-falló"></span>

<span class="section-anchor" id="section-1"></span>

## Comece pela fase que falhou

```js
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.

<span id="tabla-de-síntomas"></span>

<span class="section-anchor" id="section-2"></span>

## 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 |

<span id="resolver-conflictos-de-identidad-y-arranque"></span>

<span class="section-anchor" id="section-3"></span>

## 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:

```js
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](/pt/docs/framework/lifecycle/) 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.

<span id="recuperación-de-montaje"></span>

<span class="section-anchor" id="section-4"></span>

## 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.

<span id="pruebas-del-repositorio"></span>

<span class="section-anchor" id="section-5"></span>

## 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:

```bash
npm run test:unit
npm run test:integration
npm run test:security
npm run test:coverage
```

`test: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á.

<span id="aceptación-en-navegador"></span>

<span class="section-anchor" id="section-6"></span>

## 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.

<span id="referencia-de-implementación"></span>

<span class="section-anchor" id="section-7"></span>

## 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.