Pular para o conteúdo principal
Pular para o conteúdo principal

Documentação @box4dev/gerador-br

A biblioteca definitiva de dados brasileiros para seus testes em Node.js.

Instale o pacote NPM @box4dev/gerador-br e pare de se preocupar com massa de dados. Leve, sem dependências e com uma cobertura completa de dados fictícios para seus testes.

NPM VersionNPM Downloads

Começando

Sobre o @box4dev/gerador-br

Gerador de Dados Fictícios - Brasil

Gere dados fictícios/válidos, para testes e desenvolvimento de Software.

Ideal para testes automatizados com Cypress, Playwright, Jest, Node.js Test Runner, Jasmine, Mocha, Chai, Supertest, Sinon e Puppeteer.

Instalação

Shell
npm install @box4dev/gerador-br

Ou

Shell
yarn add @box4dev/gerador-br

Importação

ES Module:

JS
import { gerar } from '@box4dev/gerador-br';

CommonJS:

JS
const { gerar } = require('@box4dev/gerador-br');

Utilização

Importe apenas a(s) função(ões) que desejar:

JS
import { nome, cpf, cnpj, placaMercosul } from '@box4dev/gerador-br'; // ES Module
// const { nome, cpf, cnpj, placaMercosul } = require('@box4dev/gerador-br'); // CommonJS
console.log(nome.femininoCompleto());
console.log(cpf());
console.log(cnpj());
console.log(placaMercosul());

Ou, importe todo o módulo gerar e depois use qualquer função que desejar:

JS
import { gerar } from '@box4dev/gerador-br'; // ES Module
// const { gerar } = require('@box4dev/gerador-br'); // CommonJS
console.log(gerar.nome.femininoCompleto());
console.log(gerar.cpf());
console.log(gerar.cnpj());
console.log(gerar.contaBancaria());
console.log(gerar.cartaoCredito());

Documentos PF

Exemplo de uso para geração de documentos de Pessoa Física.

CPF

JS
import { cpf } from '@box4dev/gerador-br'; // ES Module
// const { cpf } = require('@box4dev/gerador-br'); // CommonJS
// Gera CPF sem máscara e de estado aleatório
console.log(cpf());
// Gera CPF com máscara e de estado aleatório
console.log(cpf(true));
// Gera CPF com máscara e do estado informado
console.log(cpf(true, "RS"));
// Gera CPF sem máscara e do estado informado
console.log(cpf(false, "MG"));

CNH

JS
import { cnh, cnhCategoria } from '@box4dev/gerador-br'; // ES Module
// const { cnh, cnhCategoria } = require('@box4dev/gerador-br'); // CommonJS
// Gera CNH aleatória
console.log(cnh());
// Gera Categoria CNH
console.log(cnhCategoria());

RG

JS
import { rg } from '@box4dev/gerador-br'; // ES Module
// const { rg } = require('@box4dev/gerador-br'); // CommonJS
// Gera RG sem máscara
console.log(rg());
// Gera RG com máscara
console.log(rg(true));

CNS

JS
import { cns } from '@box4dev/gerador-br'; // ES Module
// const { cns } = require('@box4dev/gerador-br'); // CommonJS
// Gera CNS (Cartão Nacional Saúde) sem máscara e tipo aleatório
console.log(cns());
// Gera CNS sem máscara e do tipo informado
console.log(cns(false, 'beneficiario'));
console.log(cns(false, 'profissional'));
// Gera CNS com máscara e tipo aleatório
console.log(cns(true));
// Gera CNS com máscara e do tipo informado
console.log(cns(true, 'beneficiario'));
console.log(cns(true, 'profissional'));

PIS

JS
import { pis } from '@box4dev/gerador-br'; // ES Module
// const { pis } = require('@box4dev/gerador-br'); // CommonJS
// Gera PIS sem máscara
console.log(pis());
// Gera PIS com máscara
console.log(pis(true));

Título de Eleitor

