Adding a Field: Complete Testing Guide

Step-by-step guide to adding or modifying a field with full type-safe testing infrastructure. From Drizzle schema to E2E tests.

Type Chain Overview

Drizzle Schema

lib/db/schema.ts

→

drizzle-zod

lib/api/schemas/_base/*.ts

→

Enhanced Schemas

lib/api/schemas/*.ts

→

OpenAPI Spec

public/openapi.json

→

Type Definitions

lib/api/types/openapi.d.ts

→

MSW Handlers

lib/mocks/handlers/*.ts

→

Fixtures

lib/mocks/fixtures/index.ts

→

Storybook + E2E

tests/

1. Update Drizzle Schema

The Drizzle schema in lib/db/schema.ts is the single source of truth. All types, validations, and mocks derive from it.

Example: Adding a "preferredContactMethod" field to clients

lib/db/schema.ts

import { pgTable, text, uuid, timestamp } from 'drizzle-orm/pg-core'

export const clientsTable = pgTable('clients', {
  id: uuid('id').primaryKey().defaultRandom(),
  organizationId: text('organization_id').notNull(),
  firstName: text('first_name').notNull(),
  lastName: text('last_name').notNull(),
  email: text('email'),
  phone: text('phone'),

  // NEW FIELD: Add the column definition
  preferredContactMethod: text('preferred_contact_method')
    .notNull()
    .default('email'),

  createdAt: timestamp('created_at').defaultNow().notNull(),
  updatedAt: timestamp('updated_at').defaultNow().notNull(),
})

💡 Key Decisions

• .notNull() vs nullable: Required fields use notNull()
• .default('value'): Provide sensible defaults
• Column type: text, integer, boolean, timestamp, enum, etc.