test-data-patterns

Overview

A catalog of six ways to construct test data. Pick the pattern here, then configure the tool with faker-data or synthetic-data-toolkit.

How to use this catalog

1. Inventory. List how the suite builds data today: grep for inline object literals, shared setUp / beforeAll state, factory files, snapshot files, and any production dump loaded into test databases.
2. Pick. For each entity, choose a pattern from the Pattern-selection guide. One construction pattern per entity type; Builder over Factory is the only common mix.
3. Check. Run the pattern's anti-pattern table against the existing code. Stop and fix any production data that is not anonymised before anything else (Pattern 6).
4. Hand off. Configure the tool with the skill in Hand-off targets, then re-run the suite twice in random order (pytest --random-order with pytest-random-order, jest --randomize) to confirm no test depends on another's data.

Do not use this skill to:

• Configure a specific tool - that's the per-language skill for that tool.
• Generate negative / boundary / parameterized test data - that's negative-test-generator, boundary-value-generator, pairwise-test-case-generator.
• Author an E2E seed fixture for the whole suite - that's seed-data-curator.

Pattern 1 - Test Data Builder

Canonical source: Nat Pryce and Steve Freeman, the Test Data Builder pattern (see References).

Definition: A Test Data Builder is a class with chainable methods (.withName("Alice").withOrgId(42).build()) that constructs domain objects step-by-step. Every field has a sensible default; the test overrides only the fields it cares about.

Concrete implementation (TypeScript, runnable):

type User = { role: string; org: { plan: string } };

class UserBuilder {
  private user: User = { role: "standard", org: { plan: "free" } };
  withRole(role: string) { this.user.role = role; return this; }
  withOrg(org: User["org"]) { this.user.org = org; return this; }
  build(): User { return { ...this.user }; }
}
const aUser = () => new UserBuilder();

// Test overrides only the fields it cares about:
const admin = aUser().withRole("admin").build();

When to use Test Data Builder

• Domain objects have 5+ fields and most tests only care about 1-2.
• The team values explicit "what this test cares about" in the test body.
• The language has chainable / fluent API support (most modern languages).

Anti-patterns

Pattern 2 - Factory (with traits and associations)

Canonical source: Thoughtbot's factory_bot (Ruby) is the cross-language reference implementation; the pattern adapts the Gang of Four Factory Method for test data.

Definition: A Factory is a registered, named template for creating an object. Traits are named modifiers (:admin, :disabled, :premium) that compose with the base template. Associations express relationships (user.org, org.plan).

Example (Ruby FactoryBot, the reference implementation):

factory :user do
  name { Faker::Name.name }
  email { Faker::Internet.email }

  trait :admin do
    role { :admin }
  end

  trait :with_org do
    association :org, factory: :org
  end
end

# Test usage:
admin_user = create(:user, :admin, :with_org)

The same factory in Python (factory_boy reference): traits live in class Params and switch on with one boolean; SubFactory builds the association with the caller's strategy, so build() saves nothing.

import factory

class UserFactory(factory.Factory):
    class Meta:
        model = User

    name = factory.Faker("name")
    email = factory.Faker("email")
    role = "standard"
    org = None

    class Params:
        admin = factory.Trait(role="admin")
        with_org = factory.Trait(org=factory.SubFactory(OrgFactory))

admin_user = UserFactory.build(admin=True, with_org=True)  # not persisted

Cross-language equivalents (canonical per-language tool; URLs in References):

• Ruby: factory_bot - the origin.
• Python: factory_boy - direct port.
• JS/TS: fishery, @faker-js/faker (lower-level).
• .NET: Bogus - Faker-style with factory affordances.
• Java: data-faker + handwritten factory or test-data-builder-style libraries.

When to use Factory

• The project uses a database (factories handle FK relationships via associations).
• The team is on Ruby / Python / JS-TS where mature factory libraries exist.
• Domain objects have many variants (admin / disabled / premium / legacy) - traits express each.

Anti-patterns

Pattern 3 - Object Mother

Canonical source: Martin Fowler, Object Mother (see References). Predates Test Data Builder; superseded by it for most use cases but still useful for stable canonical objects.

Definition: A central class (the "Mother") exposes named methods that return fully-constructed canonical test objects: ObjectMother.standardUser(), ObjectMother.adminUser(), ObjectMother.userInOrgWithFiveMembers().

Fowler's framing: "An Object Mother is a class that contains methods that create well-known objects for use in tests." Useful when the team has a small, stable set of canonical fixtures.

When to use Object Mother

• The domain has a small, stable set of canonical objects ("the test admin", "the seed catalogue").
• The team is on a language without first-class factory libraries (older Java, C++, legacy stacks).
• The Test Data Builder pattern is overkill for the small number of cases.

Anti-patterns

Pattern 4 - Fixture composition

Canonical source: Gerard Meszaros, xUnit Test Patterns - the seminal reference for Fresh Fixture, Shared Fixture, Implicit Setup, Delegated Setup, and Setup Decorator patterns; it defines the four-phase test pattern (setup / exercise / verify / teardown). See References.

Definition: Fixture composition is the pattern of building per-test state from reusable fragments. The three flavours:

Fowler prefers rebuilding state per test because failures are easier to trace, and switches to clean-up only when rebuilding is too slow (Eradicating Non-Determinism in Tests).

When to use Fresh Fixture (default)

