Como criar testes automatizados para integração com API de CPF

Para criar testes automatizados em uma integração com API de CPF, você precisa de ao menos três camadas: testes unitários com mocks (sem consumir cota real), testes de contrato para validar o formato da resposta e testes de integração executados periodicamente em CI/CD. Essa combinação garante cobertura completa sem desperdiçar consultas do plano.

Tipos de teste para integração com API

1. Testes unitários com mock (Python)

Use mocks para simular respostas da API sem consumir consultas reais:

import pytest
from unittest.mock import patch, MagicMock

# Funcao que queremos testar
def processar_cpf(cpf: str, api_key: str) -> dict:
    import requests
    url = f'https://api.cpfhub.io/cpf/{cpf}'
    headers = {'x-api-key': api_key, 'Accept': 'application/json'}
    response = requests.get(url, headers=headers, timeout=10)

    if response.status_code == 200:
    data = response.json()
    if data.get('success'):
    return {'valido': True, 'nome': data['data']['name']}
    elif response.status_code == 402:
    return {'valido': False, 'erro': 'cota_excedida'}

    return {'valido': False, 'erro': 'cpf_nao_encontrado'}

# Teste: CPF valido
@patch('requests.get')
def test_cpf_valido(mock_get):
    mock_response = MagicMock()
    mock_response.status_code = 200
    mock_response.json.return_value = {
    'success': True,
    'data': {
    'cpf': '12345678900',
    'name': 'Joao da Silva',
    'nameUpper': 'JOAO DA SILVA',
    'gender': 'M',
    'birthDate': '15/06/1990',
    'day': 15, 'month': 6, 'year': 1990
    }
    }
    mock_get.return_value = mock_response

    resultado = processar_cpf('12345678900', 'fake_key')
    assert resultado['valido'] is True
    assert resultado['nome'] == 'Joao da Silva'

# Teste: CPF nao encontrado
@patch('requests.get')
def test_cpf_nao_encontrado(mock_get):
    mock_response = MagicMock()
    mock_response.status_code = 200
    mock_response.json.return_value = {'success': False}
    mock_get.return_value = mock_response

    resultado = processar_cpf('00000000000', 'fake_key')
    assert resultado['valido'] is False

2. Testes unitários com mock (JavaScript/Jest)

const { consultarCPF } = require('./cpfService');

// Mock do fetch
global.fetch = jest.fn();

describe('consultarCPF', () => {
    afterEach(() => jest.resetAllMocks());

    test('retorna dados para CPF valido', async () => {
    fetch.mockResolvedValueOnce({
    ok: true,
    json: async () => ({
    success: true,
    data: {
    cpf: '12345678900',
    name: 'Joao da Silva',
    nameUpper: 'JOAO DA SILVA',
    gender: 'M',
    birthDate: '15/06/1990',
    day: 15, month: 6, year: 1990
    }
    })
    });

    const resultado = await consultarCPF('12345678900');
    expect(resultado.success).toBe(true);
    expect(resultado.data.name).toBe('Joao da Silva');
    });

    test('lida com erro 401 (chave invalida)', async () => {
    fetch.mockResolvedValueOnce({
    ok: false,
    status: 401
    });

    await expect(consultarCPF('12345678900'))
    .rejects.toThrow('Chave de API invalida');
    });

    test('lida com timeout', async () => {
    fetch.mockRejectedValueOnce(new Error('timeout'));

    await expect(consultarCPF('12345678900'))
    .rejects.toThrow('timeout');
    });
});

3. Testes de contrato

Verifique se a resposta da API mantém o formato esperado:

def test_formato_resposta():
    """Verifica que a API retorna os campos esperados."""
    resposta_mock = {
    'success': True,
    'data': {
    'cpf': '12345678900',
    'name': 'Joao da Silva',
    'nameUpper': 'JOAO DA SILVA',
    'gender': 'M',
    'birthDate': '15/06/1990',
    'day': 15,
    'month': 6,
    'year': 1990
    }
    }

    assert 'success' in resposta_mock
    assert 'data' in resposta_mock

    data = resposta_mock['data']
    campos_obrigatorios = ['cpf', 'name', 'nameUpper', 'gender', 'birthDate', 'day', 'month', 'year']
    for campo in campos_obrigatorios:
    assert campo in data, f'Campo {campo} ausente na resposta'

