Comparação de ferramentas
FakeForge vs. validate-docbr
As duas ferramentas não competem. validate-docbr é uma biblioteca npm que só valida input do usuário (CPF, CNPJ, CNH, etc). FakeForge gera documentos válidos pra popular seu ambiente de teste. Use as duas juntas.
TL;DR
- validate-docbr: instala como dep Node, chama
cpf.isValid(input)no seu backend/frontend pra checar se o CPF que o user digitou é válido. Zero geração. - FakeForge: gera CPFs, CNPJs, endereços, cartões, PIX válidos pra popular seed de banco, fixture de teste ou mock de checkout. Zero validação de input (pra isso use validate-docbr ou o /validar-cpf da API).
- Combinação natural: validate-docbr no runtime pra validar o que o user digita + FakeForge no CI/staging pra popular banco com dados válidos.
Uso combinado (padrão profissional)
// No teu backend Express/Fastify em produção:
import { cpf } from "@fnando/validate-docbr";
app.post("/signup", (req, res) => {
if (!cpf.isValid(req.body.cpf)) {
return res.status(400).json({ error: "CPF inválido" });
}
// continua signup...
});
// Nos teus testes E2E ou seed de staging:
import { FakeForge } from "fakeforge-br";
const ff = new FakeForge();
const cpfs = await ff.cpf(1000); // 1000 CPFs válidos
for (const cpf of cpfs) {
await request(app).post("/signup").send({ cpf, ...});
}
// Todos os CPFs passam na validação porque foram gerados válidos.As duas bibliotecas funcionam juntas sem overlap. validate-docbr protege a rota real, FakeForge popula o teste.
Comparação lado a lado
| Recurso | FakeForge | validate-docbr |
|---|---|---|
| Gera CPFs válidos | ✅ | ❌ |
| Gera CNPJs válidos | ✅ | ❌ |
| Gera CNPJ alfanumérico 2026 | ✅ | ❌ |
| Gera cartão com Luhn | ✅ | ❌ |
| Gera chave PIX BACEN | ✅ | ❌ |
| Gera pessoa correlacionada | ✅ | ❌ |
| Valida CPF de input | 🔵 (endpoint /validar-cpf) | ✅ |
| Valida CNPJ de input | 🔵 (endpoint /validar-cnpj) | ✅ |
| Valida CNH, RG, PIS, título | ❌ | ✅ |
| Instala como dep npm | ✅ (fakeforge) | ✅ |
| Zero deps runtime | ✅ | ✅ |
| TypeScript nativo | ✅ | ✅ |
| Uso via API HTTP (sem dep) | ✅ | ❌ |
| Free tier grátis | ✅ (50/dia) | ✅ (MIT) |
Quando escolher cada
Use validate-docbr se:
- Você só precisa VALIDAR input do usuário no runtime (formulário de cadastro, checkout)
- Já usa Node.js/TypeScript e quer instalar como dep local sem chamar API externa
- Precisa validar tipos que FakeForge não gera (CNH, RG, PIS, título de eleitor)
Use FakeForge se:
- Você precisa GERAR dados válidos pra popular teste, staging, CI/CD ou mock
- Precisa de correlação entre campos (email deriva do nome, DDD × UF)
- Precisa de CNPJ alfanumérico 2026 ou PIX BACEN completo
- Tem stack polyglot (Node + Python + Go + PHP) e não quer instalar dep em cada linguagem
- Precisa de presets correlacionados (customer, employee, ecommerce_order)
Use as duas juntas se:
- Backend Node com signup real: validate-docbr no runtime + FakeForge no CI
- App fullstack Node com testes E2E: validate-docbr no client-side + FakeForge no Playwright/Cypress fixture
Como migrar ou combinar
Você não migra de uma pra outra - você usa as duas. Instalação típica:
# Adiciona as duas ao projeto
npm install @fnando/validate-docbr fakeforge
# validate-docbr no código de produção (backend/frontend)
# fakeforge nos testes e seeds
# tests/setup.ts
import { FakeForge } from "fakeforge-br";
export const ff = new FakeForge();
# tests/checkout.test.ts
import { cpf } from "@fnando/validate-docbr";
import { ff } from "./setup";
test("checkout aceita CPFs válidos", async () => {
const [pessoa] = await ff.preset("customer", 1);
// Sanity: FakeForge deve gerar CPF que validate-docbr aprove
expect(cpf.isValid(pessoa.cpf)).toBe(true);
// Fluxo real do checkout
const res = await request(app).post("/checkout").send(pessoa);
expect(res.status).toBe(200);
});