VCR.py grava respostas HTTP em cassetes e as reproduz depois. Isso torna testes de integração rápidos e determinísticos, mas o arquivo gravado pode conter headers, tokens e dados pessoais.

import vcr
import requests

gravador = vcr.VCR(
    record_mode="once",
    filter_headers=["authorization"],
    filter_query_parameters=["api_key"],
)


@gravador.use_cassette("tests/cassettes/status.yaml")
def test_status() -> None:
    response = requests.get("https://api.example.com/status", timeout=5)
    assert response.status_code == 200

once grava quando o cassete não existe e depois exige correspondência. Revise o YAML antes do commit e filtre também cookies, corpos e identificadores sensíveis conforme a API. Não grave uma resposta de produção sem autorização.

Use mocks focados em testes unitários e VCR.py na camada de integração. Para HTTPX, veja RESPX; para clientes requests, revise requests em Python.

A documentação oficial do VCR.py, consultada em 22 de julho de 2026, descreve matchers, filtros e modos de gravação. Defina uma política para atualizar cassetes e mantenha alguns testes de contrato ao vivo em ambiente controlado.

Escolha o record mode de propósito

once é o padrão usual para CI: crie o cassete localmente, faça commit e falhe se surgir uma interação nova. none nunca grava e só reproduz, o que é mais seguro quando você quer garantir execução offline. new_episodes acrescenta interações inéditas e pode esconder drift se o diff não for revisado com cuidado. all regrava sempre e combina mal com suítes compartilhadas.

Grave contra uma API de staging ou sandbox com credenciais sintéticas. Não aponte uma sessão de gravação para dados de clientes em produção. Quando o contrato remoto mudar, apague ou regenere o cassete afetado de propósito, em vez de editar YAML à mão, salvo um ajuste trivial de filtro.

Filtre segredos antes do cassete existir

Filtros rodam antes da persistência. Configure filter_headers, filter_query_parameters e filter_post_data_parameters para tokens, chaves de API, cookies de sessão e senhas. Para corpos que embutem segredos em JSON, use um callback before_record que redija campos pelo nome.

def limpar_corpo(request):
    if request.body and b"password" in request.body:
        request.body = b'{"password":"<FILTERED>"}'
    return request


gravador = vcr.VCR(
    record_mode="once",
    filter_headers=["authorization", "cookie"],
    before_record_request=limpar_corpo,
)

Revise o cassete no pull request com o mesmo cuidado do código da aplicação. Um bearer token vazado em YAML continua sendo segredo. Prefira valores placeholder que mantenham a estrutura legível para depuração.

Faça match do que importa na requisição

Por padrão o VCR.py combina método e URI. Inclua matchers quando o mesmo endpoint é chamado com corpos ou headers diferentes que mudam a resposta, como body, headers ou matchers customizados. Match demais deixa o cassete frágil; match de menos pode reproduzir a interação errada.

Normalize partes voláteis da URI quando timestamps ou IDs aleatórios aparecem no caminho. Ou estabilize o cliente sob teste, ou ensine o matcher a ignorar esses segmentos. Afirme resultados de domínio no teste, não cada header gravado no cassete.

Organize cassetes como fixtures

Mantenha um cassete por cenário com caminho descritivo, por exemplo tests/cassettes/pagamentos/criar_sucesso.yaml. Compartilhar um cassete grande entre testes sem relação torna a renovação dolorosa e a revisão barulhenta. Nomeie arquivos pelo comportamento sob teste, não pela biblioteca do cliente HTTP.

Versione cassetes com a suíte quando a CI precisar rodar sem rede. Documente quem os regenera e com que frequência. Uma renovação trimestral, mais uma sob demanda após mudanças conhecidas da API, costuma bastar. Pareie testes com cassete a uma suíte pequena de contrato ao vivo, em agenda ou atrás de um marker explícito.

Quando VCR.py é a ferramenta errada

Testes unitários que só precisam de um JSON fixo costumam ficar mais claros com mock de transport ou uma interface de cliente stub. O VCR.py brilha quando construção de URL, headers, redirects e formas reais de resposta importam juntos. É mais fraco quando cada execução precisa mutar estado remoto que não pode ser reproduzido com segurança.

Código HTTPX async pode exigir um adapter ou outra biblioteca de mock. Confirme o suporte antes de adotar VCR.py como única estratégia de integração. Mantenha timeouts no cliente sob teste para que uma gravação ao vivo mal configurada falhe rápido em vez de travar a suíte.

Checklist operacional

Antes do merge, confirme que os filtros removem segredos, que o record mode não pode atingir a rede por acidente na CI, que o diff dos cassetes foi revisado e que existe um plano de renovação. Rode a suíte offline pelo menos uma vez. Mantenha uma verificação ao vivo rara e separada para o contrato remoto.

VCR.py transforma uma conversa HTTP real em fixture reproduzível. Trate essa fixture como configuração sensível: filtrada, versionada, renovada de propósito e nunca confundida com um substituto completo de testes de contrato.