Skip to content

reproducible-datasets.md

Latest commit

 

History

History
194 lines (140 loc) · 4.28 KB

reproducible-datasets.md

File metadata and controls

194 lines (140 loc) · 4.28 KB
Raw

Reproducible datasets

README · Docs · Guides · Packages

Generate deterministic datasets — same seed, same output, every run, every machine. For test fixtures, CI pipelines, or shared staging data.

Guides · Quick start · Determinism · Configs · CLI reference

Contents

The problem

faker.js, Faker, and similar libraries generate random data by default. Tests that depend on random values break unpredictably: snapshot mismatches, flaky assertions, CI reruns that waste time. Pinning a numeric seed helps until the library updates its algorithm and every fixture changes.

seedfaker with --seed produces byte-identical output across runs, machines, and languages. A fingerprint guard catches algorithm changes between versions.

Basic usage

seedfaker name email --seed ci-2026 --until 2026 -n 100 --format csv > test/fixtures/users.csv

Run it twice. Diff the output. Zero differences.

name,email
Tariq bin Saif Al Osaimi,echeverriamartina@entelchile.net
Martina De la Cruz Flores,flor.coelho@tap.pt
Bu Fangyi,luzlozano@hey.com
...

Config files

For fixtures with multiple columns, modifiers, or expressions, use a YAML config:

columns:
  id: serial
  name: name
  email: email
  role: enum:admin=1,user=9
options:
  seed: ci-2026
  until: 2026
  count: 100
  format: csv
seedfaker run fixtures.yaml > test/fixtures/users.csv

Multi-table fixtures

Define multiple tables in one config and generate all at once:

options:
  seed: ci-2026
  until: "2026"
  format: csv

users:
  columns:
    id: serial
    name: name
    email: email
  options:
    count: 100

orders:
  columns:
    id: serial
    user_id: users.id
    user_name: user_id->name
    amount: amount:plain:1..5000
  options:
    count: 500
seedfaker run fixtures.yaml --all --output-dir test/fixtures/

This writes test/fixtures/users.csv and test/fixtures/orders.csv.

Cross-language parity

The same seed produces identical values in Python and Node.js tests:

from seedfaker import SeedFaker

rows = SeedFaker(seed="ci-2026", until="2026").records(["name", "email"], 10)
const { SeedFaker } = require("@opendsr/seedfaker");

const rows = new SeedFaker({ seed: "ci-2026", until: "2026" })
  .records(["name", "email"], { n: 10 });

Both produce the same 10 rows.

Fingerprint guard

seedfaker includes a stable algorithm fingerprint. Pin it in your config to detect algorithm changes between versions:

columns:
  name: name
  email: email
options:
  seed: ci-2026
  until: 2026
  count: 50
  format: csv
  fingerprint: sf0-a1b2c3d4

Mismatch = immediate failure, not silent drift.

Current fingerprint:

seedfaker --fingerprint
sf0-158dc9f79ce46b43

Validation in CI

Check config syntax and field names without generating data:

seedfaker run fixtures.yaml --validate

No output on success, exit code 0.

GitHub Actions

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - name: Install seedfaker
        run: cargo install seedfaker

      - name: Validate fixture config
        run: seedfaker run fixtures.yaml --all --output-dir test/fixtures/ --validate

      - name: Generate fixtures
        run: seedfaker run fixtures.yaml --all --output-dir test/fixtures/

      - name: Run tests
        run: make test

Tips

Always pin --until — without it, temporal fields use current time and fixtures differ across days:

seedfaker name timestamp --seed ci --until 2026 -n 10   # stable forever

Add a Makefile target for regeneration:

fixtures:
	seedfaker run fixtures.yaml --all --output-dir test/fixtures/

README · Docs · Guides · Packages