JS
import { tituloEleitor } from '@box4dev/gerador-br'; // ES Module
// const { tituloEleitor } = require('@box4dev/gerador-br'); // CommonJS
// Gera Título de Eleitor sem máscara e de estado aleatório
console.log(tituloEleitor());
// Gera Título de Eleitor com máscara e de estado aleatório
console.log(tituloEleitor(true));
// Gera Título de Eleitor sem máscara e de estado informado
console.log(tituloEleitor(true, 'SE'));
// Gera Título de Eleitor com máscara e de estado informado
console.log(tituloEleitor(false, 'PR'));

Passaporte

JS
import { passaporte } from '@box4dev/gerador-br'; // ES Module
// const { passaporte } = require('@box4dev/gerador-br'); // CommonJS
// Gera Passaporte aleatório
console.log(passaporte());

Certidão

JS
import { certidao } from '@box4dev/gerador-br'; // ES Module
// const { certidao } = require('@box4dev/gerador-br'); // CommonJS
// Certidão aleatória
console.log(certidao.aleatoria()); // com máscara
console.log(certidao.aleatoria(false)); // sem máscara
// Certidão de nascimento
console.log(certidao.nascimento()); // com máscara
console.log(certidao.nascimento(false)); // sem máscara
// Certidão de casamento
console.log(certidao.casamento()); // com máscara
console.log(certidao.casamento(false)); // sem máscara
// Certidão de óbito
console.log(certidao.obito()); // com máscara
console.log(certidao.obito(false)); // sem máscara
// Objeto com os detalhes de Certidão
console.log(certidao.aleatoriaObj()); // Objeto detalhado de certidão aleatória
console.log(certidao.nascimentoObj()); // Objeto detalhado de certidão de nascimento
console.log(certidao.casamentoObj()); // Objeto detalhado de certidão de casamento
console.log(certidao.obitoObj()); // Objeto detalhado de certidão de óbito

Documentos PJ

Exemplo de uso para geração de documentos de Pessoa Jurídica.

CNPJ

JS
import { cnpj } from '@box4dev/gerador-br'; // ES Module
// const { cnpj } = require('@box4dev/gerador-br'); // CommonJS
// Gera CNPJ sem máscara
console.log(cnpj());
// Gera CNPJ com máscara
console.log(cnpj(true));

CNPJ Alfanumérico

JS
import { cnpjAlfanumerico } from '@box4dev/gerador-br'; // ES Module
// const { cnpjAlfanumerico } = require('@box4dev/gerador-br'); // CommonJS
// Gera CNPJ Alfanumérico com máscara
console.log(cnpjAlfanumerico(true));
// Gera CNPJ Alfanumérico sem máscara
console.log(cnpjAlfanumerico(false));

Inscrição Estadual

JS
import { inscricaoEstadual } from '@box4dev/gerador-br'; // ES Module
// const { inscricaoEstadual } = require('@box4dev/gerador-br'); // CommonJS
// Gera Inscrição Estadual aleatória e do estado informado
console.log(inscricaoEstadual()); // Sem informar o estado
console.log(inscricaoEstadual('AC')); // AC 01.335116638
console.log(inscricaoEstadual('AP')); // AP 03.42773842
console.log(inscricaoEstadual('BA')); // BA 16408652-16
console.log(inscricaoEstadual('DF')); // DF 0724.4814180
console.log(inscricaoEstadual('RJ')); // RJ 41038311.44

Nome Empresa

JS
import { nomeEmpresa } from '@box4dev/gerador-br'; // ES Module
// const { nomeEmpresa } = require('@box4dev/gerador-br'); // CommonJS
// Gera Nome de Empresa baseado em filmes, séries, livros, videogames, animação, hq, etc
console.log(nomeEmpresa()); // Exemplo: "Wayne Enterprises", "Los Pollos Hermanos", "Nakatomi Corporation"
console.log(nomeEmpresa('BR')); // Exemplo: "Indústrias Tabajara", "Vavá Tur"

Bancos

Exemplos de uso para geração de dados bancários.

Banco

JS
import { banco } from '@box4dev/gerador-br'; // ES Module
// const { banco } = require('@box4dev/gerador-br'); // CommonJS
// Gera dados de um banco aleatório
console.log(banco());
// Opcionalmente, atribua o objeto a uma variável e utilize as propriedades
const bnc = banco();
console.log(bnc.codigoBanco);
console.log(bnc.nomeBanco);
console.log(bnc.razaoSocial);
console.log(bnc.ispb);
// Gera dados do banco informado
console.log(banco(237));