• Unit / integration tests with fast setup.
• Tests that mutate state (Shared Fixture would leak across tests).
• Anything parallel-executed.

When to use Shared Fixture

• E2E tests where setup is genuinely expensive (multi-service stack, large seed data).
• Tests that only read the fixture (no mutation).
• The fixture is documented as immutable and the team enforces it.

Anti-patterns

Pattern 5 - Snapshot / golden-file

Canonical source: Jest snapshot testing is the cross-language reference for the test-code side; Michael Feathers' Working Effectively with Legacy Code coined "characterisation tests", the legacy-code-tier version of snapshot testing. See References.

Definition: A snapshot test compares the current output of code under test to a previously-saved canonical output ("the golden file"). When the test runs, it serialises the output, compares against the file, fails if they differ. Engineers explicitly approve a new golden file when the change is intentional.

This skill's role: Snapshot is a recurring concept in test-data conversation, but the operational details (file naming, sanitisation of timestamps / IDs / PII, per-OS variants, review workflow) are documented in detail by golden-file-conventions. Reach for that skill for the operational catalog; this section is the pattern's catalog entry only.

When to use Snapshot

• Output is structured and large (HTML render, JSON response, CLI output).
• Manual assertions would be tedious or wrong (50 fields to check).
• Changes to output are infrequent and require explicit approval anyway.

When NOT to use Snapshot

• Output is non-deterministic (timestamps, UUIDs, locale, PII) - sanitise first or skip the snapshot.
• Output changes frequently - the team will rubber-stamp the snapshot update and lose the test's value.
• The behaviour you care about is one field - write an explicit assertion.

Pattern 6 - Production-Data Anonymisation

Canonical source: GDPR Recital 26: pseudonymised data is still personal data, and only truly anonymous information falls outside the regulation (Recital 26). synthetic-pii-generator is the companion PII-synthesis skill.

Definition: Using production data (or production-shaped data) for testing only after removing or masking personal data, commercially sensitive data, and any field that would breach privacy or compliance if leaked from a test environment.

The three anonymisation flavours

Anti-patterns

Pattern-selection guide

Cross-cutting anti-patterns

Hand-off targets

• Configure a specific per-language tool → faker-data (Python / JS / Ruby) or synthetic-data-toolkit (FactoryBot / mimesis / Bogus).
• Build an E2E seed dataset → seed-data-curator.
• Generate PII (anonymised) test data → synthetic-pii-generator.
• Snapshot / golden-file operational details → golden-file-conventions.
• Generate negative / boundary / malicious test data → negative-test-generator, boundary-value-generator, malicious-payload-bank.
• Cross-test isolation / fixture scope rules → test-isolation-patterns (sister catalog, in the qa-test-review plugin).
• Object-model architecture patterns → object-model-patterns (sister catalog).

References

• Nat Pryce - Test Data Builders (the canonical reference for the Builder pattern as applied to test data): http://www.natpryce.com/articles/000714.html
• Nat Pryce and Steve Freeman - Growing Object-Oriented Software, Guided by Tests (2009), chapter 22: https://www.growing-object-oriented-software.com/
• Martin Fowler - Object Mother (canonical reference for the Object Mother pattern): https://martinfowler.com/bliki/ObjectMother.html
• Martin Fowler - Eradicating Non-Determinism in Tests (Fresh Fixture vs Shared Fixture trade-off, the load-bearing quote on test isolation): https://martinfowler.com/articles/nonDeterminism.html
• Gerard Meszaros - xUnit Test Patterns: Refactoring Test Code (2007) (the seminal reference for fixture patterns; cite by book ISBN 978-0131495050).
• thoughtbot - factory_bot (Ruby; the canonical Factory implementation): https://github.com/thoughtbot/factory_bot
• FactoryBoy team - factory_boy (Python equivalent): https://github.com/FactoryBoy/factory_boy ; reference docs for Trait, SubFactory, Faker, build / create: factory_boy reference
• thoughtbot - fishery (TypeScript Factory): https://github.com/thoughtbot/fishery
• bchavez - Bogus (.NET; Faker-style with factory affordances): https://github.com/bchavez/Bogus
• Jest CLI - --randomize: jestjs.io/docs/cli
• pytest-random-order - --random-order: https://github.com/jbasko/pytest-random-order
• Jest - Snapshot Testing (the cross-language reference for the snapshot pattern): https://jestjs.io/docs/snapshot-testing
• Michael Feathers - Working Effectively with Legacy Code (the characterisation-tests progenitor of golden-file testing): ISBN 978-0131177055.
• Wikipedia - Test fixture (Meszaros's four-phase test pattern): https://en.wikipedia.org/wiki/Test_fixture
• ISTQB glossary - test data: https://glossary.istqb.org/en_US/term/test-data
• ISTQB glossary - fixture: https://glossary.istqb.org/en_US/term/test-fixture
• GDPR Recital 26 - pseudonymised vs anonymous data: gdpr-info.eu
• Anonymisation / synthetic-data tooling: Tonic.ai (https://www.tonic.ai/), Gretel.ai (https://gretel.ai/), K2view (https://www.k2view.com/).
• faker-data, synthetic-data-toolkit, synthetic-pii-generator, golden-file-conventions, seed-data-curator - the per-tool and operational siblings.
• object-model-patterns, test-isolation-patterns - sister architecture-tier pattern catalogs (step design is test-code-conventions §11).