#contract-testing#llm#testes#pydantic#schema#integracao#ci#fixtures

Contract testing para APIs de LLM: o teste que seus mocks escondem

Seu fake determinístico passa. A API real mudou. Como detectar drift de contrato antes do incidente

Anderson LimaSoftware Engineer & Architect

22 de setembro de 2026

10 min de leitura

2 visualizações

Contract testing para APIs de LLM: o teste que seus mocks escondem

Numa POC que fiz recentemente, o cliente do provedor enviava uma pergunta declarada como "type": "boolean". A documentação de primitivos do fornecedor dizia que o tipo correto era noul. O catálogo do gateway exibia "Boolean" como capacidade.

A suíte de testes estava verde. Vinte e oito testes, todos passando, sem rede e em 0,34 segundo.

Eles passavam porque o fake devolvia exatamente aquilo que eu tinha escrito nele. O fake não sabia de contrato nenhum. Ele sabia do meu palpite sobre o contrato — e testava meu palpite contra ele mesmo.

Esse é o ponto cego. Testes com mock provam que seu código lida corretamente com a resposta que você imaginou. Eles não provam nada sobre a resposta que o provedor de fato envia.

Este artigo mostra como fechar essa lacuna sem transformar o CI em refém da API de terceiros.

TL;DR

Mock testa o seu modelo mental. Contract test confronta o modelo mental com a realidade.
Três camadas: teste unitário com fake (rápido, sempre), contract test contra a API real (lento, agendado), e validação em runtime (sempre, em produção).
Valide semântica, não só tipo: enum permitido, faixa [0,1], soma de probabilidades, campos obrigatórios presentes.
Grave fixtures a partir de respostas reais e versione-as. Elas viram a fonte dos fakes.
Rode o contract test em schedule, não em cada PR. Ele falha por motivos fora do seu controle.
Drift silencioso é o inimigo: o schema continua válido e a distribuição muda. Isso exige eval, não asserção.
Registre a versão efetiva do modelo em cada decisão persistida.

As três camadas, e o que cada uma prova

Camada	Roda quando	Usa rede	Prova
unitário com fake	cada commit	não	seu código lida com a forma esperada
contract test	agendado, e no deploy	sim	a forma esperada ainda é a forma real
validação em runtime	toda requisição	sim	esta resposta específica é utilizável

A maioria dos times tem a primeira e a terceira. A segunda é a que falta, e é a única que detecta drift antes do usuário.

Camada 1: o fake que continua valendo a pena

Não jogue fora os mocks. Eles são rápidos, determinísticos, não custam tokens e cobrem o caminho de degradação — coisa que a API real dificilmente reproduz sob demanda.

A única regra é: o fake deve ser construído a partir de uma resposta gravada, nunca digitado à mão a partir da documentação.

python

import json
from pathlib import Path

FIXTURES = Path(__file__).parent / "fixtures"

def load_fixture(name: str) -> dict:
    return json.loads((FIXTURES / f"{name}.json").read_text())

class RecordedClient:
    """Fake alimentado por resposta real gravada. Nunca escrito à mão."""

    def __init__(self, fixture: str = "evaluate_ok"):
        self.payload = load_fixture(fixture)
        self.calls: list[dict] = []

    def evaluate(self, state, questions):
        self.calls.append({"state": state, "questions": questions})
        return self.payload

class FailingClient:
    def __init__(self, error: Exception):
        self.error = error

    def evaluate(self, state, questions):
        raise self.error

A lista calls importa mais do que parece: ela permite asserções sobre o que você enviou, não só sobre o que recebeu. Metade dos bugs de contrato está no request.

python

def test_envia_tipo_de_pergunta_correto(client: RecordedClient):
    service.triage("Checkout fora do ar", "Pagamentos falhando há 20 min")

    sent = client.calls[0]["questions"]
    assert sent["is_urgent"]["type"] == "noul", (
        "o provedor documenta 'noul'; 'boolean' é rótulo de catálogo"
    )
    assert set(sent["department"]["criteria"]) == {
        "billing", "technical", "shipping", "general",
    }

