0.2.0 • Published yesterday

fakeforge-br

Licence

MIT

Version

0.2.0

Deps

Size

44 kB

Vulns

Weekly

Summary Dependency Versions

fakeforge

SDK oficial do FakeForge para Node.js e TypeScript — gera dados brasileiros válidos (CPF, CNPJ, CEP, PIX, cartão de crédito) para testes de software.

Zero dependências (usa fetch nativo do Node 18+)
TypeScript nativo com types completos
CJS + ESM builds
Validação real — todos os documentos passam mod-11 da Receita Federal, Luhn, ANATEL
Presets correlacionados — pessoa completa com CPF + email + endereço + telefone coerentes em 1 chamada
CNPJ alfanumérico 2026 — cobertura do novo formato (IN RFB 2.229)
Grátis — 50 chamadas/dia sem API key, ou 10.000/dia com plano Dev (R$29/mês)

Instalação

npm install fakeforge-br

pnpm add fakeforge

yarn add fakeforge

Uso rápido

import { FakeForge } from "fakeforge-br";

const ff = new FakeForge();

// CPFs válidos (mod-11 da Receita Federal)
const cpfs = await ff.cpf(10);
// ["123.456.789-09", "987.654.321-00", ...]

// CNPJs válidos (mod-11)
const cnpjs = await ff.cnpj(5);

// Chave PIX no formato BACEN (CPF, email, telefone ou UUID)
const pix = await ff.pixKey(3);

// Cartão de crédito com Luhn válido
const cartoes = await ff.creditCard(5);
// [{ number, brand, cvv, expiry }, ...]

// Pessoa completa correlacionada
const pessoa = await ff.person(1);
// [{ name, cpf, email, phone, birthdate, address }]

Presets: dados correlacionados em 1 chamada

Presets retornam objetos com múltiplos campos que se relacionam entre si — email deriva do nome, DDD bate com o estado do endereço, etc.

const customers = await ff.preset("customer", { quantity: 100 });

for (const c of customers) {
  console.log({
    name: c.name,           // "João Silva Souza"
    cpf: c.cpf,             // "123.456.789-09" (mod-11 válido)
    email: c.email,         // "joao.silva.souza@gmail.com" (derivado do nome)
    phone: c.phone,         // "(11) 98765-4321" (DDD bate com estado)
    address: c.address,     // { city: "São Paulo", state: "SP", ... }
  });
}

Presets disponíveis:

Preset	Retorna
`customer`	pessoa + endereço + email + telefone + PIX
`employee`	pessoa + conta bancária + PIX
`company`	empresa + endereço + contato
`ecommerce_order`	cliente + cartão + entrega
`contact_list`	nome + email + telefone

Comparação com Faker.js

Recurso	Faker.js (pt-BR)	fakeforge
CPF com mod-11 válido	(só formato)
CNPJ com mod-11 válido
CNPJ alfanumérico 2026
Cartão com Luhn
PIX BACEN (4 formatos)
Correlação entre campos (email deriva do nome, DDD bate com UF)
DDDs oficiais ANATEL		(67 DDDs)
Bancos brasileiros reais (17)
CEPs válidos por estado

Se você usa Faker.js hoje só pra nome/endereço, funciona bem. Se precisa de CPF/CNPJ que passe validação (não só formato), use fakeforge.

Uso com pytest, jest, vitest

Vitest / Jest fixture

// setup.ts
import { FakeForge } from "fakeforge-br";
import { beforeAll } from "vitest";

const ff = new FakeForge();
let customers: unknown[];

beforeAll(async () => {
  customers = await ff.preset("customer", { quantity: 500 });
});

export function getCustomer(i: number) {
  return customers[i];
}

// checkout.test.ts
import { test, expect } from "vitest";
import { getCustomer } from "./setup";

test("checkout aceita cartão válido do customer", async () => {
  const customer = getCustomer(0);
  const response = await api.post("/checkout", customer);
  expect(response.status).toBe(200);
});

Playwright E2E

import { test } from "@playwright/test";
import { FakeForge } from "fakeforge-br";

const ff = new FakeForge();

test("signup fluxo completo", async ({ page }) => {
  const [pessoa] = await ff.person(1);

  await page.goto("/signup");
  await page.fill("#nome", pessoa.name);
  await page.fill("#cpf", pessoa.cpf);
  await page.fill("#email", pessoa.email);
  await page.fill("#telefone", pessoa.phone);
  await page.click("#continuar");

  // Formato válido = passa validação de front
  await expect(page.locator(".error")).toHaveCount(0);
});

Prisma seed

// prisma/seed.ts
import { PrismaClient } from "@prisma/client";
import { FakeForge } from "fakeforge-br";

const prisma = new PrismaClient();
const ff = new FakeForge({ apiKey: process.env.FAKEFORGE_API_KEY });

async function main() {
  const customers = await ff.preset("customer", { quantity: 1000 });

  await prisma.customer.createMany({
    data: customers.map((c: any) => ({
      cpf: c.cpf,
      name: c.name,
      email: c.email,
      phone: c.phone,
    })),
  });

  console.log(`✓ Seed: ${customers.length} customers inseridos`);
}

