generate-sample-data

Generate mock/sample data from Zod schemas for testing, development, and mocks. Use when creating sample data generators, setting up test fixtures, populating mock APIs, or generating realistic fake d

SKILL.md

GitHub

Skill: Generate Sample Data from Zod Schemas

Generate type-safe, realistic sample data for testing, development, and mock APIs using Zod schema definitions.

When to Use

  • Creating sample data generators for domain models
  • Populating MSW mock API handlers
  • Generating test fixtures
  • Creating Storybook stories
  • Seeding development databases
  • Building realistic demo data

Technology Stack

Package Purpose
@anatine/zod-mock Generates mock data from Zod schemas via generateMock()
@faker-js/faker Provides realistic fake data
Zod Source of truth for type definitions and validation

File Structure

model/
├── Job.ts              # Zod schema + type
├── Job.sample.ts       # Sample generator ← THIS FILE
├── User.ts / User.sample.ts
└── index.ts            # Re-export samples

Standard Function Signature

createEntitySample(options?: { seed?: number; overrides?: Partial<Entity> }): Entity

Two Generation Patterns

Pattern 1: Simple Schemas (Primitives Only)

Use generateMock directly:

import { generateMock } from '@anatine/zod-mock';
import { EntitySchema } from './Entity';

export function createEntitySample(options?: { seed?: number; overrides?: Partial<Entity> }): Entity {
  const mock = generateMock(EntitySchema, { seed: options?.seed });
  return { ...mock, ...options?.overrides };
}

Pattern 2: Composed Schemas (Nested Objects/Arrays)

Compose child samples:

export function createJobSample(options?: { seed?: number; overrides?: Partial<Job> }): Job {
  const mock = generateMock(JobBaseSchema, {
    seed: options?.seed,
    stringMap: {
      name: () => faker.company.name(),
      email: () => faker.internet.email(),
    },
  });
  return { ...mock, ...options?.overrides };
}

Enhancing with Faker

Use Faker for realistic names, emails, phones. Create seeded Faker instances for determinism:

import { faker } from '@faker-js/faker';

// Seeded for determinism
if (options?.seed !== undefined) {
  faker.seed(options.seed);
}

Using in Mock APIs (MSW)

Generate 15-20+ items with variety:

const jobs = Array.from({ length: 20 }, (_, i) =>
  createJobSample({ seed: i, overrides: { status: i % 3 === 0 ? 'COMPLETED' : 'ACTIVE' } })
);

Creating Array Samples

export function createJobSamples(count: number, baseSeed: number = 0): Job[] {
  return Array.from({ length: count }, (_, i) =>
    createJobSample({ seed: baseSeed + i })
  );
}

CRITICAL: Deterministic Dates with Seeds

NEVER use Date.now() or new Date() when a seed is provided!

const baseTimestamp = seed !== undefined
  ? new Date(2026, 1, 20, 10, 0, 0).getTime() + (seed * 1000)
  : Date.now();

Testing Sample Generators

Every generator should have tests for:

  • Validity (validates against schema)
  • Determinism (same seed = same output)
  • Overrides work correctly

Key Principles

  1. Types derive from Zod schemas
  2. JSON serializable only (ISO 8601 strings, not Date objects)
  3. Consistent naming: create[Entity]Sample / create[Entity]Samples
  4. Seed for determinism
  5. Overrides for flexibility
  6. Export from model index
  7. 15-20+ items for lists/tables

Installation

npm install -D @anatine/zod-mock @faker-js/faker