Teste de Contrato de API

Visão Geral

Transforme uma mudança de API em verificações explícitas de provedor e consumidor. Comece pelo contrato real e pelos clientes afetados, e então verifique o comportamento no nível da rede em vez de depender de tipos gerados ou de uma compilação bem-sucedida. Use por padrão fixtures locais e ferramentas de teste existentes; esta habilidade não provisiona um serviço de teste.

Quando Usar

• Um campo de resposta, endpoint, esquema de evento ou envelope de erro muda.
• Um cliente e um servidor compilam com sucesso, mas discordam em tempo de execução.
• Uma equipe precisa distinguir uma mudança que quebra a compatibilidade de uma extensão compatível.
• Uma regressão reportada precisa de uma reprodução mínima de provedor/consumidor.

Não use isso como autorização para chamar endpoints de produção, contornar controles de acesso ou publicar uma nova versão de API.

Como Funciona

1. Vincule o contrato e o escopo

Identifique o provedor, o transporte, a fonte do contrato e a versão, os consumidores conhecidos e o comportamento solicitado. Leia a definição real de OpenAPI/JSON Schema/protobuf ou exemplos documentados e o código correspondente do servidor/cliente. Registre consumidores ausentes e especificações desatualizadas como lacunas de cobertura; não invente interfaces ou reivindique cobertura completa de um único cliente.

Mantenha estes distintos: esquema documentado, saída real do provedor, tipos de cliente gerados e análise em tempo de execução. Uma simples asserção de tipo não é validação. Preserve o protocolo existente e o runner de teste em vez de introduzir uma nova plataforma por padrão.

2. Classifique a mudança

Revise campos, obrigatoriedade, nulidade, valores de enum, códigos de status, cabeçalhos, tipo de conteúdo, paginação e comportamento de erro. Inspecione se os clientes toleram campos extras e valores de enum desconhecidos. Mesmo um campo opcional adicionado pode quebrar um consumidor rigoroso. Identifique explicitamente as versões afetadas e as suposições antes de chamar uma mudança de compatível.

Para eventos, inclua entrega duplicada, ordenação e envelopes de versão. Para mudanças de requisição, verifique a serialização e a validação do servidor, bem como as respostas.

3. Construa uma pequena matriz de teste

Use fixtures sintéticas determinísticas para:

• Sucesso válido, incluindo valores opcionais e vazios.
• Campos obrigatórios ausentes, tipos incorretos e nulos explícitos.
• Campos extras e enums desconhecidos de acordo com a política de compatibilidade real.
• Envelopes de erro declarados, status não-sucesso e corpos malformados.
• Consumidor antigo contra provedor novo e consumidor novo contra provedor antigo retido, onde essas combinações são suportadas.

Afirme o comportamento prometido pelo contrato. Não coercion silenciosamente valores malformados ou faça a fixture corresponder a um defeito apenas para obter um teste aprovado.

4. Verifique cada limite

Execute o validador de esquema existente contra as fixtures. Exercite o manipulador do provedor localmente e passe seu resultado serializado pelo parser real do consumidor. Verifique se os casos de falha rejeitam ou mapeiam erros conforme especificado. Use um ambiente de integração isolado autorizado apenas quando as fixtures não puderem estabelecer a propriedade necessária; relate esse limite explicitamente.

Um mock verifica as suposições codificadas no mock. Ele não estabelece que o provedor real as implementa. Registre os comandos exatos, as versões das fixtures e os resultados observados separadamente das verificações não executadas.

5. Relate e entregue

Entregue a classificação da mudança, os consumidores afetados, a matriz de teste, as falhas observadas, a reprodução mínima e as lacunas de cobertura restantes. Para uma mudança que quebra a compatibilidade, proponha versionamento, um adaptador de compatibilidade ou uma migração em estágios com proprietários e critérios de rollback. Implantação e migração de consumidores requerem sua própria autorização de tarefa.

Exemplo

Resposta sintética documentada:

{"id":"invoice-demo","amount_minor":1250,"currency":"EUR"}

Contrato: id e currency são strings; amount_minor é um inteiro não negativo em unidades menores. Esta fixture não representa um cliente ou pagamento real.

Prompt reutilizável:

Revise esta mudança de API contra o contrato real e o código de cliente/servidor fornecido.

…