test-data-patterns

Overview

This skill is a pure reference - no execution steps. It is the catalog cited when auditing a test framework's data-construction approach. It complements faker-data, synthetic-data-toolkit (FactoryBot / mimesis / Bogus), synthetic-pii-generator (cross-language), and golden-file-conventions (snapshot pattern). Those skills document the tools; this skill documents the patterns.

When to use

• Designing test-data construction strategy for a new framework - pick the right pattern before reaching for the tool.
• Auditing an existing framework where test data is the bottleneck (every test re-creates the world; tests run for minutes; data drifts between tests).
• Migrating between tools (Ruby's FactoryBot → Python's factory_boy, JS's Fishery → Python's Polyfactory) - the pattern stays; the tool changes.
• Onboarding engineers - point them at the canonical pattern citation.

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, cited as the canonical 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)

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 on the trade-off (Eradicating Non-Determinism in Tests): "I prefer the former [Fresh Fixture], as it's often easier - and in particular easier to find the source of a problem." But: "rebuilding the database each time can add a lot of time to test runs, so that argues for switching to a clean-up strategy."

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: ISO/IEC 25024 (data quality) and GDPR / CCPA requirements; synthetic-pii-generator is the companion PII-synthesis skill. Tooling vendors listed in References.

Definition: Anonymisation is the technique of using production data (or production-shaped data) for testing after removing or masking personally-identifiable information (PII), commercially-sensitive data, and any field that would breach privacy / compliance if leaked to a test environment.

Why this is a pattern, not just a tool concern: The pattern dictates that no production data enters a test environment without anonymisation - even if the test environment is "internal only." Cross-environment data leakage is a dominant security failure mode in test-data management (2025 Verizon DBIR; see References).

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
• thoughtbot - fishery (TypeScript Factory): https://github.com/thoughtbot/fishery
• bchavez - Bogus (.NET; Faker-style with factory affordances): https://github.com/bchavez/Bogus
• 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
• 2025 Verizon DBIR - cited for the cross-environment data leakage risk in production-data testing: https://www.verizon.com/business/resources/reports/dbir/
• 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
• ISO/IEC 25024 - data quality model (cited for anonymisation requirements).
• 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).