Lista de Códigos de Bancos

JS
import { listaCodigosBancos } from '@box4dev/gerador-br'; // ES Module
// const { listaCodigosBancos } = require('@box4dev/gerador-br'); // CommonJS
// Retorna uma lista de códigos de bancos
console.log(listaCodigosBancos());

Cartão de Crédito

JS
import { cartaoCredito, nome } from '@box4dev/gerador-br'; // ES Module
// const { cartaoCredito, nome } = require('@box4dev/gerador-br'); // CommonJS
// Gera objeto cartaoCredito com as propriedades:
// numero (sem máscara), bandeira, cvv, dataExpiracao e nomeTitular aleatório (abreviado)
console.log(cartaoCredito());
// Opcionalmente, atribua o objeto a uma variável e utilize as propriedades
const cc = cartaoCredito();
console.log(cc.numero);
console.log(cc.bandeira);
console.log(cc.cvv);
console.log(cc.dataExpiracao);
console.log(cc.nomeTitular);
// Gera objeto cartaoCredito com as propriedades:
// numero (com máscara), bandeira, cvv, dataExpiracao e nomeTitular informado (abreviado)
console.log(cartaoCredito(true, "João Santos da Silva"));
// Gera objeto cartaoCredito com as propriedades:
// numero (sem máscara), bandeira, cvv, dataExpiracao e nomeTitular informado (abreviado)
console.log(cartaoCredito(false, "Maria Aparecida Reis"));
// Gera objeto cartaoCredito com as propriedades:
// numero (com máscara), bandeira, cvv, dataExpiracao e nomeTitular gerado (abreviado)
console.log(cartaoCredito(true, nome.femininoCompleto()));

Conta Bancária

JS
import { contaBancaria } from '@box4dev/gerador-br'; // ES Module
// const { contaBancaria } = require('@box4dev/gerador-br'); // CommonJS
// Gera uma conta bancária aleatória de um banco aleatório
console.log(contaBancaria());
// Opcionalmente, atribua o objeto a uma variável e utilize as propriedades
const cb = contaBancaria();
console.log(cb.codigoBanco);
console.log(cb.nomeBanco);
console.log(cb.agencia);
console.log(cb.agenciaDv);
console.log(cb.conta);
console.log(cb.contaDv);
// Gera uma conta bancária aleatória do Banco do Brasil
console.log(contaBancaria('1'));
console.log(contaBancaria('Banco do Brasil'));
// Gera uma conta bancária aleatória do Bradesco
console.log(contaBancaria("237"));
console.log(contaBancaria('Bradesco'));
// Gera uma conta bancária aleatória da Caixa
console.log(contaBancaria('104'));
console.log(contaBancaria('Caixa'));
// Gera uma conta bancária aleatória do Citibank
console.log(contaBancaria('745'));
console.log(contaBancaria('Citibank'));
// Gera uma conta bancária aleatória do HSBC
console.log(contaBancaria('296'));
console.log(contaBancaria('HSBC'));
// Gera uma conta bancária aleatória do Itaú
console.log(contaBancaria('341'));
console.log(contaBancaria('Itaú'));
// Gera uma conta bancária aleatória do Santander
console.log(contaBancaria('33'));
console.log(contaBancaria('Santander'));

Pessoas

Exemplo de uso para geração de dados pessoais.

Nome

JS
import { nome } from '@box4dev/gerador-br'; // ES Module
// const { nome } = require('@box4dev/gerador-br'); // CommonJS
// Gera um nome aleatório (feminino ou masculino)
console.log(nome.aleatorio());
// Gera um nome aleatório completo (feminino ou masculino)
console.log(nome.aleatorioCompleto());
// Gera um nome masculino aleatório
console.log(nome.masculino());
// Gera um nome masculino completo aleatório
console.log(nome.masculinoCompleto());
// Gera um nome feminino aleatório
console.log(nome.feminino());
// Gera um nome feminino completo aleatório
console.log(nome.femininoCompleto());
// Gera o nome da mãe aleatório
console.log(nome.mae());
// Gera o nome completo da mãe aleatório
console.log(nome.maeCompleto());
// Gera o nome do pai aleatório
console.log(nome.pai());
// Gera o nome completo do pai aleatório
console.log(nome.paiCompleto());
// Gera um nome do meio aleatório
console.log(nome.doMeio());
// Gera um sobrenome aleatório
console.log(nome.sobrenome());

