Boas Práticas para Testes com Documentos Brasileiros
Testar sistemas que aceitam documentos brasileiros exige atenção a regras algorítmicas, casos de borda e conformidade legal. Este guia reúne as melhores práticas para equipes de QA e desenvolvedores que trabalham com CPF, CNPJ, CNH, RG e outros documentos.
Entenda os documentos que seu sistema aceita
O primeiro passo para testar corretamente é entender a estrutura de cada documento aceito pelo sistema. CPF e CNPJ têm dígitos verificadores calculados por módulo 11. CNH tem um dígito verificador próprio. RENAVAM usa módulo 11 com pesos específicos. RG não tem uma regra nacional única — cada estado tem seu formato. Cartão de crédito usa o algoritmo de Luhn (módulo 10). Conhecer essas regras permite criar casos de teste precisos.
Para cada tipo de documento, documente: (1) formato esperado com e sem máscara; (2) tamanho em dígitos; (3) regras de dígitos verificadores; (4) casos conhecidos de invalidade (todos os dígitos iguais, por exemplo); (5) variações regionais quando aplicável. Essa documentação vira a base do seu plano de teste.
Cobrindo os casos de borda mais importantes
Os casos de borda para validação de documentos são previsíveis e devem fazer parte de todo plano de teste: (1) Documento vazio ou nulo — o campo é obrigatório? (2) Comprimento incorreto — menos ou mais dígitos que o esperado. (3) Caracteres não numéricos — letras, símbolos, espaços. (4) Dígitos verificadores incorretos — número com estrutura válida mas verificador errado. (5) Sequências inválidas por definição — como CPFs com todos os dígitos iguais. (6) Máscaras — o sistema aceita '123.456.789-09' e '12345678909' como equivalentes?
(7) Documentos de estados específicos — para Título de Eleitor e AIH, teste com códigos de estado válidos e inválidos. (8) Valor no limite — para documentos que têm range válido (como CNPJ onde o sufixo 0000 pode ser inválido). (9) SQL injection e XSS — os campos de documento são um vetor de ataque comum; valide que inputs maliciosos são tratados corretamente antes da validação do documento.
Estruturando testes automatizados eficientes
Em frameworks como Cypress, Playwright ou Selenium, organize os testes de documentos em três categorias: testes de validação de campo (unitários), testes de fluxo com dados válidos (integração) e testes de fluxo com dados inválidos (negativos). Para os testes negativos, use uma fixture com documentos inválidos conhecidos — mantenha essa lista no repositório.
Parametrize seus testes de campo com múltiplos documentos válidos para aumentar a cobertura sem multiplicar o código. Um único teste parametrizado com 10 CPFs válidos diferentes cobre muito mais que 10 testes idênticos. O Help4Dev pode ser usado durante o desenvolvimento dos testes para gerar os dados necessários rapidamente.
Gestão de dados de teste e ambientes
Separe os dados de teste por ambiente: desenvolvimento, QA, homologação e produção devem ter conjuntos de dados distintos. Em desenvolvimento e QA, use exclusivamente dados fictícios. Em homologação, use dados fictícios que imitem os padrões dos clientes reais (mesma distribuição geográfica, por exemplo). Nunca use dados reais de produção em ambientes de não-produção.
Versione seus dados de teste junto com o código no repositório. Um arquivo seeds.json ou fixtures/documents.json com CPFs, CNPJs e outros dados fictícios válidos garante que todos na equipe usem os mesmos dados e que os pipelines de CI/CD funcionem de forma consistente. Atualize esses arquivos sempre que adicionar novos tipos de documento ao sistema.
Erros comuns e como evitá-los
Os erros mais frequentes em testes de documentos brasileiros: (1) Usar CPFs famosos da internet — existem CPFs fictícios amplamente divulgados (como 123.456.789-09) que são conhecidos e podem ter comportamentos especiais em alguns sistemas legados. Prefira dados gerados aleatoriamente. (2) Não testar a máscara — sistemas frequentemente aceitam ou rejeitam documentos com base na presença ou ausência de pontuação; teste os dois formatos. (3) Ignorar a validação no backend — sempre valide no servidor, mesmo que valide no frontend.
(4) Reutilizar o mesmo CPF em muitos testes — se o sistema não permite dois cadastros com o mesmo CPF, usar sempre o mesmo dado vai causar falsos negativos. Gere dados variados. (5) Não atualizar dados de teste após mudanças nas regras — o CNPJ alfanumérico é um bom exemplo: quando a mudança entrar em vigor, os testes existentes precisarão cobrir o novo formato. Mantenha um processo para revisar e atualizar os dados de teste periodicamente.