Skip to main content
Skip to main content

@box4dev/gerador-br Documentation

The definitive Brazilian data library for your Node.js tests. QA tests.

Install the @box4dev/gerador-br NPM package and stop worrying about test data. Lightweight, with no dependencies and complete coverage of fictitious data for your tests.

NPM VersionNPM Downloads

Getting Started

About @box4dev/gerador-br

Brazilian Fictitious Data Generator

Generate fictitious/valid data for testing and software development.

Ideal for automated testing with Cypress, Playwright, Jest, Node.js Test Runner, Jasmine, Mocha, Chai, Supertest, Sinon, and Puppeteer.

Installation

Shell
npm install @box4dev/gerador-br

Or

Shell
yarn add @box4dev/gerador-br

Import

ES Module:

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

CommonJS:

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

Usage

Import only the function(s) you need:

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());

Or import the entire 'gerar' module and use any function you want:

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());

Personal Documents

Usage examples for generating Individual Person documents.

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));

Voter ID

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'));

Passport

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

Certificate

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

Company Documents

Usage examples for generating Legal Entity documents.

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));

Alphanumeric CNPJ

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));

State Registration

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

Company Name

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"

Banks

Usage examples for generating banking data.

Bank

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));

Bank Codes List

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());

Credit Card

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()));

Bank Account

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'));

People

Usage examples for generating personal data.

Name

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());

Nickname

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

Birth Date

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

Education

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

Profession

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

Skin Color

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());

Blood Type

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());

Gender

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'));

Sexual Orientation

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.

Gender Identity

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"

Gender Identity by Sexual Orientation

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.

Contacts

Usage examples for generating contact information.

Email

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"));

Carrier Code

Note: Number portability is not considered; the mobile phone number is generated purely based on the operators' original ranges.

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"));

Mobile

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"

Phone

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"

Address

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);

Vehicles

Usage examples for generating vehicle data.

Old License Plate

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));

Mercosul License Plate

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

Usage examples for generating generic texts.

Word

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

Sentence

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));

Paragraphs

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));

Frequently Asked Questions (FAQ)

Does @box4dev/gerador-br work with both CommonJS and ES Modules?
Yes! The package is a 'dual package', which means it natively supports both Node.js module systems. You can use both 'import { cpf } from '@box4dev/gerador-br'' (ESM) and 'const { cpf } = require('@box4dev/gerador-br')' (CJS) without any additional configuration.
Are the functions pure and without external dependencies?
Correct. All generator functions are pure, synchronous, and have no production dependencies. They only depend on devDependencies for testing, ensuring the package is lightweight and safe to add to your project.
Are the generated data always the same or random?
They are random. Each time you call a function like cpf(), a new mathematically valid number will be generated. This ensures a variety of data for your tests, covering different scenarios.
How can I request a new feature or report a bug?
The best way is through our GitHub repository. Please open an 'Issue' detailing your suggestion or the problem you found. Contributions through Pull Requests are also very welcome!