Os dados de endereço em fixtures são o conjunto fixo de exemplos que os testes usam para exercitar formulários, integrações e rotinas de importação. Quando esse conjunto é bem organizado, um teste que falha aponta para um problema real; quando é improvisado, o mesmo teste passa e falha sem motivo aparente. Neste texto, mostramos como estruturar esses dados, o que nunca deve entrar neles e quais casos-limite vale a pena preparar desde o começo.
O que torna um conjunto de teste confiável
Confiar em um conjunto de teste significa poder rodá-lo duas vezes e obter o mesmo resultado. Isso exige que os dados sejam conhecidos, versionados e independentes de qualquer serviço externo que possa mudar sem aviso.
Um endereço digitado à mão no meio do teste tem três defeitos ao mesmo tempo: ninguém sabe se ele é internamente coerente, ele muda quando alguém o edita para outra finalidade, e não existe referência de onde ele veio. Um conjunto organizado resolve os três: o dado é escolhido com um propósito, mora em um arquivo revisável e tem nome que explica o cenário.
Vale lembrar o que esses dados são. Eles não apontam para residências reais e não podem ser usados para entrega, cadastro verdadeiro ou qualquer verificação de identidade. São valores de teste, e o conjunto deve dizer isso de forma explícita.
Por que não usar o endereço de um cliente real?
Porque um endereço identifica uma pessoa. Guardar o endereço de um cliente em um repositório de testes é criar uma cópia de dado pessoal em outro lugar, com outro controle de acesso, outra política de retenção e outra finalidade — nenhuma delas justificada pelo teste.
O risco não é abstrato. Repositórios de código são copiados para máquinas de desenvolvimento, ambientes de integração contínua e backups. Uma vez que o dado entra, sai por caminhos que ninguém mapeia. E o dado continua correto: se a pessoa se mudar, a cópia antiga segue descrevendo uma residência que existiu.
Há ainda um problema técnico: dados reais escondem bugs. Um endereço verdadeiro é, por definição, válido e entregável, então ele nunca exercita o comportamento do sistema diante de entrada ambígua, incompleta ou esquisita. Um conjunto sintético é escolhido justamente para atacar esses pontos.
Como organizar os exemplos por país e cenário
A estrutura que costuma envelhecer melhor tem dois eixos. O primeiro é o país, porque as regras de formato, a presença de código postal e o nome da divisão administrativa dependem dele. O segundo é o cenário, porque um teste não precisa de “um endereço alemão”, precisa de “um endereço alemão sem número de complemento”.
Com os dois eixos, o nome de cada exemplo fica autoexplicativo e o teste deixa de depender de posição em uma lista. Isso importa quando alguém acrescenta um caso no meio do arquivo.
| Eixo | Exemplos de valor | Por que separar |
|---|---|---|
| País | Brasil, Japão, Canadá, Emirados Árabes Unidos | as regras mudam por país |
| Cenário | mínimo, completo, longo, sem código | cada um exercita um caminho diferente |
| Finalidade | cadastro, entrega, cobrança | o mesmo dado é usado de formas distintas |
| Estabilidade | fixo, gerado sob demanda | testes de regressão precisam de valor fixo |
Separe o que é fixo do que é gerado. Um teste de regressão que compara saída precisa de valor estável; um teste exploratório pode usar valores gerados a cada execução. Misturar os dois na mesma pasta é uma fonte constante de confusão.
Que casos-limite vale a pena preparar?
Alguns cenários dão muito retorno pelo esforço que custam:
- Linha de logradouro muito longa, além do que o layout espera, com complemento.
- País que não usa código postal, para verificar se o campo obrigatório impede o cadastro.
- Caracteres não latinos, em escrita local e em transliteração, para checar ordenação, largura e busca.
- Número de unidade com letra em vez de algarismo.
- Código postal com sufixo opcional presente e ausente.
- Endereço com apenas uma linha, quando o formulário espera quatro.
Cada item desse ataca uma suposição diferente. O primeiro testa limites visuais; o segundo, regras de obrigatoriedade; o terceiro, suporte a alfabetos; os três últimos, regras de formato e de exibição.
Usando o gerador para montar o conjunto
No gerador de endereços os componentes saem do mesmo registro: a cidade pertence à divisão escolhida e o código postal segue o padrão daquela área. Isso permite montar fixtures em que a coerência entre campos é garantida, o que é difícil de obter quando os exemplos são digitados.
Um roteiro simples funciona bem. Escolha de oito a doze países que o sistema atende, gere um exemplo de cada um e acrescente os casos-limite da lista acima. Guarde tudo com um comentário que diga que o dado é sintético e destinado a teste. Para entender como os conjuntos de dados do site se organizam, vale comparar com a página de dados de endereço no México e com o texto sobre dados de endereço e privacidade.
Para quem desenvolve: estrutura e manutenção do conjunto
Quatro decisões práticas definem a qualidade final do conjunto.
A primeira é o formato. Um arquivo de dados legível, versionado junto com o código, é mais fácil de revisar do que valores espalhados dentro dos testes. Se o conjunto crescer, valem um nome de campo explícito e um identificador por exemplo.
A segunda é a imutabilidade. Quando um teste depende de um valor, mudar esse valor deve ser uma decisão consciente, com revisão. Alterar um exemplo compartilhado por vários testes costuma quebrar algum deles de forma silenciosa.
A terceira é o vínculo com o cenário. Cada exemplo deve ter um comentário curto dizendo o que ele exercita. Sem isso, ninguém sabe se pode apagá-lo.
A quarta é a checagem de vazamento. Vale rodar uma verificação periódica que procure no conjunto padrões que indiquem dado real: nomes de pessoas, documentos, telefones. É mais fácil impedir a entrada do que descobrir a cópia depois.
Próximos passos
Se o seu repositório tem endereços copiados de ambientes reais, remova-os hoje e substitua por exemplos sintéticos. Se está montando o conjunto do zero, gere os primeiros casos no gerador de endereços, acrescente os casos-limite da lista e escreva, em cada exemplo, uma linha explicando o que ele verifica.