Manual de Testes LZR
Versão 1.0 — 2026-06-20. Consolida em um lugar só todas as regras de teste que antes viviam espalhadas (a pasta de padrões de teste, a seção de testes da central e os pedaços nos modelos de projeto).
O que este manual responde: como eu provo que funciona. Tudo que é "como eu construo certo" mora no Manual de Código.
Regra de ouro deste acervo: cada regra mora em um lugar só. Quando uma regra depende de outra, ela aponta — nunca copia.
Quanto deste manual é obrigatório depende do porte do projeto — ver Níveis de Exigência. O piso (toda lógica nova nasce com teste) vale para todos; integração, ponta a ponta e os testes mais pesados sobem com o nível.
Princípio
A rede de testes é o que dá dente a tudo: sem ela, o "nada sobe com defeito" da qualidade e o "sobe sozinho" da publicação não teriam como existir. É o verificador adversário da casa — e roda de graça, sem depender de IA.
1. Código novo nasce com teste
Toda funcionalidade nova vem com o seu teste, desde o dia 1. A rede de testes cresce junto com o projeto. Nada de "testa depois" — que vira "depois nunca". A contagem de testes do projeto sobe a cada entrega.
Em termos concretos: todo arquivo novo de serviço, de gancho (hook) e de biblioteca interna tem teste. O vigia de testes barra mudança de lógica sem teste correspondente.
2. Escreva o teste antes (teste-primeiro)
Quando for construir uma capacidade nova, primeiro escreva o teste que descreve o que ela deveria fazer — ele falha, porque a capacidade ainda não existe. Depois construa até o teste passar.
Isso transforma o teste de "tarefa do fim" em "bússola do começo": você define o alvo verificável antes de codar, e sabe exatamente quando terminou. A ordem é: teste que falha → implementação → teste verde.
3. Cobre o que dá certo E o que dá errado
Testar o uso normal e as situações ruins: dado inválido, abuso, sem permissão, limites. É aqui que mora a robustez e a segurança — conecta com "nunca confiar no que chega" do Manual de Código §8.
4. Critério de aceite em "dado / quando / então"
Toda tarefa termina a descrição com cenários de aceite concretos no formato:
Dado que o cliente está sem saldo, quando ele tenta confirmar, então o sistema bloqueia e avisa.
Esses cenários viram os testes — de ponta a ponta e de regra de negócio. O fluxo é: a tarefa descreve os cenários → o teste nasce a partir deles → a implementação vai até todos passarem. É a ponte entre o que foi pedido e o que foi provado.
5. As camadas de teste
| Camada | O que cobre | Quando é obrigatória |
|---|---|---|
| Rápido (isolado, dependências externas simuladas) | Lógica isolada de serviços, ganchos e bibliotecas internas | Sempre, para todo serviço/gancho/biblioteca |
| Regra de negócio | As invariantes do domínio — o que nunca pode acontecer, os limites, as regras que vêm do negócio | Sempre que houver regra de domínio (não diluir no teste rápido) |
| Integração (banco de verdade, local) | As partes conversando entre si, a separação de clientes, as migrações | Toda feature multi-cliente |
| Ponta a ponta | O caminho principal do usuário, no navegador real contra o aplicativo real | Para o caminho de ouro de cada aplicativo |
A camada de regra de negócio tem nome próprio de propósito: as regras do domínio (os limites, as invariantes) são onde mora o risco real e precisam ser testadas por si, não escondidas dentro do teste rápido.
Mocks mentem: serviço crítico (pagamento, separação de clientes, webhook) tem teste de integração além do teste rápido. Um teste isolado com o banco simulado passa mesmo com a proteção por linha quebrada — só o banco de verdade pega.
A suíte de ponta a ponta é enxuta de propósito (caminho de fumaça + caminhos críticos), para rodar em segundos e raramente quebrar por instabilidade. Cobertura ampla é trabalho do teste rápido.
Camadas adicionais por contexto (opcionais por nível — ver Níveis de Exigência):
| Camada | O que cobre | Quando considerar |
|---|---|---|
| Acordo entre partes | Que os dois lados de uma interface concordam no formato dos dados que trocam | Produto com múltiplos serviços ou quando a quebra de contrato entre partes é risco real |
| Acessibilidade | Que a interface respeita as regras de acessibilidade (WCAG AA) | Nível Crítico e projetos com exigência explícita de acessibilidade |
| Migração | Que cada passo de mudança de estrutura do banco aplica e reverte corretamente | Sempre antes de publicar mudança de estrutura em produção |
| Carga | Que o sistema aguenta o volume esperado de uso sem degradação | Onde há pico de uso previsível ou contrato de desempenho |
6. Cobertura: catraca trava, maturidade mede
Cobertura cumpre dois papéis diferentes — e tratá-los como a mesma coisa foi o que gerou contradição no passado. Eles convivem:
- A catraca é a trava do dia a dia. A cobertura parte de onde o projeto está e só sobe, nunca desce. Não se exige um piso alto de cara (um piso alto quebraria projeto novo ou herdado no primeiro dia); um piso baixo demais também não serve. Quando entra teste e a cobertura sobe, o limite sobe junto. É proteção contínua contra regressão.
- O 80% é a régua de maturidade. Serve para responder "este projeto já está completo?" — é o alvo aspiracional (mirar 70–85% no geral, 90%+ nas camadas críticas), e é o que a avaliação de projeto mede. Não é uma trava que bloqueia projeto novo.
Em resumo: a trava de subida é a catraca; o alvo de maturidade é o 80% (crítico em 90%+). Não perseguir 100% — código trivial (telas estáticas, tipos) fica de fora; o foco é o crítico (dinheiro, entrada no sistema, dado de cliente).
Cobertura de linha não é suficiente por si. Um teste pode tocar 100% das linhas sem pegar nenhum erro. A medida complementar é a cobertura de mutação — o verificador injeta um erro de propósito (troca > por >=, muda um retorno, apaga uma condição) e confere se o teste detecta. Em camadas críticas, mirar ≥ 80% de mutantes pegos.
7. Testes confiáveis
Testes estáveis (sem falha aleatória) e independentes (a ordem não importa). Teste instável é tratado como bug, não ignorado.
Quarentena de teste instável: ao detectar um teste que falha de forma aleatória, o processo é: (1) isolar — marcar com rótulo de quarentena e tirar da suíte bloqueadora; (2) investigar — encontrar a causa (concorrência, dependência de estado global, ordem de execução, dependência de tempo); (3) resolver em até 3 dias úteis — consertar e reintegrar; (4) se não resolver no prazo, remover o teste e registrar como dívida técnica o que ele cobria — para voltar como teste estável depois. Nunca simplesmente ignorar um teste instável.
8. Teste de separação de clientes
Em produto multi-cliente, a proteção de acesso por linha (RLS) é o único mecanismo que impede o vazamento entre clientes. Um defeito numa regra de acesso = um cliente vê o dado de outro. Por isso, é obrigatório teste de integração real (banco de verdade, sem simulação) cobrindo, para cada tabela com dono:
- Leitura cruzada entre clientes → retorna vazio
- Escrita com o identificador de outro cliente → erro
- Atualização/remoção de registro de outro cliente → nenhuma linha afetada
- Acesso total (super-admin) enxerga tudo, quando aplicável
- Usuário órfão (sem empresa e sem papel de acesso total) continua bloqueado — é o cenário que prova o fechamento da brecha de controle de acesso; não pode faltar
- Revogar o papel de acesso total derruba o acesso imediatamente (sem cache, sem validade pendente)
A regra de segurança que isso protege mora no Manual de Código §6. Aqui fica o como provar.
9. Teste vermelho trava a entrega
Teste falhando barra a subida, automaticamente — o vigia roda a suíte na máquina e antes de publicar. Isso é parte da tolerância zero a defeito, cuja regra-mãe está no Manual de Código §4.
Quando um teste pega um erro, conserta-se o código — não se afrouxa o teste. A única exceção é quando o próprio teste está errado (descreve um comportamento que não é mais o esperado); aí o ajuste é no teste, justificado.
10. Projeto novo nasce com a rede montada
Todo projeto novo já nasce com a fundação de teste de ponta a ponta montada (caminho de fumaça + caminho crítico, com sessão reusada e bloqueio na publicação). O modelo de projeto já vem com isso pronto — o coder não monta do zero.
11. Blindagem automática (enforcement)
Camadas automáticas garantem que o código obedece os padrões sem depender de ninguém lembrar. Incluem a auditoria de design, a validação de tokens, a catraca de etiquetas HTML cruas e a regra de lint que proíbe elemento cru fora da biblioteca de UI.
As regras de identidade visual que essas camadas defendem moram no Manual de Design. Aqui fica só o fato de que existe blindagem automática e como o vigia opera.
12. Proibições (o que nunca se faz com testes)
- Nunca deletar teste para fazer o bloqueio passar. Falha de teste significa bug no código (ou, raramente, teste que descreve comportamento que mudou — com justificativa explícita). Teste que some sem razão é regressão invisível.
- Nunca simular o banco onde o banco de verdade é o que importa. Em serviços críticos (pagamento, separação de clientes, webhook), a proteção real (RLS, transação, idempotência) só aparece com banco real — o simulado aprova o que o banco rejeitaria.
- Nunca aceitar teste instável como normal. Flakiness é bug. Processo de quarentena em §7.
- Nunca perseguir 100% de cobertura. Código trivial, telas estáticas e tipos ficam de fora de propósito; o foco é o crítico. Detalhe em §6.
- Nunca deixar o destino de um teste depender da ordem de execução. Cada teste parte do zero, limpa o que criou e não assume estado deixado por outro.
Fronteiras deste manual: "como construo" → Manual de Código. Identidade visual → Manual de Design.