Como testar regras de negócio sem API com Arquitetura Hexagonal
Descubra como separar verdadeiramente sua lógica de negócio para garantir testes mais rápidos e independentes, sem interagir diretamente com APIs.
Por que isso é importante
Arquitetura hexagonal te dá liberdade. Quando você separa regras de negócio do resto da infraestrutura, ganha velocidade para testar, clareza para evoluir e poder para adaptar o produto sem medo. Quem só depende da API para garantir que tudo funciona está perdendo agilidade e gastando tempo à toa. Tornar a regra de negócio uma camada isolada significa ciclos de feedback mais rápidos, código mais limpo e menos dependências.
Sua regra de negócio não precisa da API para ser testada
A maioria ainda acha que só dá para garantir a qualidade do sistema com testes end-to-end, via API. Só que, se você depender do seu endpoint, toda mudança vira um evento grande e demorado. Separando a lógica de negócio da camada de entrada, a validação acontece de forma direta: rápida, objetiva e confiável.
⚠️Atenção
Ignorar a separação gera testes lentos, difíceis de manter e aumenta acoplamento. Não caia nessa armadilha.
O que é Arquitetura Hexagonal: separação real entre camadas
Na Arquitetura Hexagonal (também chamada de Ports and Adapters), a ideia é clara: o núcleo do seu sistema — a regra de negócio — não conhece detalhes de frameworks, banco de dados ou rotas. Esse núcleo conversa com o mundo externo apenas por interfaces bem definidas. Assim, seu código fica testável isoladamente e adaptável a qualquer tecnologia ou interface, seja API, fila, CLI ou interface gráfica.
ℹ️Dica Técnica
Implemente interfaces para abstrair dependências. Isso permite trocar APIs, bancos ou serviços externos sem mexer na lógica central.
Testar direto: sem passar pela API, sem gambiarra
Ao separar o código da aplicação, você testa a lógica pura usando unit tests simples, focados apenas no que importa. Não há necessidade de requests HTTP, mocks complexos ou infraestruturas extras.
✅Prático
Basta chamar a função da sua regra de negócio, passando os parâmetros desejados, e validar os resultados. Sem middlewares, autenticação ou delays desnecessários.
Passo a passo: criando a camada Application
Dentro da sua pasta SRC, crie uma pasta chamada Application. Essa pasta irá concentrar toda lógica central do negócio. Lá, adicione arquivos que representam casos de uso (ex: CreateEvent.ts). Nomes em PascalCase para indicar que este arquivo pode ser uma classe ou função no futuro.
ℹ️Alerta
Mesmo que hoje você use funções, adote estruturas nomeadas e separadas. Isso facilita manutenção e evolução.
Como estruturar um caso de uso
O arquivo CreateEvent.ts pode ser uma função, classe ou service que encapsula toda lógica para criar um evento. Ele recebe apenas os dados necessários, valida, executa ações e retorna respostas — tudo sem saber que existe uma API.
Teste a lógica de negócio sem medo
Agora você pode escrever testes específicos, sem mocks pesados ou dependências externas. Mudou a regra? Testa de novo, com feedback instantâneo.
⚠️Atenção
Testes “acoplados” à API escondem bugs e tornam refatorações muito mais arriscadas.
Evite armadilhas: nunca misture camadas de responsabilidade
Confundir regras do domínio com detalhes de comunicação espalha lógica e duplica problemas. Mantenha sempre a separação: regra de negócio fica no núcleo, adaptação no entorno.
Padrão de nomenclatura: clareza e evolução
Use nomes compostos em PascalCase (ex: CreateEvent, EditBooking). Essa escolha facilita a transição para classes, serviços, testes automatizados e documentação futura.
Portas e Adaptadores: conectando com segurança
Ao precisar acessar outros serviços (API, DB, email), faça-o via adaptadores desacoplados. Assim, mudanças no ambiente externo não impactam sua lógica principal.
ℹ️Dica Extra
Implemente interfaces para cada dependência externa. Isso permite mocks inválidos apenas na camada correta.
Automatize seus testes: menos dor, mais valor
Com a lógica isolada, automatizar testes se torna natural e veloz. Rode milhares de casos, valide exceções e garanta cobertura total sem esperar respostas de API.
✅Eficiência
Feedback rápido = produto melhor e menos bugs em produção.
Mudança de mentalidade: foco no que importa
Quando seu escopo de validação é a lógica pura, seu foco está no que realmente agrega valor. A API vira apenas uma “porta de entrada”, nunca o centro do sistema.
Aumente a legibilidade do seu código
Com camadas bem divididas, todo o time entende o fluxo, contribui com confiança e reduz risco de bugs silenciosos.
⚠️Alerta
Acúmulo de lógicas distintas em arquivos confunde e dificulta integração. Separe sempre.
Resultado: mantenha seu projeto sob controle
Separar regra de negócio de detalhes externos é investir na saúde do seu sistema. Você ganha testes rápidos, código limpo e evolução sem medo.
Assista: explicação e exemplos práticos em vídeo
Quer ver essa mesma arquitetura em ação? No canal Dev Doido no YouTube você encontra exemplos detalhados e demonstrações práticas. Veja os conceitos em um projeto real.