Pirâmide de testes na prática: como duas ADRs padronizaram a qualidade

Testes só protegem de verdade quando todo mundo segue as mesmas regras. Quando apoiei a padronização de testes na empresa, a resposta foi escrever essa decisão em duas ADRs (Architecture Decision Records), uma para backend e outra para frontend, e usar a pirâmide de testes como referência de quanto testar em cada nível.

Por que padronizar

Sem um padrão, cada projeto escolhe o seu jeito, e isso tem custos conhecidos:

• Revisões que discutem formato de teste em vez de comportamento.
• Qualidade imprevisível: não dá para confiar que um projeto novo nasce com uma rede de segurança.
• Onboarding mais lento: quem entra precisa descobrir as convenções de cada repositório.

Em um contexto anterior, vi o outro lado: várias aplicações com cobertura de testes zero que levei para mais de 80%. O que faltava agora era evitar que os projetos nascessem sem essa base.

O que as ADRs definem

Em vez de um guia genérico, as ADRs são objetivas e definem:

• Os três níveis de teste: unitários, de integração e end-to-end, todos presentes nos projetos novos.
• O padrão AAA (Arrange, Act, Assert): todo teste segue a mesma estrutura, o que torna a leitura previsível.
• Jest como ferramenta padrão, no backend e no frontend, para que configuração e vocabulário sejam os mesmos.
• Playwright para os testes end-to-end do frontend: é uma diferença importante entre as duas ADRs. O Playwright abre a aplicação em um navegador de verdade, navega pelas páginas, clica nos elementos e valida as funcionalidades como uma pessoa usuária faria, automatizando o teste de ponta a ponta. Isso está definido exclusivamente na ADR de frontend.
• Execução no GitHub Actions: como rodar testes unitários e de integração na esteira, de forma padronizada.
• Estrutura de pastas: onde cada tipo de teste mora, para que qualquer pessoa encontre o que procura em qualquer projeto.

A pirâmide de testes como guia de quantidade

De onde vem o conceito

A pirâmide de testes (test automation pyramid) foi popularizada por Mike Cohn no livro Succeeding with Agile (2009). Na versão original, as camadas eram Unit, Service e UI; hoje, é comum mapeá-las para testes unitários, de integração e end-to-end (e2e). A ideia central tem duas regras:

1. Escreva testes em granularidades diferentes.
2. Quanto mais alto o nível, menos testes você deve ter.

A razão é prática: testes de alto nível (que passam pela interface ou por vários serviços) são mais lentos, mais caros de manter e mais frágeis (flaky), enquanto os unitários dão feedback em milissegundos e apontam exatamente onde está o problema. A orientação do Google Testing Blog segue a mesma linha: manter o formato de pirâmide, com poucos testes e2e, e deixar a proporção exata para cada time.

As proporções

Uma regra prática muito citada na indústria é a divisão 70/20/10: cerca de 70% de testes unitários, 20% de integração e 10% de end-to-end. Não é lei: o próprio Martin Fowler trata a pirâmide como uma heurística, e ressalta que, se testes de alto nível forem rápidos, confiáveis e baratos de mudar, a conta pode mudar. Mas, como ponto de partida, a proporção é útil, e foi o que adotamos como referência.

O insight veio depois de alguns meses, vendo a suíte crescer: a pirâmide não é teoria, ela descreve a realidade. Escrevemos muitos testes unitários de forma natural, porque são rápidos e baratos. Conforme subimos de nível, cada teste já integra tudo o que está abaixo dele, então precisamos de menos. A quantidade vai diminuindo de forma orgânica.

Por isso passei a usar a pirâmide dentro das ADRs: não como regra rígida, mas como forma de indicar às pessoas a proporção esperada em cada nível, sem ninguém precisar adivinhar quantos testes de cada tipo escrever.

"Mas qual o valor dos testes unitários?"

Uma pergunta que ouvi de um colega foi justamente essa. Na experiência dele, o valor estava nos testes de integração e end-to-end, porque nunca tinha trabalhado de verdade com testes unitários. É uma dúvida legítima, e a conversa foi mais útil do que qualquer documento:

• São os testes mais baratos de escrever, rodar e manter, seja o código escrito por uma pessoa ou com ajuda de IA.
• Dão o feedback mais rápido: você descobre o problema em segundos, ainda enquanto desenvolve, e não depois de subir um ambiente inteiro.
• Protegem as regras de negócio: mexer em um ponto do código pode quebrar, sem ninguém perceber, uma regra que parecia não ter relação. O teste unitário aponta exatamente onde isso aconteceu.
• Sustentam a qualidade do código ao longo do tempo, porque dão segurança para refatorar e evoluir.

Com o passar do tempo e com essa mudança de mentalidade, o colega passou a enxergar o valor deles. Testes de integração e e2e continuam essenciais, mas eles se apoiam na base: quanto mais confiança nos unitários, menos precisamos depender dos testes caros lá em cima.

O que mudou na prática

Hoje, os projetos novos da empresa já nascem com testes unitários, de integração e end-to-end seguindo esse padrão:

• Mais confiança nas entregas, porque o código é validado contra as funcionalidades esperadas.
• Revisões mais focadas, já que o formato dos testes não está mais em discussão.
• Desenvolvimento agêntico mais preciso: com convenções claras e testes confiáveis, agentes de IA conseguem seguir o padrão e validar o que geram. O mesmo vale para ajustes manuais, que passam a ter uma rede de segurança.

Lições

1. Padronize a decisão, não só a ferramenta. Jest e Playwright ajudam, mas o que alinha o time é a ADR.
2. Use a pirâmide para indicar proporção, não só para ensinar teoria.
3. Estrutura de pastas e esteira são parte da qualidade, não detalhe.
4. Bons testes servem a pessoas e a agentes. Convenções explícitas reduzem erros dos dois lados.

Perguntas frequentes

Qual a proporção ideal da pirâmide de testes?

Uma regra prática muito citada é 70% de testes unitários, 20% de integração e 10% de end-to-end. Não é lei: serve como ponto de partida, e o importante é manter o formato de pirâmide, com menos testes a cada nível acima.

Por que os testes unitários são a base da pirâmide?

Porque são os mais baratos de escrever, rodar e manter, dão o feedback mais rápido e protegem as regras de negócio quando alguém altera o código, seja uma pessoa ou uma IA.

Quais ferramentas as ADRs de testes definem?

Jest como ferramenta padrão no backend e no frontend, o padrão AAA (Arrange, Act, Assert), execução dos testes unitários e de integração no GitHub Actions e Playwright para os testes end-to-end do frontend.

Por que usar uma ADR para padronizar testes?

Porque a ADR registra a decisão, o contexto e as consequências no próprio repositório. Isso reduz discussões repetidas e dá um ponto de partida claro para evoluir o padrão.

Referências

• TestPyramid, Martin Fowler
• The Practical Test Pyramid, martinfowler.com
• Just Say No to More End-to-End Tests, Google Testing Blog