Esse teste teria pegado o drift da minha POC — porque ele afirma o contrato, em vez de repetir o palpite.

Camada 2: o contract test de verdade

Aqui você chama a API real. Uma vez, com um payload mínimo, e afirma apenas a forma — nunca o conteúdo.

python

import os
import pytest

pytestmark = pytest.mark.contract

MINIMAL_QUESTIONS = {
    "is_urgent": {"type": "noul", "instructions": "Is this urgent?"},
    "department": {
        "type": "choice",
        "instructions": "Which team?",
        "criteria": {"billing": "payments", "technical": "bugs"},
    },
    "urgency": {
        "type": "score",
        "instructions": "How urgent?",
        "criteria": ["low", "medium", "high"],
    },
}

@pytest.fixture(scope="session")
def live_client():
    key = os.environ.get("PROVIDER_API_KEY")
    if not key:
        pytest.skip("PROVIDER_API_KEY ausente — contract test pulado")
    return ProviderClient(api_key=key, timeout=30.0)

def test_contrato_de_resposta(live_client, record_fixture):
    body = live_client.evaluate(
        state={"subject": "Checkout down", "message": "Payments failing"},
        questions=MINIMAL_QUESTIONS,
    )
    record_fixture("evaluate_ok", body)      # atualiza a fixture versionada

    answers = body["answers"]
    assert set(answers) == set(MINIMAL_QUESTIONS), "conjunto de respostas mudou"

    # noul: probabilidade, não booleano
    assert "noul" in answers["is_urgent"] or "probability" in answers["is_urgent"]
    p = answers["is_urgent"].get("noul", answers["is_urgent"].get("probability"))
    assert isinstance(p, float) and 0.0 <= p <= 1.0

    # choice: opção dentro do enum enviado, probabilidades somando ~1
    dep = answers["department"]
    assert dep["choice"] in MINIMAL_QUESTIONS["department"]["criteria"]
    assert abs(sum(dep["probabilities"].values()) - 1.0) < 0.02

    # score: dentro da faixa dos critérios enviados
    assert 0.0 <= answers["urgency"]["score"] <= 2.0

Três decisões deliberadas neste teste:

Nenhuma asserção sobre qual departamento foi escolhido. O modelo pode mudar de opinião entre versões sem quebrar contrato. Testar conteúdo aqui produz flakiness e ensina a equipe a ignorar o teste.

record_fixture grava a resposta. O contract test alimenta os mocks da camada 1. As duas camadas ficam sincronizadas por construção.

pytest.skip quando não há credencial. Nenhum desenvolvedor sem chave fica bloqueado; o teste some em vez de falhar.

O gravador:

python

@pytest.fixture
def record_fixture():
    def _record(name: str, body: dict) -> None:
        if os.environ.get("RECORD_FIXTURES") != "1":
            return
        path = FIXTURES / f"{name}.json"
        path.write_text(json.dumps(redact(body), indent=2, sort_keys=True) + "\n")
    return _record

SENSITIVE = {"authorization", "api_key", "request_id", "trace_id"}

def redact(obj):
    """Remove identificadores e segredos antes de versionar a fixture."""
    if isinstance(obj, dict):
        return {
            k: ("<redacted>" if k.lower() in SENSITIVE else redact(v))
            for k, v in obj.items()
        }
    if isinstance(obj, list):
        return [redact(i) for i in obj]
    return obj

Nunca versione fixture sem redigir. IDs de requisição, tokens e eventuais trechos do input real não pertencem ao repositório.

Onde rodar: schedule, não pull request

Contract test falha por motivos que não são culpa do PR: rate limit, indisponibilidade do provedor, rotação de chave. Colocá-lo no caminho do merge treina o time a ignorar CI vermelho — o pior resultado possível.

yaml

name: contract-tests

on:
  schedule:
    - cron: "0 7 * * *"        # diário, antes do expediente
  workflow_dispatch:            # sob demanda
  push:
    branches: [main]            # após merge, não antes

