O Faker no Node.js gera nomes, e-mails, endereços, produtos, datas, números e outros dados fictícios para testes, demonstrações e ambientes locais. A biblioteca reduz a repetição de fixtures manuais e ajuda a criar conjuntos maiores para testar paginação, filtros, relatórios e desempenho.
Dados aleatórios sem controle, porém, tornam falhas difíceis de reproduzir. A estratégia correta usa seeds, locales explícitos, limites válidos e builders de domínio. Faker deve gerar entradas plausíveis, enquanto factories e Test Data Builders garantem que os objetos respeitem as regras do sistema.
Neste guia, você aprenderá a instalar Faker, usar seeds, gerar dados localizados, criar factories, evitar colisões, produzir grandes volumes, integrar com bancos e manter testes determinísticos.
Instalação
A documentação oficial do Faker recomenda instalar como dependência de desenvolvimento:
npm install --save-dev @faker-js/fakerFaker v10 exige Node.js 20 ou superior. Em CommonJS, verifique a versão mínima específica do runtime.
Primeiro exemplo
import { faker } from '@faker-js/faker';
const user = {
id: faker.string.uuid(),
name: faker.person.fullName(),
email: faker.internet.email(),
phone: faker.phone.number(),
createdAt: faker.date.past()
};
console.log(user);Seed para reprodução
faker.seed(12345);
console.log(faker.person.fullName());A mesma versão, seed e sequência de chamadas produzem resultados repetíveis. Se uma chamada nova for inserida antes, os valores seguintes podem mudar; não dependa de um nome exato quando o teste só precisa de formato válido.
Seed por teste
beforeEach(() => {
faker.seed(20260913);
});Outra opção é criar seed com base no nome do teste e registrá-la quando houver falha.
Locale brasileiro
import { Faker, pt_BR } from '@faker-js/faker';
const fakerBR = new Faker({ locale: [pt_BR] });
const customer = {
name: fakerBR.person.fullName(),
city: fakerBR.location.city(),
state: fakerBR.location.state({ abbreviated: true })
};Declare o locale, pois defaults podem mudar e dados internacionais podem não refletir o cenário esperado.
Factory de usuário
type User = {
id: string;
name: string;
email: string;
role: 'customer' | 'admin';
createdAt: Date;
};
export function fakeUser(
overrides: Partial<User> = {}
): User {
return {
id: faker.string.uuid(),
name: faker.person.fullName(),
email: faker.internet.email().toLowerCase(),
role: 'customer',
createdAt: faker.date.recent({ days: 30 }),
...overrides
};
}O teste sobrescreve apenas o campo relevante:
const admin = fakeUser({ role: 'admin' });Combinação com builders
const order = new OrderBuilder()
.withCustomerId(faker.string.uuid())
.withItems(
faker.helpers.multiple(
() => new OrderItemBuilder()
.withName(faker.commerce.productName())
.build(),
{ count: 3 }
)
)
.build();Veja Test Data Builders no Node.js.
Números com limites
const quantity = faker.number.int({ min: 1, max: 20 });
const price = faker.number.int({ min: 100, max: 100000 });Evite gerar valores fora do domínio quando o teste não é sobre validação.
Decimais e dinheiro
Prefira centavos inteiros:
const priceInCents = faker.number.int({
min: 100,
max: 500000
});Floats podem introduzir erros de precisão e valores com casas inesperadas.
Datas
const start = new Date('2026-01-01T00:00:00Z');
const end = new Date('2026-12-31T23:59:59Z');
const date = faker.date.between({ from: start, to: end });Use intervalos fixos para evitar testes que mudam com o relógio.
Datas relacionadas
const createdAt = faker.date.past({ years: 1 });
const updatedAt = faker.date.between({
from: createdAt,
to: new Date('2026-09-13T00:00:00Z')
});Garanta invariantes como updatedAt >= createdAt.
Escolhas
const status = faker.helpers.arrayElement([
'pending',
'paid',
'cancelled'
]);Para pesos diferentes:
const status = faker.helpers.weightedArrayElement([
{ value: 'paid', weight: 7 },
{ value: 'pending', weight: 2 },
{ value: 'cancelled', weight: 1 }
]);Vários registros
const users = faker.helpers.multiple(
() => fakeUser(),
{ count: 100 }
);Para volume alto, gere em batches e evite armazenar milhões de objetos simultaneamente.
Valores únicos
Dados aleatórios podem colidir. Para e-mails realmente únicos:
function fakeUniqueEmail(index: number) {
return `user-${index}@example.test`;
}Um contador é mais previsível do que repetir geração até encontrar valor livre.
Domínios reservados
Use example.com, example.org ou .test para evitar enviar mensagens a endereços reais.
const email = `customer-${index}@example.test`;Telefones e documentos
Faker produz strings plausíveis, não necessariamente válidas pelas regras brasileiras. Se CPF, CNPJ ou telefone válido é requisito, use gerador específico testado ou builders com fixtures conhecidas.
Dados inválidos
Para testar validação, crie valores explícitos:
const invalidEmails = [
'',
'sem-arroba',
'@example.com',
'user@'
];Não dependa de Faker gerar um caso inválido por acaso.
Seed em CI
const seed = Number(process.env.TEST_SEED ?? 12345);
faker.seed(seed);
console.log(`Faker seed: ${seed}`);Registre a seed para reproduzir uma falha localmente.
Seed aleatória controlada
const seed = process.env.TEST_SEED
? Number(process.env.TEST_SEED)
: crypto.randomInt(1, 2_147_483_647);
faker.seed(seed);Esse modelo explora variedade e mantém reprodução pelo log.
Banco de dados
for (let offset = 0; offset < 10000; offset += 500) {
const rows = Array.from({ length: 500 }, (_, index) => ({
id: faker.string.uuid(),
email: `user-${offset + index}@example.test`,
name: faker.person.fullName()
}));
await database.users.insertMany(rows);
}Use transação ou banco descartável. Consulte Testcontainers no Node.js.
Seeds de desenvolvimento
Crie comando separado:
{
"scripts": {
"db:seed": "tsx scripts/seed-database.ts"
}
}Bloqueie execução acidental em produção:
if (process.env.NODE_ENV === 'production') {
throw new Error('Seed proibido em produção');
}Fixtures de API
const response = {
data: faker.helpers.multiple(() => fakeUser(), { count: 10 }),
nextCursor: faker.string.alphanumeric(32)
};Use em mocks de clientes e demos, mantendo o schema real.
Testes de desempenho
Faker pode criar dados antes do teste, mas gerar durante a medição distorce os resultados. Prepare o conjunto e depois execute Autocannon no Node.js ou k6.
Snapshots
Defina seed e datas fixas antes de snapshots. Mesmo assim, prefira assertions específicas quando o objeto possui muitos campos aleatórios.
Não usar em produção
Faker deve ficar em devDependencies. Não importe em código executado pelo servidor. Isso aumenta bundle e pode criar dados fictícios em fluxos reais.
Tree shaking
Importe a instância necessária e avalie o formato recomendado pela versão. Em scripts de teste, o impacto de bundle geralmente é irrelevante; em demos de navegador, imports específicos podem reduzir tamanho.
Locales e tamanho
Importar muitos locales aumenta memória. Crie uma instância com apenas o locale usado.
Factories por domínio
test/factories/
├── user-factory.ts
├── order-factory.ts
├── payment-factory.ts
└── product-factory.tsEvite um arquivo fake-data.ts gigante.
Contratos TypeScript
Use satisfies:
const user = {
id: faker.string.uuid(),
name: faker.person.fullName(),
email: faker.internet.email()
} satisfies UserDTO;Isso detecta campos ausentes sem alterar inferência.
Validação das factories
Quando há schema:
const user = fakeUser();
const result = UserSchema.safeParse(user);
assert.equal(result.success, true);Veja Zod no Node.js quando o artigo estiver disponível; alternativamente use o validador adotado pelo projeto.
Node Test Runner
import test from 'node:test';
import assert from 'node:assert/strict';
test('factory permite override', () => {
faker.seed(1);
const user = fakeUser({ role: 'admin' });
assert.equal(user.role, 'admin');
});Consulte Node Test Runner.
Erros comuns
- Sem seed: falha não reproduz.
- Seed sem log: CI não pode ser repetida.
- Dados aleatórios em assertion: intenção fica escondida.
- Colisão de campo único: teste falha ocasionalmente.
- Datas relativas: resultado muda com o dia.
- Faker em produção: dependência e risco aumentam.
- Dados pessoais plausíveis demais: podem ser confundidos com dados reais.
- Volume gerado durante benchmark: medição é contaminada.
Configuração recomendada
import { Faker, pt_BR } from '@faker-js/faker';
export const testFaker = new Faker({
locale: [pt_BR]
});
export function setTestSeed(seed = 12345) {
testFaker.seed(seed);
return seed;
}
export function fakeCustomer(overrides = {}) {
return {
id: testFaker.string.uuid(),
name: testFaker.person.fullName(),
email: testFaker.internet.email().toLowerCase(),
createdAt: new Date('2026-01-01T00:00:00Z'),
...overrides
};
}Conclusão
O Faker no Node.js facilita dados fictícios para testes, seeds, demos e carga. O valor aparece quando a aleatoriedade é controlada por seeds, limites e factories de domínio.
Use datas fixas, identificadores únicos determinísticos e locales explícitos. Com Test Data Builders e validação de schemas, Faker adiciona variedade sem transformar a suíte em um conjunto de falhas intermitentes.