Apelido

JS
import { apelido } from '@box4dev/gerador-br'; // ES Module
// const { apelido } = require('@box4dev/gerador-br'); // CommonJS
// Gera apelido aleatório
console.log(apelido());

Data de Nascimento

JS
import { dataNascimento } from '@box4dev/gerador-br'; // ES Module
// const { dataNascimento } = require('@box4dev/gerador-br'); // CommonJS
// Gera data de nascimento aleatória
console.log(dataNascimento()); // Data entre 18-80 anos
console.log(dataNascimento(25)); // Data de quem tem exatamente 25 anos
console.log(dataNascimento([30, 40])); // Data entre 30-40 anos

Escolaridade

JS
import { escolaridade } from '@box4dev/gerador-br'; // ES Module
// const { escolaridade } = require('@box4dev/gerador-br'); // CommonJS
// Gera escolaridade
console.log(escolaridade());

Profissão

JS
import { profissao } from '@box4dev/gerador-br'; // ES Module
// const { profissao } = require('@box4dev/gerador-br'); // CommonJS
// Gera profissão
console.log(profissao());

Cor da Pele

JS
import { corPele } from '@box4dev/gerador-br'; // ES Module
// const { corPele } = require('@box4dev/gerador-br'); // CommonJS
// Gera cor de pele aleatória
console.log(corPele());

Tipo Sanguíneo

JS
import { tipoSanguineo } from '@box4dev/gerador-br'; // ES Module
// const { tipoSanguineo } = require('@box4dev/gerador-br'); // CommonJS
// Gera tipo sanguíneo aleatório
console.log(tipoSanguineo());

Gênero

JS
import { genero } from '@box4dev/gerador-br'; // ES Module
// const { genero } = require('@box4dev/gerador-br'); // CommonJS
// Retorna "Feminino"
console.log(genero('f'));
// Retorna "Masculino"
console.log(genero('m'));
// Retorna "Intersexo"
console.log(genero('i'));
// Retorna aleatoriamente "Masculino" ou "Feminino"
console.log(genero());
// Retorna aleatoriamente "Masculino" ou "Feminino"
console.log(genero(null));
// Retorna aleatoriamente "Masculino" ou "Feminino"
console.log(genero('x'));

Orientação Sexual

JS
import { orientacaoSexual } from '@box4dev/gerador-br'; // ES Module
// const { orientacaoSexual } = require('@box4dev/gerador-br'); // CommonJS
// Gera uma orientação sexual aleatória.
console.log(orientacaoSexual()); // "Heterossexual", "Homossexual", "Bissexual", "Assexual", "Pansexual", etc.

Identidade de Gênero

JS
import { identidadeGenero } from '@box4dev/gerador-br'; // ES Module
// const { identidadeGenero } = require('@box4dev/gerador-br'); // CommonJS
// Gera identidade de gênero aleatória.
console.log(identidadeGenero()); // "Cisgênero", "Transgênero" ou "Não binário"

Identidade de Gênero por Orientação Sexual

JS
import { identidadePorOrientacao } from '@box4dev/gerador-br'; // ES Module
// const { identidadePorOrientacao } = require('@box4dev/gerador-br'); // CommonJS
console.log(identidadePorOrientacao('Heterossexual')); // 'Cisgênero' ou 'Transgênero'
console.log(identidadePorOrientacao('Homossexual')); // 'Cisgênero' ou 'Transgênero'
console.log(identidadePorOrientacao('Bissexual')); // 'Cisgênero', 'Transgênero' ou 'Não binário'
console.log(identidadePorOrientacao('Assexual')); // 'Cisgênero', 'Transgênero' ou 'Não binário'
console.log(identidadePorOrientacao('Pansexual')); // 'Cisgênero', 'Transgênero' ou 'Não binário'
console.log(identidadePorOrientacao()); // Retorna uma identidade de gênero aleatória associada a uma orientação sexual aleatória.

Contatos

Exemplo de uso para geração de contato.