jobs:
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: "3.12" }
      - run: pip install -e ".[dev]"
      - name: contract tests
        env:
          PROVIDER_API_KEY: ${{ secrets.PROVIDER_API_KEY }}
        run: pytest -m contract -v
      - name: abrir issue em caso de drift
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: `Drift de contrato detectado em ${new Date().toISOString().slice(0,10)}`,
              labels: ['contract-drift', 'priority'],
              body: `O contract test agendado falhou.\n\nRun: ${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`
            })

No pyproject.toml, registre o marcador e mantenha-o fora do default:

toml

[tool.pytest.ini_options]
markers = ["contract: chama a API real do provedor (lento, precisa de credencial)"]
addopts = "-m 'not contract'"

Camada 3: validação em runtime, e por que tipo não basta

Schema válido não significa resposta utilizável. Um department fora do enum é sintaticamente perfeito e semanticamente inválido.

python

from pydantic import BaseModel, Field, field_validator, model_validator

DEPARTMENTS = {"billing", "technical", "shipping", "general"}

class Evaluation(BaseModel):
    is_urgent: float = Field(ge=0.0, le=1.0)
    department: str
    department_probabilities: dict[str, float]
    urgency_score: float = Field(ge=0.0, le=2.0)
    confidence: float | None = Field(default=None, ge=0.0, le=1.0)

    @field_validator("department")
    @classmethod
    def department_no_enum(cls, v: str) -> str:
        if v not in DEPARTMENTS:
            raise ValueError(f"departamento fora do enum: {v!r}")
        return v

    @model_validator(mode="after")
    def probabilidades_coerentes(self) -> "Evaluation":
        probs = self.department_probabilities
        if set(probs) != DEPARTMENTS:
            raise ValueError(f"chaves de probabilidade divergem: {sorted(probs)}")
        total = sum(probs.values())
        if abs(total - 1.0) > 0.02:
            raise ValueError(f"probabilidades somam {total:.3f}")
        if max(probs, key=probs.get) != self.department:
            raise ValueError("escolha não corresponde ao argmax das probabilidades")
        return self

O último validador é o mais valioso e o menos comum. Ele detecta uma classe inteira de inconsistências internas: a resposta diz technical, mas a maior probabilidade está em billing. Nenhum teste de tipo pega isso.

E a falha de validação precisa ter um destino claro, não um except: pass:

python

def build_evaluation(raw: dict) -> Evaluation | None:
    try:
        return Evaluation.model_validate(raw)
    except ValidationError as error:
        metrics.increment("llm.contract_violation", tags={"field": first_field(error)})
        logger.bind(errors=error.errors()).warning("resposta violou o contrato")
        return None            # ticket é criado sem avaliação; não falha o fluxo

Contagem de contract_violation por campo é o sinal mais barato de drift em produção. Quando ele sobe sem deploy do seu lado, algo mudou do outro.

O drift que nenhuma asserção pega

Existe uma categoria pior: o schema continua perfeito e a distribuição muda.

O provedor promove um alias para uma versão nova. As respostas continuam válidas, os tipos continuam corretos, todos os testes continuam verdes — e a taxa de urgência classificada como alta cai 14% porque o modelo ficou mais conservador.

Nenhum contract test detecta isso. O que detecta:

python

def test_distribuicao_estavel_no_conjunto_dourado(live_client, golden_set):
    """Roda um conjunto fixo e compara agregados com o baseline versionado."""
    results = [live_client.evaluate(c.state, QUESTIONS) for c in golden_set]

    urgent_rate = mean(r["answers"]["is_urgent"]["noul"] > 0.5 for r in results)
    mean_score = mean(r["answers"]["urgency"]["score"] for r in results)

    baseline = load_baseline()   # versionado junto do código
    assert abs(urgent_rate - baseline["urgent_rate"]) < 0.08, (
        f"taxa de urgência mudou: {baseline['urgent_rate']:.2f} → {urgent_rate:.2f}"
    )
    assert abs(mean_score - baseline["mean_score"]) < 0.25

