Como testar o contrato entre consumidor e provedor de uma API

O que você vai levar deste guia

• Teste o que o consumidor realmente utiliza, com exemplos relevantes.
• Verifique o contrato contra a implementação do provedor em estados preparados.
• Relacione resultados às versões que serão publicadas e reconheça o que o contrato não cobre.

Identifique a discordância que precisa ser detectada

Um consumidor pode esperar um campo obrigatório que o provedor tornou opcional, ou interpretar um estado que mudou de significado. Os testes locais de cada serviço podem continuar passando porque usam exemplos diferentes. Comece escolhendo uma interação em que essa divergência teria impacto real. O objetivo é tornar a expectativa compartilhada verificável antes da publicação, sem exigir que toda a plataforma esteja executando em conjunto para cada alteração.

No exemplo fictício da empresa Atendimento Conectado, uma aplicação de planejamento consulta a API de disponibilidade de técnicos. O consumidor usa identificador, intervalo e motivo de indisponibilidade para decidir o que mostrar. Uma mudança no provedor altera a representação do motivo, e a interface deixa de oferecer uma mensagem útil. O contrato deve representar essa dependência concreta, não apenas afirmar que a resposta é um JSON válido.

Liste quem consome a operação e quais versões continuam em uso. Um endpoint pode atender aplicações que evoluem em ritmos diferentes. O teste precisa estar associado a consumidores reais e a seus estados relevantes. Não crie um contrato genérico sem dono que ninguém atualiza quando a interface muda. A expectativa deve nascer de uma necessidade do consumidor e ser verificada contra o comportamento do provedor.

Descreva exemplos que exercitem o consumidor

Escolha solicitações e respostas que fazem o consumidor executar caminhos importantes. Inclua disponibilidade encontrada, ausência de opções e erro que exige uma mensagem específica. O teste do consumidor deve chamar seu código real de integração, não apenas comparar um objeto escrito à mão com outro igual. Caso contrário, ele demonstra a consistência do teste consigo mesmo e não a dependência da aplicação.

Defina quais campos e formatos o consumidor realmente utiliza. Se ele ignora um campo adicional, não torne esse detalhe uma exigência rígida sem motivo. Acoplamento excessivo faz mudanças compatíveis parecerem falhas. Por outro lado, uma correspondência permissiva demais pode aceitar valores que quebram o comportamento. Escolha regras de correspondência que representem a necessidade, preservando restrições relevantes como presença, tipo e casos especiais. Confira também a diferença entre propriedade ausente, valor nulo e texto vazio: o consumidor pode usar cada situação para uma decisão diferente, e um exemplo que representa apenas uma delas deixa essa dependência sem verificação.

Na Atendimento Conectado fictícia, o consumidor precisa distinguir lista vazia de falha de consulta. Dois exemplos separados são necessários, porque a interface oferece continuidade diferente. Um único exemplo feliz não cobre essa expectativa. Evite preencher a suíte com muitas variações equivalentes enquanto estados importantes ficam ausentes. O conjunto deve ser pequeno o suficiente para manter e abrangente nas decisões que realmente dependem da resposta.

Gere o contrato a partir da interação testada

A documentação do Pact explica o fluxo em que testes do consumidor registram expectativas e a verificação do provedor confere essas interações contra sua implementação. Essa abordagem permite ligar as duas partes sem executar todos os serviços juntos a cada teste. O valor depende de os exemplos exercitarem o código relevante e de a verificação representar o comportamento real do provedor.

Mantenha o contrato como artefato associado à versão do consumidor. Não edite manualmente seu conteúdo para fazer a verificação passar se isso deixa o teste da aplicação desatualizado. A mudança precisa refletir uma expectativa legítima e ser acompanhada pelo comportamento correspondente. Registre nome do consumidor, versão e contexto necessário para localizar a origem do contrato quando surgir uma incompatibilidade.

Separe exemplos de dados de segredos e informações reais. Use identidades fictícias e estados preparados. O artefato pode circular por ferramentas de desenvolvimento e precisa conter apenas o necessário à interação. Não capture respostas de produção indiscriminadamente para transformá-las em contrato. Além de dados desnecessários, isso pode congelar detalhes acidentais que o consumidor não deveria exigir.

Prepare estados controlados no provedor

Para verificar uma interação, o provedor precisa estar em um estado que permita reproduzi-la. Defina preparação de dados para técnico disponível, período ocupado e recurso inexistente, por exemplo. A preparação deve ser confiável e isolada entre testes. Não dependa de registros que mudam em um ambiente compartilhado, porque falhas intermitentes reduzem a confiança e dificultam distinguir incompatibilidade de problema de teste.

Execute a verificação contra a implementação relevante, com dependências controladas conforme o escopo. Se uma dependência externa é simulada, registre a limitação e mantenha outras verificações para seu contrato. O teste do provedor não deve contornar justamente a lógica que precisa conferir. Um controlador substituído por uma resposta fixa pode passar sem demonstrar que a aplicação real produz o conteúdo esperado.

Na empresa fictícia, o estado de indisponibilidade inclui um motivo reconhecido e um intervalo específico. A verificação confere a resposta que o serviço realmente devolve nesse cenário. Se o motivo depende de uma regra de negócio complexa, testes próprios dessa regra continuam necessários. O contrato observa a fronteira e não substitui toda a validação interna do provedor.

Relacione compatibilidade às versões publicadas

Um resultado de verificação só é útil quando se sabe quais versões ele relaciona. Registrar apenas “contrato passou” pode misturar código antigo e expectativa nova. Identifique versão do consumidor, do provedor e do contrato. O processo de publicação precisa consultar evidências relevantes para as combinações que estarão em uso, incluindo clientes que ainda não foram atualizados.