E-mail

JS
import { email, nome } from '@box4dev/gerador-br'; // ES Module
// const { email, nome } = require('@box4dev/gerador-br'); // CommonJS
// Gera e-mail com nickname aleatório
console.log(email());
// Gera e-mail com nome masculino
const nomeMasculinoCompleto = nome.masculinoCompleto();
console.log(email(nomeMasculinoCompleto));
// Gera e-mail com nome feminino
const nomeFemininoCompleto = nome.femininoCompleto();
console.log(email(nomeFemininoCompleto));

DDD

JS
import { ddd } from '@box4dev/gerador-br'; // ES Module
// const { ddd } = require('@box4dev/gerador-br'); // CommonJS
// Gera DDD aleatório
console.log(ddd());
// Gera DDD aleatório do estado informado
console.log(ddd("PA"));

Código da Operadora

Nota: A portabilidade numérica não é considerada; o número de telefone celular é gerado puramente com base nas faixas originais das operadoras.

JS
import { codigoOperadora } from '@box4dev/gerador-br'; // ES Module
// const { codigoOperadora } = require('@box4dev/gerador-br'); // CommonJS
// Gera um código da Claro (968, 973, 974, 975, 976, 991, 992, 993 ou 994)
console.log(codigoOperadora("Claro"));
// Gera um código da Oi (984, 985, 986, 987, 988 ou 989)
console.log(codigoOperadora("Oi"));
// Gera um código da Tim (969, 979, 980, 981, 982 ou 983)
console.log(codigoOperadora("Tim"));
// Gera um código da Vivo (967, 971, 972, 995, 996, 997, 998 ou 999)
console.log(codigoOperadora("Vivo"));
// Gera um código de uma operadora aleatória
console.log(codigoOperadora());
// Gera um código de uma operadora aleatória
console.log(codigoOperadora("blablabla"));

Celular

JS
import { celular } from '@box4dev/gerador-br'; // ES Module
// const { celular } = require('@box4dev/gerador-br'); // CommonJS
// Gera celular sem máscara, de estado aleatório e operadora aleatória
console.log(celular()); // "11999999999"
// Gera celular com máscara, de estado aleatório e operadora aleatória
console.log(celular(true)); // "(11) 99999-9999"
// Gera celular sem máscara, do estado informado e operadora aleatória
console.log(celular(false, "SC")); // "48999999999"
// Gera celular com máscara, do estado informado e operadora aleatória
console.log(celular(true, "ES")); // "(27) 99999-9999"
// Gera celular sem máscara, do estado aleatório e operadora informada
console.log(celular(false, "", "Claro")); // "85991999999"
// Gera celular com máscara, do estado informado e operadora informada
console.log(celular(true, "MS", "Vivo")); // "(67) 99799-9999"

Telefone

JS
import { telefone } from '@box4dev/gerador-br'; // ES Module
// const { telefone } = require('@box4dev/gerador-br'); // CommonJS
// Gera telefone sem máscara, de estado aleatório
console.log(telefone()); // "1199999999"
// Gera telefone com máscara, de estado aleatório
console.log(telefone(true)); // "(11) 9999-9999"
// Gera telefone sem máscara, do estado informado
console.log(telefone(false, "SC")); // "4899999999"
// Gera telefone com máscara, do estado informado
console.log(telefone(true, "ES")); // "(27) 9999-9999"

CEP

JS
import { cep } from '@box4dev/gerador-br'; // ES Module
// const { cep } = require('@box4dev/gerador-br'); // CommonJS
// Gera CEP sem máscara de estado aleatório
console.log(cep()); // "12345678"
// Gera CEP com máscara de estado aleatório
console.log(cep(true)); // "12345-678"
// Gera CEP sem máscara de estado informado
console.log(cep(false, "SP")); // "01001000"
// Gera CEP com máscara de estado informado
console.log(cep(true, "SP")); // "01001-000"

Endereço

