# Como criar testes automatizados para integração com API de CPF > Aprenda a criar testes automatizados para sua integração com API de CPF. Testes unitários, de integração e mocks para garantir qualidade. **Publicado:** 03/04/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/testes-automatizados-integracao-api-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 | Tipo | O que testa | Usa API real? | | --- | --- | --- | | Unitário | Lógica de parsing, validação, tratamento de erros | Não (mock) | | Integração | Comunicação real com a API | Sim | | Contrato | Formato da resposta da API | Parcial (pode usar mock) | | E2E | Fluxo completo (UI → API → resposta) | Sim | --- ## 1. Testes unitários com mock (Python) Use mocks para simular respostas da API sem consumir consultas reais: ```python 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) ```javascript 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: ```python 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: ```python 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: ```bash 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](https://owasp.org/www-project-web-security-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. ### Leia também - [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest) - [Boas práticas para consumir APIs de CPF de forma segura](https://cpfhub.io/blog/boas-praticas-consumir-apis-cpf-segura) - [Como consumir API de CPF em TypeScript com tipagem segura](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-typescript-com-tipagem-segura) - [Como implementar validação de CPF em microsserviços com Docker e Kubernetes](https://cpfhub.io/blog/como-implementar-validacao-cpf-microsservicos-docker-kubernetes) --- ## 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](https://www.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.