4. Testes de integração (com API real)

Para testes de integração, use o plano gratuito da CPFHub.io (50 consultas/mês) com CPFs de teste:

import os
import pytest
import requests

@pytest.mark.integration
def test_integracao_api_real():
    """Teste de integracao com a API real (consome cota)."""
    api_key = os.environ.get('CPFHUB_API_KEY')
    if not api_key:
    pytest.skip('CPFHUB_API_KEY nao configurada')

    url = 'https://api.cpfhub.io/cpf/00000000000'
    headers = {'x-api-key': api_key, 'Accept': 'application/json'}

    response = requests.get(url, headers=headers, timeout=15)
    assert response.status_code in [200, 404]

Dica: Marque testes de integração com labels e execute-os separadamente para não consumir cota desnecessariamente:

pytest -m integration # apenas testes de integracao
pytest -m "not integration" # apenas testes unitarios

5. Cenários essenciais para testar

• CPF válido com dados completos (200).

• CPF não encontrado (404).

• CPF com formato inválido (400).

• Chave de API inválida (401).

• Timeout da API.

• Erro de rede (DNS, conexão recusada).

• Resposta com formato inesperado.

Boas práticas

• Use mocks para testes unitários — Não consuma consultas reais.

• Reserve testes de integração para CI/CD — Execute periodicamente, não a cada commit.

• Teste cenários de erro — Tão importantes quanto o caminho feliz.

• Versionamento — Se a API mudar, seus testes de contrato vão detectar.

• Variáveis de ambiente — Nunca hardcode chaves de API nos testes.

De acordo com a OWASP Testing Guide, testar autenticação e tratamento de erros em APIs externas é uma das práticas mais negligenciadas em revisões de segurança — e uma das mais impactantes quando a integração vai para produção.

Perguntas frequentes

Quais tipos de mock devo usar para testar minha integração com API de CPF sem consumir cota?

Use unittest.mock.patch em Python ou jest.fn() em JavaScript para substituir as chamadas HTTP por respostas simuladas. O mock deve cobrir os cenários mais comuns: resposta 200 com sucesso, 200 com success: false, 400 (formato inválido) e 401 (chave inválida). Dessa forma, toda a lógica de parsing e tratamento de erros é testada sem nenhuma consulta real.

Como organizar testes de integração para não consumir cota desnecessariamente?

Marque os testes de integração com um label separado (ex: @pytest.mark.integration no Python ou uma pasta __tests__/integration/ no Node.js) e execute esse grupo apenas em pipelines de CI/CD agendados, não a cada push. O plano gratuito da CPFHub.io oferece 50 consultas/mês — suficiente para smoke tests periódicos sem impacto no orçamento.

O que um teste de contrato deve verificar na resposta da API de CPF?

O teste de contrato deve confirmar que todos os campos esperados estão presentes na resposta: success, data.cpf, data.name, data.nameUpper, data.gender, data.birthDate, data.day, data.month e data.year. Se a API mudar o formato em uma atualização futura, o teste de contrato captura a quebra antes que ela chegue em produção.

Como a CPFHub.io se comporta quando o limite do plano é atingido?

A API não bloqueia nem retorna erro 429 ao atingir o limite mensal. Cada consulta excedente é cobrada a R$0,15, sem interrupção do serviço. Isso simplifica os testes: você não precisa simular bloqueio por cota — apenas garantir que sua aplicação lida com respostas 200 e 404 corretamente.

Conclusão

Testes automatizados garantem que sua integração com a API de CPF funcione corretamente em todos os cenários. Com mocks para testes unitários e o plano gratuito da CPFHub.io para testes de integração, você cobre o ciclo completo com confiança — sem depender de chamadas reais em cada execução do pipeline.

A combinação de testes unitários, de contrato e de integração cria uma rede de segurança que detecta quebras antes de chegarem em produção. Quanto mais cedo um problema é encontrado no ciclo de desenvolvimento, menor o custo de correção.

Cadastre-se em cpfhub.io e comece com 50 consultas gratuitas por mês, sem cartão de crédito — ideal para montar seu ambiente de testes de integração.