JS
import { endereco } from '@box4dev/gerador-br'; // ES Module
// const { endereco } = require('@box4dev/gerador-br'); // CommonJS
// Gera um objeto com todos os campos do endereço e de estado aleatório
console.log(endereco());
// Gera um objeto com todos os campos do endereço, o CEP com máscara e de estado aleatório
console.log(endereco(true));
// Gera um objeto com todos os campos do endereço, o CEP sem máscara e de estado aleatório
console.log(endereco(false));
// Gera um objeto com todos os campos do endereço, o CEP com máscara e do estado informado
console.log(endereco(true, "RJ"));
// Gera um objeto com todos os campos do endereço, o CEP sem máscara e do estado informado
console.log(endereco(false, "SP"));
// Opcionalmente, gere um endereço e utilize apenas a propriedade desejada
const end = endereco();
console.log(end.cep);
console.log(end.logradouro);
console.log(end.numero);
console.log(end.complemento); // caso exista
console.log(end.bairro);
console.log(end.localidade);
console.log(end.estado);

Veículos

Exemplo de uso para geração de dados de veículos.

Placa Antiga

JS
import { placaAntiga } from '@box4dev/gerador-br'; // ES Module
// const { placaAntiga } = require('@box4dev/gerador-br'); // CommonJS
// Gera placa no formato antigo com máscara "ABC-1234"
console.log(placaAntiga(true));
// Gera placa no formato antigo sem máscara "ABC1234"
console.log(placaAntiga(false));

Placa Mercosul

JS
import { placaMercosul } from '@box4dev/gerador-br'; // ES Module
// const { placaMercosul } = require('@box4dev/gerador-br'); // CommonJS
// Gera placa no formato Mercosul com máscara "ABC-1D23"
console.log(placaMercosul(true));
// Gera placa no formato Mercosul sem máscara "ABC1D23"
console.log(placaMercosul(false));

RENAVAM

JS
import { renavam } from '@box4dev/gerador-br'; // ES Module
// const { renavam } = require('@box4dev/gerador-br'); // CommonJS
// Gera RENAVAM
console.log(renavam());

Lorem Ipsum

Exemplo de uso para geração de textos genéricos.

Palavra

JS
import { palavra } from '@box4dev/gerador-br'; // ES Module
// const { palavra } = require('@box4dev/gerador-br'); // CommonJS
// Gera uma palavra aleatória
console.log(palavra());

Sentença

JS
import { sentenca } from '@box4dev/gerador-br'; // ES Module
// const { sentenca } = require('@box4dev/gerador-br'); // CommonJS
// Gera uma sentença com quantidade de palavras aleatórias
console.log(sentenca());
// Gera uma sentença com quantidade de palavras definida
console.log(sentenca(10));

Parágrafos

JS
import { paragrafo } from '@box4dev/gerador-br'; // ES Module
// const { paragrafo } = require('@box4dev/gerador-br'); // CommonJS
// Gera um parágrafo com quantidade de palavras aleatórias
console.log(paragrafo());
// Gera um parágrafo com quantidade de sentença informada, cada uma com quantidade de palavras aleatórias
console.log(paragrafo(5));
// Gera um parágrafo com quantidade de sentenças e de palavras informadas.
console.log(paragrafo(3, 8));

Perguntas Frequentes (FAQ)

O @box4dev/gerador-br funciona tanto em CommonJS quanto em ES Modules?
Sim! O pacote é um 'dual package', o que significa que ele suporta nativamente ambos os sistemas de módulos do Node.js. Você pode usar tanto 'import { cpf } from '@box4dev/gerador-br'' (ESM) com 'const { cpf } = require('@box4dev/gerador-br')' (CJS) sem nenhuma configuração adicional.
As funções são puras e não têm dependências externas?
Correto. Todas as funções geradoras são puras, síncronas e não possuem dependências de produção (dependencies). Elas dependem apenas de devDependencies para testes, garantindo que o pacote seja leve e seguro para adicionar ao seu projeto.
Os dados gerados são sempre os mesmos ou aleatórios?
São aleatórios. A cada chamada de uma função como cpf(), um novo número matematicamente válido será gerado. Isso garante uma variedade de dados para seus testes, cobrindo diferentes cenários.
Como posso solicitar uma nova funcionalidade ou reportar um bug?
A melhor forma é através do nosso repositório no GitHub. Por favor, abra uma 'Issue' detalhando sua sugestão ou o problema encontrado. Contribuições através de Pull Requests também são muito bem-vindas!