Trinta a cinquenta casos fixos bastam. O objetivo não é medir qualidade — é detectar que algo mudou. A investigação vem depois.

E fixe a versão quando o provedor permitir. Alias é conveniência de upgrade, não garantia de reprodutibilidade:

python

MODEL = os.environ.get("MODEL_ID", "provider/model-1.13.0")   # não "model-latest"

Persista a versão efetiva junto de cada decisão. Sem isso, você não consegue responder "por que este ticket foi classificado assim em março?".

Checklist

Todo fake é construído a partir de fixture gravada, não digitado da documentação.
Existe asserção sobre o request, não só sobre a response.
O contract test afirma forma, nunca conteúdo específico.
Fixtures são redigidas antes de versionar.
Contract test roda em schedule e abre issue automática ao falhar.
O marcador de contract test está fora do addopts padrão.
A validação de runtime cobre enum, faixa, soma e coerência interna.
Violação de contrato emite métrica com o campo culpado.
Existe um conjunto dourado com baseline de distribuição versionado.
O ID do modelo é fixo, e a versão efetiva é persistida com a decisão.

Conclusão

O mock é um espelho. Ele devolve o que você colocou nele, e por isso nunca contradiz você. É útil para testar o seu lado da integração — e completamente cego para o lado do provedor.

O contract test é a única camada que confronta a sua suposição com a realidade. Ele é lento, depende de rede, custa alguns centavos por execução e precisa rodar longe do caminho de merge. Tudo isso é preço, não defeito.

Na POC que abriu este artigo, um único assert sobre o tipo enviado teria transformado uma suposição silenciosa em um teste vermelho. Foi barato demais para ter sido esquecido — e é exatamente por ser barato que costuma ser.

Leituras relacionadas

Os exemplos usam Python 3.12, pytest 8 e Pydantic 2. Nomes de campos como noul, choice e score seguem a convenção de primitivos tipados descrita no artigo sobre JEV; adapte aos nomes do seu provedor antes de copiar.

react · boilerplate

React Zero to Hero Starter

Starter React público com TypeScript, Zustand, React Query, Tailwind CSS, PWA e integrações de IA documentadas. O repositório não declara uma licença SPDX; revise os termos antes de uso comercial.

Ver produto

R$ 19,99

nextjs · saas

SaaS Landing Page

Landing page SaaS para Next.js, TypeScript e Tailwind CSS com SEO, temas, i18n, PWA e pontos de integração para auth, Stripe e IA. Uma base clara para sair da tela vazia e adaptar sua proposta.

Ver produto

Explorar todos os produtos

Transforme o que aprendeu em código que roda

Templates testados em produção, usados por desenvolvedores. Economize semanas de setup no seu próximo projeto.

Ver templates

Contract testing para APIs de LLM: o teste que seus mocks escondem

Contract testing para APIs de LLM: o teste que seus mocks escondem

TL;DR

As três camadas, e o que cada uma prova

Camada 1: o fake que continua valendo a pena

Camada 2: o contract test de verdade

Onde rodar: schedule, não pull request

Camada 3: validação em runtime, e por que tipo não basta

O drift que nenhuma asserção pega

Checklist

Conclusão

Leituras relacionadas

Continue construindo depois da leitura

FastAPI Clean Architecture

Boilerplate React Native

AI Agents Starter Kit

AI First MongoDB

AI SaaS First Ultra

AI SaaS First Firebase

Me pague um café

React TestForge — Vitest + Playwright Starter

React Cupertino UI

IgnitionStack

LuminALL Boilerplate – Multi-Tenant AI SaaS Starter Kit

React Zero to Hero Starter

SaaS Landing Page

Artigos Relacionados

Versionamento de decisões de IA: respondendo “por que o sistema decidiu isso em março?”

Custo por tarefa: a métrica que substitui preço por token

Degradação graciosa em produtos com IA: o que acontece quando o modelo some

Checklist de Code Review Pré-Produção

Transforme o que aprendeu em código que roda