Visão

O modelo

Como se trabalha

A plataforma

Origem e rumo

Decisões

Este repositório
Começar
Aparência

Vale na hora e fica lembrada neste navegador.

Como se trabalha

10 · Testes

Três camadas. As duas primeiras usam as ferramentas da linguagem da stack (lacuna); a terceira é igual em toda stack. O que é comum a todas: TDD, dependências reais em container e um comando que roda tudo.

As três camadas

As três camadas de teste numa pirâmide: na base, a unidade — regras puras, sem rede nem container, em milissegundos; no meio, a integração — teste de rota, persistência com banco real e o fio com Keycloak e coletor em container; no topo, o fim a fim — Playwright e um navegador real com as aplicações no ar. Unidade e integração usam as ferramentas da stack; o fim a fim é igual em toda stack. fim a fimnavegador realintegraçãorotas · banco real · Keycloak e coletorunidaderegras puras · sem rede · milissegundosigual emtoda stacke2e/, Playwrightferramentasda stackno módulomais lento, mais realista
CamadaO que provaVelocidadeRoda emFerramentas
UnidadeO que prova: uma regra isoladaVelocidade: msRoda em: build, CIFerramentas: lacuna ({{LACUNA:testes.unidade}})
IntegraçãoO que prova: uma parte real do sistema contra dependências reais; inclui o teste de rotaVelocidade: sRoda em: build, CI (precisa de Docker)Ferramentas: lacuna ({{LACUNA:testes.integracao}})
Fim a fimO que prova: o usuário consegue, numa tela, de ponta a pontaVelocidade: s–min por casoRoda em: estação de trabalho (CI opcional)Ferramentas: Playwright + Node (fixo)

O teste de rota é o de integração mais comum: uma requisição HTTP atravessa, dentro do processo, o roteamento, a segurança e a resposta de uma aplicação, com usuário simulado e sem rede. Prova status, permissão e redirecionamento. Toda linguagem tem a sua ferramenta para isso; a da stack fica na ADR-0003 dela.

O que é fixo nas camadas de unidade e integração

Mesmo sem saber a linguagem, o modelo já decide:

  1. Um comando roda unidade + integração (ex.: ./gradlew build, npm test, dotnet test) e é o mesmo na máquina e na CI;
  2. Dependências reais em container (Testcontainers ou equivalente da linguagem). Nada de banco em memória que finge ser outro (H2 no lugar de PostgreSQL), nem servidor OIDC falso para provar o fio com o Keycloak;
  3. A imagem do Keycloak nos testes é a mesma do compose.yaml e do toolbox — conferido por eng/pinned-versions.sh;
  4. Suporte de teste por aplicação (helpers de login, containers): duplicar um pouco é aceitável; extrair um módulo de suporte só quando a duplicação doer;
  5. Recortes documentados no docs/guias/testes.md: só unidade (sem Docker), um módulo, uma classe, um teste;
  6. Contratos da plataforma têm teste de integração em toda aplicação:
    • identidade: rota protegida redireciona ao Keycloak; sem permissão → 403 explicativo; logout encerra a sessão no Keycloak;
    • observabilidade: log JSON com traceId; métricas só na porta interna; /up sem autenticação; coletor fora do ar não derruba requisição;
    • aviso de ambiente: aparece fora de production.

Tempo de suíte

O Keycloak em container leva ~50 s para subir sozinho e mais de 3 min com vários em paralelo numa máquina de 4 CPUs — o startup é limitado por CPU. Regras:

  • poucos testes de integração com Keycloak (o fio, não as regras), com espera generosa (6 min) e reuso do container dentro do módulo;
  • regras de acesso testadas no teste de rota, com usuário simulado, não no Keycloak real;
  • se a suíte ficar lenta, separar por tag (unidade, integracao) é mudança de configuração, registrada no guia.

Fim a fim

O E2E tem documento próprio: 11 · Testes fim a fim hierárquicos.

Em resumo:

Uma corrida do E2E: escolhe-se o que rodar (tudo, um agrupamento, um cenário ou um caso); os setups dos níveis necessários rodam uma vez; os casos rodam independentes entre si; saem as capturas, se ligadas, e o relatório em árvore com o trace das falhas. seleçãotudo, agrupamento,cenário ou casosetupsem cascata, só osnecessários, uma vezcasosindependentesentre sicapturasse ligadasrelatórioem árvore, com otrace das falhas

Matriz de quando rodar cada coisa

MomentoUnidadeIntegraçãoE2E
A cada tarefa do tasks.md (ciclo TDD)Unidade: o teste da tarefaIntegração: o teste da tarefaE2E: o caso da tarefa, se ela muda uma tela
Ao terminar um grupo de tarefasUnidade: móduloIntegração: móduloE2E: casos da change
Ao terminar a changeUnidade: tudoIntegração: tudoE2E: regressão: tudo, do zero
CI (push)Unidade: tudoIntegração: tudoE2E: opcional (ADR da stack)
Antes de um deployUnidade: — (a CI já rodou)Integração: —E2E: regressão na estação do mantenedor

Roteiro manual

Um roteiro manual em prosa ao lado de um roteiro automatizado que o traduz são dois artefatos que se desencontram a cada change.

No modelo há uma fonte só: o caso E2E narra os próprios passos (step('…')), e eng/e2e.sh --walkthrough gera o roteiro legível a partir deles — em Markdown, por agrupamento e cenário, para quem quer conferir com as próprias mãos.