Test Data Builder

Demo

Click to play with sound.

---
name: Test Data Builder
description: Builds realistic domain fixtures, factories, and edge-case datasets with the builder pattern and valid defaults. Use when a test needs domain objects, seed data, factories, or boundary/edge-case inputs; do NOT use when a test needs to fake a network call, database, clock, or third-party SDK — use mock-stub-designer instead.
---
# Test Data Builder

Produce per-test domain data that is realistic, deterministic, and isolated, so each test owns exactly the objects it asserts on.

## Workflow

1. **Build per test, never share a global fixture.** Construct the objects each test needs inside that test via a factory or builder (FactoryBot, Fishery, test-data-bot, Mother objects). Do not load one static fixture file for the suite — shared mutable fixtures become an append-only god object where one test's tweak to a record silently couples and flakes another.
2. **Expose a builder with valid defaults; override only what the test cares about.** Write `aUser().withRole('admin').build()` so the intent is the override and the reader ignores the irrelevant fields. Defaults must always produce a valid object: when a new required field is added, set it once in the factory so unrelated tests do not break.
3. **Make data realistic but deterministic.** Use Faker (Faker, faker.js, Bogus) for names, emails, and addresses so fixtures resemble production and surface encoding/length bugs. Seed the faker with a fixed seed in CI so a failing run reproduces. Randomness varies the shape of inputs — it must never decide whether an assertion passes.
4. **Build the inputs that break code.** Deliberately construct empty strings, unicode and emoji, very long strings, leading/trailing whitespace, nulls, zero, negative numbers, max integers, timezone-boundary dates, and duplicate keys. For ranges, build the boundary and the just-over-boundary value. For input spaces too large to enumerate, reach for property-based generators (Hypothesis, fast-check).
5. **Keep persistence cheap and isolated.** Build in memory by default; only persist (`create` vs `build`) when the test needs a real row. Wrap DB-touching tests in a transaction rolled back per test so factories never leak state. Do not rely on sequences or global counters surviving across tests.

## Quality bar

- Every factory's defaults alone produce a valid, persistable object.
- A reader can tell what a test asserts from its overrides without reading the factory.
- The suite passes identically on repeated runs and in any order; no test depends on another's data.
- Edge-case tests name the specific boundary they exercise.

## Do NOT