Defina como mudanças propostas são introduzidas sem bloquear indevidamente toda evolução. Uma nova expectativa pode ser preparada enquanto o provedor ainda não a implementou, mas a publicação do consumidor deve respeitar a compatibilidade necessária. O fluxo concreto depende das ferramentas e da organização. O importante é que um contrato não verificado não seja confundido com uma garantia e que versões antigas continuem visíveis enquanto forem suportadas.

A Tironi Tech pode integrar essas referências aos processos de desenvolvimento para que a decisão de publicar use evidência atual. A configuração precisa evitar verificar contra a versão errada apenas porque é a mais recente em um ambiente. Compatibilidade é uma relação entre versões e interações, não uma propriedade absoluta de um serviço isolado.

Interprete falhas sem enfraquecer o contrato

Quando a verificação falha, descubra se houve quebra real, expectativa incorreta ou preparação inadequada. Não afrouxe a correspondência automaticamente para obter sucesso. Se o consumidor depende de um campo, removê-lo do contrato esconde a incompatibilidade. Se ele não depende, a exigência pode ser excessiva e deve ser corrigida com justificativa. A revisão precisa voltar à necessidade da aplicação.

Considere semântica além do formato. Um campo numérico pode continuar válido tecnicamente e mudar de unidade. Dependendo do exemplo e das verificações, o contrato pode não detectar toda alteração de significado. Documente unidades e use casos que exponham dependências relevantes, complementando com testes de negócio. Não anuncie proteção contra qualquer quebra apenas porque existe uma suíte de contrato.

Na Atendimento Conectado fictícia, um motivo de indisponibilidade passa a ser vazio em certos casos. A equipe verifica se a interface tem uma saída correta para isso e se o contrato deveria exigir o motivo. A resposta não é necessariamente restaurar o campo em todas as situações; pode ser ajustar a expectativa e o comportamento de forma coordenada. O teste serve para tornar a decisão explícita antes de afetar usuários.

Mantenha cobertura útil sem criar um espelho da API

Revise interações quando o consumidor muda. Um contrato abandonado pode continuar bloqueando alterações que ninguém precisa, enquanto uma nova dependência fica sem cobertura. Associe cada exemplo a um caminho real e remova exigências obsoletas conforme a política de versões. Não transforme a suíte em uma cópia de toda a documentação do provedor sem relação com o uso.

Agrupe exemplos por decisão do consumidor e mantenha nomes claros. “Sem técnico disponível no intervalo” ajuda mais que “teste 17”. Quando várias aplicações dependem da mesma operação, preserve suas expectativas distintas em vez de fundi-las em um contrato genérico impossível de atribuir. A verificação deve permitir identificar quem seria afetado e qual comportamento precisa ser discutido.

Equilibre com outras camadas de teste. Testes de unidade cobrem regras internas; testes de contrato verificam fronteiras representadas; um conjunto de jornadas integradas pode conferir sequência e efeitos completos. Evite duplicar tudo em todas as camadas sem necessidade. O desenho deve fornecer feedback útil com custo administrável, reconhecendo os limites de cada evidência.

Faça um piloto com uma mudança conhecida

Escolha uma interação e provoque uma alteração controlada em ambiente de desenvolvimento: remover um campo utilizado ou mudar uma condição representada. Confira que o teste detecta o problema e que a mensagem permite localizar a expectativa. Depois, faça uma mudança compatível, como acrescentar informação ignorada, e verifique que ela não falha sem motivo. Esse ensaio demonstra a sensibilidade e a tolerância do contrato.

Teste também a associação de versões e o processo de publicação. Uma suíte correta com metadados errados pode produzir uma decisão inadequada. Simule consumidor antigo e novo contra o provedor pretendido e confira o resultado consultado. Registre o procedimento para investigar falhas e quem mantém os estados de teste. A ferramenta só ajuda quando as equipes confiam que a evidência corresponde ao código que será entregue.

Finalize com o recorte coberto, os exemplos e as limitações. Amplie para outras interações quando houver benefício claro, sem adotar contratos por obrigação em toda chamada interna. O resultado esperado é uma conversa técnica mais concreta: esta versão precisa desta resposta nestes estados, e o provedor demonstrou ou não esse comportamento. Essa clareza reduz surpresas sem fingir que um teste de fronteira substitui o entendimento da jornada inteira.

Perguntas frequentes

Um arquivo OpenAPI substitui testes de contrato?

Ele descreve a interface e pode apoiar verificações, mas é necessário conferir comportamento e expectativas reais. O papel de cada artefato depende da estratégia adotada.

Devo incluir todos os campos retornados?

Não por hábito. Foque no que o consumidor depende e nas regras relevantes, evitando acoplamento desnecessário a detalhes que ele ignora.

Passar no contrato garante a jornada inteira?

Não. O teste cobre as interações e estados representados. Regras de negócio, sequência completa e comportamento sob falhas podem exigir outras verificações.

Evolua serviços com expectativas compartilhadas

A Tironi Tech pode desenvolver testes de contrato e integrações de publicação para que consumidores e provedores evoluam com evidências de compatibilidade.

Artigos relacionados

• Como mudar um campo de API sem exigir que todos os consumidores atualizem juntos
• Versionamento de API sem quebrar clientes: como evoluir contratos com compatibilidade e migração observável
• Observabilidade ponta a ponta de integrações: como seguir uma transação entre APIs, filas e sistemas

Fontes consultadas

• Pact — How Pact works