Teste de API contratual

1) Porquê testes contratuais

O contrato registra as expectativas do cliente e promessas do provedor, como rotas/métodos, cabeçalhos, esquemas corporais, estatais, semânticas de erros e limitações. O objetivo é capturar mudanças incompatíveis antes da integração e produzir versões em segurança, sem E2E pesado.

2) Abordagens

CDC (Consumer-Driven Comands): o cliente cria expectativas (Pact e similares); O provedor confere-os regularmente.
Especificação: contrato como uma única fonte de verdade (OpenAPI/Protobuf/GraphQL SDL); os testes validam a implementação contra a especificação.
Evento: esquemas de mensagens (Avro/JSON Schema/Protobuf) + regras de compatibilidade no corretor/registro.

3) HTTP/REST: fluxo de especificação

1. Contrato: OpenAPI 3. x (esquemas, exemplos, códigos).
2. Lente e análise de estilo, campos obrigatórios, códigos unificados.
3. Validação de implementação: gerador de testes anti- OpenAPI (schemathesis/Dredd) + negativo manual.
4. Snapshots: Registre exemplos de respostas, semântica ETag, cabeçalhos de idempotação.

yaml paths:
/v1/payments:
post:
responses:
"201": { $ref: "#/components/responses/PaymentCreated" }
"409": { description: Duplicate by Idempotency-Key }
"422": { description: Schema/Business validation failed }

4) CDC (abordagem Pact)

1. O Consumer está escrevendo um teste, formando um arquivo pact (espera).

2. Publicação em corretor (artefato).

3. Provider em CI eleva o serviço (ou contrato-balcão), confere pact' s.

4. O corretor calcula a matriz de compatibilidade can-i-deploy.

js pact
.given("wallet exists")
.uponReceiving("get wallet")
.withRequest({ method:"GET", path:"/v1/wallets/w123", headers:{ "Authorization": term({generate:"Bearer x", matcher:/^Bearer\s.+/}) }})
.willRespondWith({
status: 200,
headers: { "Content-Type": "application/json" },
body: like({ id:"w123", currency: "EUR", balance: 0 })
});

5) gRPC/Protobuf contratos

O contrato é '.proto' com a versionização de pacotes/serviços.
Compatibilidade: não reutilizar marcas de formatação, apenas adicionar novas com optional, não excluir campos usados; reservar quartos.
Testes: geração de stab do servidor/cliente, aluguel de malas autogeradas + negativos (unknown fields, size-limits).

6) Contratos de eventos (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
Política de compatibilidade «BACKWARD» (muitas vezes suficiente) ou «FULL».
Testes do provedor: valida a mensagem contra o esquema; Testes de combinação: aceita versões antigas e novas.
Invariantes: chaves de idempotação, ordem/repetência, semântica de dedução.

json
{"type":"record","name":"PayoutCreated","fields":[
{"name":"payoutId","type":"string"},
{"name":"amount","type":"double"},
{"name":"currency","type":{"type":"string","logicalType":"iso-4217"}}
]}

7) Compatibilidade e versões

Backward-compatível (mínimo recomendado): Adicione campos opcionais, não rompa os campos existentes.
Forward-compatível: Os consumidores ignoram campos desconhecidos.
Full: Ambos.
Versioning: 'path (/v1)', 'Accept: aplicação/vnd. brand. v2+json`, `proto package v2`.
Política Deprecation: janela de saída (por exemplo, 90 dias) alertando cabeçalhos/eventos.

8) Negativo e erros - também é um contrato

Normalize os códigos: 400/401/403/404/409/422/429/5xx, campos obrigatórios de 'código', 'mensagem', 'trace _ id'.
As dimensões/limites fazem parte do contrato (413/414/431).
Idempotidade: comportamento de repetição (409 vs 201 same id).
Títulos: «Retry-After» a 429/503, «Idempotency-Key», «Conteúdo-Language» etc.

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"..." }

9) Os dados gerenciam o contrato

Exemplos/respostas primitivas (examples) são vivas, valendo-se em CI.
Ficturas para CDC são mínimos, determinados.
Geração de dados - property-based para números/datas; mas não quebrar a estabilidade dos snapshots.

