Um gerador de endereço dos EUA é útil quando o seu formulário precisa aceitar endereços americanos sem que nenhum dado de cliente real entre no ambiente. O trabalho dele não é inventar texto plausível, e sim montar um conjunto em que o número do imóvel, a via, a cidade, a sigla de estado e o código postal pertençam uns aos outros. Neste texto, percorremos a anatomia de um endereço americano, mostramos por que a coerência interna é o que separa um bom exemplo de um exemplo inútil e listamos os casos que mais quebram formulários. Ao final, você vai saber quais campos exigir, quais aceitar como opcionais e como usar as amostras sem transformar o seu ambiente de teste em uma coleção de erros silenciosos.
Por que usar um gerador em vez de um endereço fixo?
Quase todo projeto começa com um único endereço de exemplo colado em algum arquivo de configuração. Ele funciona na primeira demonstração e passa a atrapalhar na semana seguinte, porque todo teste acaba exercitando a mesma combinação de cidade, estado e código postal. Quando o formulário tem um defeito que só aparece em um estado específico, ou quando o layout quebra com um nome de via mais longo, esse exemplo único não revela nada.
Um gerador resolve isso de duas maneiras. A primeira é volume: você consegue montar centenas de registros plausíveis para popular um banco de homologação ou para rodar um teste de carga. A segunda é variedade controlada: dá para escolher o estado e obter exemplos de lá, em vez de descobrir por acaso que o seu seletor de cidade nunca funcionou no Alaska.
O que um gerador não faz é produzir um endereço entregável. Ele produz um registro de formato correto, e essa distinção vale para todo o resto do texto.
Como se compõe um endereço americano?
A primeira linha começa pelo número do imóvel e segue com o nome da via e o tipo de via, na ordem contrária à que boa parte da Europa usa. Depois do nome podem aparecer o sentido das vias numeradas e um sufixo de quadra, que faz parte do endereço oficial e não é enfeite tipográfico. Truncar essa linha é pior do que parecer feio: a parte cortada pode ser exatamente o elemento que distingue duas vias com o mesmo nome.
A segunda linha, quando existe, identifica a unidade. Ela é opcional, porque a maior parte dos endereços residenciais não tem apartamento nem sala, e o identificador costuma ser texto livre, já que pode ser um número, uma letra ou a combinação dos dois. Misturar a unidade ao logradouro quebra a correspondência de registros e atrapalha a impressão de etiquetas.
Fecham o conjunto a cidade, a sigla de duas letras da divisão de primeiro nível e o código postal. A cidade é texto livre na origem do dado, mas na prática pertence a uma lista mantida; a sigla segue um padrão oficial; e o código postal tem cinco dígitos, com um sufixo opcional de quatro posições que aponta para uma faixa menor de entrega. O sufixo não deve ser exigido de quem digita, mas precisa ser aceito e preservado quando vier.
Quais divisões e territórios precisam caber no formulário?
Um formulário que só aceita as siglas dos cinquenta estados vai recusar endereços válidos. Existem territórios que usam o mesmo sistema de siglas e que aparecem em cadastros de verdade com frequência, e existem endereços de instalações militares, que seguem um formato próprio, com duas letras seguidas de uma identificação numérica e o país indicado de uma forma específica.
A decisão prática, para a maior parte dos sistemas, é aceitar o conjunto completo em vez do subconjunto mais conhecido. Uma lista restrita gera recusas silenciosas, e o sintoma não aparece como mensagem de erro, e sim como alguém reclamando que o site não aceita o próprio endereço. Vale também decidir cedo se o campo vai guardar a sigla de duas letras ou o nome por extenso, porque converter entre os dois formatos na hora de exibir exige uma tabela mantida e não uma regra de abreviação.
Por que a coerência entre campos importa mais que o formato?
O erro mais comum em teste não é o formato, e sim a combinação. Um registro com cidade de um estado e código postal de outro passa por qualquer validação que olhe campo a campo e falha em qualquer verificação que olhe o conjunto. O código postal americano é distribuído por área geográfica, então um par que não combina é indício forte de erro de digitação, ainda que não seja prova, porque faixas podem se sobrepor a estados vizinhos.
A mesma lógica vale para a cidade. Um formulário que aceita qualquer cidade para qualquer estado está aceitando um dado que não corresponde a lugar nenhum, e o teste que usa esse dado nunca vai exercitar o caminho de validação. É por isso que um gerador útil não sorteia cada campo de forma independente: ele escolhe primeiro a divisão, depois uma cidade que pertence a ela e, por fim, um código postal compatível.
No gerador de endereços, os dados de um endereço americano saem nessa ordem de dependência: a cidade pertence à divisão escolhida e o código postal segue o padrão daquela área. A cobertura disponível no site abrange centenas de cidades, milhares de divisões administrativas e mais de treze mil códigos postais, o que é suficiente para que dois testes seguidos raramente recebam o mesmo exemplo.
Que erros de digitação o seu formulário precisa tolerar?
Alguns desvios aparecem em praticamente todo cadastro real e vale testá-los de propósito. O primeiro é o zero à esquerda do código postal: muitos sistemas guardam o campo como número e perdem o zero, o que corrompe códigos que começam com ele. O segundo é o espaço depois do hífen do sufixo, ou o hífen trocado por espaço, que deveria ser normalizado e não recusado.
O terceiro é a mistura de caixa na sigla do estado, que quase sempre vem em minúsculas de um formulário rápido ou de uma planilha. O quarto é a linha do logradouro com acentuação e com palavras longas sem espaço, que quebra tanto o limite do campo quanto a largura de uma etiqueta impressa. O quinto é a abreviação de tipo de via escrita de forma livre, que exige uma tabela de equivalência e não uma expressão regular.
Vale ainda testar a colagem de um endereço completo em um único campo, com quebras de linha, e verificar se o formulário separa as partes ou se grava tudo no logradouro. A segunda opção não é necessariamente errada, mas precisa ser uma decisão consciente, porque depois é difícil desfazer.
Como montar casos de teste a partir das amostras
Uma bateria enxuta costuma bastar. Use um endereço com unidade alfabética, outro com nome de via muito longo, um com sufixo de quatro posições e um com código postal começando por zero. Acrescente um exemplo de território e um de instalação militar, se o seu produto aceita esse tipo de cliente, e um endereço com acentuação no nome da via.
Depois de gerar os exemplos, congele alguns no repositório para os testes que comparam saída com valor esperado. Um teste de igualdade alimentado por dado aleatório falha uma vez por semana e ninguém entende por quê, então marque no próprio caso se ele espera um registro estável ou uma variação. O texto sobre casos de teste do formulário de entrega mostra como transformar essa lista em verificações concretas, e o resumo da estrutura do endereço americano detalha cada componente campo por campo.
Como escolher os estados que a sua bateria deve cobrir?
Um conjunto de teste distribuído ao acaso pelos cinquenta estados parece completo e costuma ser raso. O critério que funciona melhor é agrupar por característica, e não por geografia, porque os defeitos aparecem nas características e não nos nomes.
Comece pelos estados que representam um caso difícil de cada tipo. Um estado com código postal começando por zero cobre o defeito de truncamento numérico. Um estado com nome de cidade muito longo cobre o limite de largura do campo. Um território cobre a lista de siglas aceitas. Um estado grande, onde uma mesma cidade tem vários códigos postais, cobre o caso em que o código postal específico não corresponde ao centro da cidade.
Depois acrescente um exemplo com unidade no mesmo prédio em andares diferentes, porque o identificador muda de forma dentro do mesmo endereço e o formulário precisa aceitar as duas grafias. E acrescente um endereço de rota rural ou de caixa postal, que tem estrutura própria e não deve ser forçado no campo do logradouro.
Com esse conjunto pequeno, de oito ou dez registros, você cobre mais caminho de código do que cobriria com cinquenta exemplos escolhidos sem critério. O restante do volume serve para teste de carga e para popular ambiente, e nesse caso tanto faz qual estado aparece, desde que as combinações continuem coerentes.
Que decisões de produto esse conjunto ajuda a tomar?
Além de encontrar defeito, um bom conjunto de dados de teste informa decisões que ainda não foram tomadas. A primeira é sobre campos obrigatórios: se a maior parte dos exemplos residenciais não tem unidade, o formulário não deve exigi-la, e o teste deixa isso evidente.
A segunda é sobre a lista de siglas. Se o produto aceita apenas os cinquenta estados, isso deve ser uma decisão escrita, e não um efeito colateral de uma lista colada de um exemplo. O teste com um território força a conversa e o resultado é uma escolha consciente.
A terceira é sobre a exibição do código postal. Guardar como texto ou como número parece detalhe de implementação e decide se os códigos que começam por zero sobrevivem à primeira exportação. O caso de teste com zero à esquerda transforma essa decisão em algo visível.
A quarta é sobre a normalização. Aceitar entrada com ponto, com hífen e com espaço e gravar sempre no mesmo formato é uma decisão que precisa de caso de teste explícito, porque é fácil implementar metade dela sem perceber.
Limites: dado de teste não é endereço entregável
Os registros produzidos por um gerador são dados sintéticos. A estrutura é a do país escolhido e os campos são coerentes entre si, mas o conjunto não corresponde a um imóvel existente e não deve ser tratado como endereço de entrega, de cobrança ou de cadastro em serviço algum. Ele serve para exercitar o seu software: validar máscara, testar mensagens de erro, popular um ambiente de homologação, verificar como a tela se comporta com dado de outro país.
Também não faz sentido usá-los para simular verificação de identidade, abrir contas ou preencher processos que exijam uma pessoa real. Se o seu objetivo é entender quais divisões e cidades existem em cada país antes de desenhar o formulário, a página de dados de endereço nos Estados Unidos ajuda a ver o conjunto disponível. E se você precisa montar dados de teste para vários países ao mesmo tempo, vale ler o resumo sobre formatos de endereço por país antes de fixar as regras de validação no código.