main();

API key opcional (plano Dev/Team)

Sem API key: 50 chamadas/dia por IP, até 100 items por chamada. Perfeito pra dev local.

Com API key do plano Dev (R$29/mês): 10.000 chamadas/dia, até 10.000 items por chamada. Ideal pra CI/CD, seed em produção, load test.

const ff = new FakeForge({ apiKey: process.env.FAKEFORGE_API_KEY });
const cpfs = await ff.cpf(10_000); // no Dev, cabe em 1 chamada

Pegue sua API key em fakeforge.com.br/dashboard.

Tratamento de erros

import { FakeForge, FakeForgeError } from "fakeforge-br";

const ff = new FakeForge();

try {
  const cpfs = await ff.cpf(1000);
} catch (err) {
  if (err instanceof FakeForgeError && err.status === 429) {
    console.error(`Rate limit atingido: ${err.usedToday}/${err.dailyLimit}`);
    console.error(`Assine plano Dev: ${err.upgradeUrl}`);
  } else {
    throw err;
  }
}

API completa

Métodos por tipo de dado

cpf(quantity?, formatted?) — CPFs válidos
cnpj(quantity?, formatted?) — CNPJs numéricos válidos
cnpjAlfa(quantity?, formatted?) — CNPJs alfanuméricos (IN RFB 2.229, 01/07/2026)
cep(quantity?, formatted?) — CEPs válidos por estado
address(quantity?, formatted?) — endereços completos
phone(quantity?, formatted?) — celulares ANATEL (9 na frente)
landline(quantity?, formatted?) — fixos residenciais (10 dígitos)
email(quantity?) — emails com nomes BR
person(quantity?, formatted?) — pessoa completa correlacionada
creditCard(quantity?, formatted?) — cartão com Luhn
pixKey(quantity?) — chave PIX (CPF/email/tel/EVP)
bankAccount(quantity?, formatted?) — conta bancária com DV por banco
company(quantity?, formatted?) — empresa (CNPJ + razão social + endereço)
cnh(quantity?, formatted?) — CNH DENATRAN
rg(quantity?, formatted?) — RG por estado
pis(quantity?, formatted?) — PIS/PASEP/NIT/NIS
renavam(quantity?, formatted?) — RENAVAM DENATRAN
placa(quantity?) — placa Mercosul

Presets

preset("customer", options)
preset("employee", options)
preset("company", options)
preset("ecommerce_order", options)
preset("contact_list", options)

Genérico

generate<T>(type, options) — chama a API com qualquer type

Sim. Gerar números que passam validação matemática (mod-11) pra fins de teste é prática padrão em desenvolvimento. Crime é usar CPF/CNPJ (fake ou real) pra fraude, sonegação ou cadastro em nome de terceiro.

Os dados gerados batem no DICT/SPC/Serasa?

Não. São dados matematicamente válidos mas não existem em nenhuma base oficial. Perfeito pra teste de formato, validação de front-end e seed de staging. Não serve pra teste com API externa que consulta base real.

Como configurar em CI/CD?

# .github/workflows/test.yml
- name: Rodar testes com FakeForge
  env:
    FAKEFORGE_API_KEY: ${{ secrets.FAKEFORGE_API_KEY }}
  run: pnpm test

Cache dos dados gerados na primeira chamada evita esgotar quota:

// tests/fixtures/customers.ts
import fs from "node:fs/promises";
import path from "node:path";
import { FakeForge } from "fakeforge-br";

const CACHE = path.join(__dirname, "customers.json");

export async function getCustomers() {
  try {
    return JSON.parse(await fs.readFile(CACHE, "utf8"));
  } catch {
    const ff = new FakeForge();
    const customers = await ff.preset("customer", { quantity: 100 });
    await fs.writeFile(CACHE, JSON.stringify(customers, null, 2));
    return customers;
  }
}

Qual a diferença entre fakeforge, faker-br, python-brasilidades e validate-docbr?

Biblioteca	Linguagem	Foco	Validação real
fakeforge	Node/TS	Todos os documentos BR + presets correlacionados	mod-11, Luhn, ANATEL, BACEN
faker-js/faker (pt-BR)	JS/TS	Localização genérica (nome, endereço)	(formato apenas)
validate-docbr	JS	Só validação de CPF/CNPJ, não geração	validação
python-brasilidades	Python	Documentos BR
laravel-brasil	PHP	Documentos BR
caelum-stella	Java	Documentos BR

fakeforge é o único com API HTTP + SDK que permite escalar geração em CI/CD sem instalar dependência de biblioteca em cada linguagem do stack.

Suporte

Docs completos: fakeforge.com.br/docs
Email direto: hey@fakeforge.com.br
Issues: github.com/everpaula/fakeforge-br/issues

Licença

MIT — veja LICENSE para detalhes.

Feito por Everton Paula — engenheiro brasileiro que precisou de dados válidos pra testar checkout PIX e escreveu essa lib porque nenhuma outra funcionava direito.

Keywords

cpf cnpj cep pix gerador brazilian brazil faker testing mock fixture seed fake-data test-data typescript