10) Pipeline em CI/CD (árbitro)

1. Lint/validate: OpenAPI/Proto/Avro (`validate`, style-линер).
2. Publish: contrato como artefato (corretor/registro).
3. Verify: O provedor executa pacotes CDC/testes de especificação.
4. can-i-deploy gate: sem matriz verde, o lançamento é proibido.
5. Diff: verifique se as alterações são compatíveis (semantic diff).
6. Relatório: JUnit/HTML, lista de violações/descrições.

yaml jobs:
lint:...
publish-contract: needs: [lint]
verify-provider: needs: [publish-contract]
can-i-deploy:
if: always()
steps: [run: pact-broker can-i-deploy...]

11) Ferramentas (por classe de tarefas)

Lint/validadores: openapi-linters, protobuf-lint, avro-tools.
CDC: Família Pact/corretor, Spring Cloud Contract, Hoverfly (HTTP gravações/réplicas).
Runners de especificação: schemathesis/Dreedd-semelhante, Postman teste + JSON Schema.
Diff: semantic-diff OpenAPI/Proto/Avro (identifica alterações breaking).
Contêineres: Testcontainers para levantar o provedor/balcão de contratos.

12) Antipattern

O «doutor especial» está separado do código → descolonização. Mantenha o contrato junto ao serviço.
Os mooks de terceiros, em vez de um contrato, → a fragilidade dos updates.
Respostas/geração aleatórias sem ligação com o esquema → flocos.
Altera o tipo/obrigatoriedade de campos sem versão.
Extensões Silent sem notificação/despreceção.
Não há contratos ou códigos de erro negativos.

13) Especificidades do iGaming/Finanças

Formalize os campos de dinheiro: 'amount' - decimal com escala, moeda - ISO-4217, somas invariantes.
Contratos de pagamentos/webhooks: HMAC/mTLS, anti-replay ('X-Timestamp' janela), idempotação, 'Retry-After'.
Regionalidade/tenentes: títulos obrigatórios 'X-Tenant/X-Region', localização de mensagens.
Eventos: revistas imutáveis (auditoria), chaves de dedução, garantias de entrega (at least once + hendlers idumpotentes).

14) Exemplos de testes «esqueletos»

14. 1 Estilo Schemathesis (pseudo)

bash schemathesis run openapi. yaml --checks all --hypothesis-deadline=200

14. 2 Postman como runner de especificação

js pm. test ("Scheme/v1/wallets/{ id} is valid," () => {
const schema = pm. collectionVariables. get("wallet_get_schema");
pm. expect(ajv. validate(JSON. parse(schema), pm. response. json())). to. be. true;
});

14. 3 Provider-verificação CDC (pseudo)

bash pact-broker can-i-deploy --pacticipant wallets --version $SHA --to-environment staging

15) Folha de cheque pró-prontidão

• Contratos no repositório, a CI valida e publica artefatos.
• O CDC está ativado para integrações críticas; funciona broker/matrix «can-i-deploy».
• A política de compatibilidade (HTTP/gRPC/Events) foi documentada; semantic-diff automático.
• Contratos negativos: erros, limites de tamanho, idempotidade, 'Retry-After'.
• Dados de teste são determinados; os exemplos são suportados.
• Versionização e deprecação: prazos, notificações, cabeçalhos.
• Para eventos - Schema Registry e modo de compatibilidade; O produtor/consumer está testando ambas as versões.
• Artefatos: JUnit/HTML, relatórios diff/verify, matriz de compatibilidade.
• Procedimento de incidente: rápida rolback contrato/bandeira de fique, notificação aos integradores.

16) TL; DR

Fixe as expectativas nos contratos e execute-as automaticamente, como CDC para expectativas de clientes, testes de especificação para adequação de implementação, registro de padrão para eventos. Mantenha uma política de compatibilidade rigorosa e contratos negativos (erros, limites, idempotidade). Não se pode lançar sem a matriz verde can-i-deploy e semantic-diff sem alterações breaking.