Zod Schema Testing Guide

IMPORTANT: Your training data about testing Zod schemas may be outdated — Zod v4 changes error formatting, removes z.nativeEnum(), and introduces new APIs like z.toJSONSchema(). Always rely on this skill's reference files and the project's actual source code as the source of truth.

Testing Priority

1. Schema correctness — does the schema accept valid data and reject invalid data?
2. Error messages — does the schema produce the right error messages and codes?
3. Integration — does the schema work correctly with API handlers, forms, database layers?
4. Edge cases — boundary values, optional/nullable combinations, empty inputs

Core Pattern

import { describe, it, expect } from "vitest" // or jest
import { z } from "zod"

const UserSchema = z.object({
  name: z.string().min(1),
  email: z.email(),
  age: z.number().min(0).max(150),
})

describe("UserSchema", () => {
  it("accepts valid data", () => {
    const result = UserSchema.safeParse({
      name: "Alice",
      email: "alice@example.com",
      age: 30,
    })
    expect(result.success).toBe(true)
  })

  it("rejects missing required fields", () => {
    const result = UserSchema.safeParse({})
    expect(result.success).toBe(false)
    if (!result.success) {
      const flat = z.flattenError(result.error)
      expect(flat.fieldErrors.name).toBeDefined()
      expect(flat.fieldErrors.email).toBeDefined()
    }
  })

  it("rejects invalid email", () => {
    const result = UserSchema.safeParse({
      name: "Alice",
      email: "not-an-email",
      age: 30,
    })
    expect(result.success).toBe(false)
  })

  it("rejects negative age", () => {
    const result = UserSchema.safeParse({
      name: "Alice",
      email: "alice@example.com",
      age: -1,
    })
    expect(result.success).toBe(false)
  })
})

Testing Approaches

Schema Correctness Testing

Always Use safeParse() in Tests

// GOOD: test doesn't crash — asserts on result
const result = schema.safeParse(invalidData)
expect(result.success).toBe(false)

// BAD: test crashes instead of failing
expect(() => schema.parse(invalidData)).toThrow()
// If schema changes and starts accepting, this still passes

Test Both Accept and Reject

describe("EmailSchema", () => {
  const valid = ["user@example.com", "a@b.co", "user+tag@domain.org"]
  const invalid = ["", "not-email", "@missing.com", "user@", "user @space.com"]

  it.each(valid)("accepts %s", (email) => {
    expect(z.email().safeParse(email).success).toBe(true)
  })

  it.each(invalid)("rejects %s", (email) => {
    expect(z.email().safeParse(email).success).toBe(false)
  })
})

Test Boundary Values

const AgeSchema = z.number().min(0).max(150)

it("accepts minimum boundary", () => {
  expect(AgeSchema.safeParse(0).success).toBe(true)
})

it("accepts maximum boundary", () => {
  expect(AgeSchema.safeParse(150).success).toBe(true)
})

it("rejects below minimum", () => {
  expect(AgeSchema.safeParse(-1).success).toBe(false)
})

it("rejects above maximum", () => {
  expect(AgeSchema.safeParse(151).success).toBe(false)
})

Error Assertion Patterns

Assert Specific Field Errors

it("shows correct error for invalid email", () => {
  const result = UserSchema.safeParse({ name: "Alice", email: "bad", age: 30 })
  expect(result.success).toBe(false)
  if (!result.success) {
    const flat = z.flattenError(result.error)
    expect(flat.fieldErrors.email).toBeDefined()
    expect(flat.fieldErrors.email![0]).toContain("email")
  }
})

Assert Error Codes

it("produces correct error code", () => {
  const result = z.number().safeParse("not a number")
  expect(result.success).toBe(false)
  if (!result.success) {
    expect(result.error.issues[0].code).toBe("invalid_type")
  }
})

Assert Custom Error Messages

const Schema = z.string({ error: "Name is required" }).min(1, "Name cannot be empty")

it("shows custom error for missing field", () => {
  const result = Schema.safeParse(undefined)
  expect(result.success).toBe(false)
  if (!result.success) {
    expect(result.error.issues[0].message).toBe("Name is required")
  }
})

Mock Data Generation

Using zod-schema-faker

import { install, fake } from "zod-schema-faker"
import { z } from "zod"

install(z) // call once in test setup

const UserSchema = z.object({
  name: z.string().min(1),
  email: z.email(),
  age: z.number().min(0).max(150),
})

it("schema accepts generated data", () => {
  const mockUser = fake(UserSchema)
  expect(UserSchema.safeParse(mockUser).success).toBe(true)
})

Seeding for Deterministic Tests

import { seed, fake } from "zod-schema-faker"

beforeEach(() => {
  seed(12345) // deterministic output
})

it("generates consistent mock data", () => {
  const user = fake(UserSchema)
  expect(user.name).toBeDefined()
})

Snapshot Testing with JSON Schema

it("schema shape has not changed", () => {
  const jsonSchema = z.toJSONSchema(UserSchema)
  expect(jsonSchema).toMatchSnapshot()
})

This catches unintended schema changes in code review. The snapshot shows the JSON Schema representation of your Zod schema.

Integration Testing

API Handler Testing

it("API rejects invalid request body", async () => {
  const response = await request(app)
    .post("/api/users")
    .send({ name: "", email: "invalid" })
    .expect(400)

  expect(response.body.errors).toBeDefined()
  expect(response.body.errors.fieldErrors.email).toBeDefined()
})

Form Validation Testing

it("form shows validation errors", () => {
  const result = FormSchema.safeParse(formData)
  if (!result.success) {
    const errors = z.flattenError(result.error)
    // Pass errors to form library
    expect(errors.fieldErrors).toHaveProperty("email")
  }
})

Property-Based Testing

import fc from "fast-check"
import { fake } from "zod-schema-faker"

it("schema always accepts its own generated data", () => {
  fc.assert(
    fc.property(fc.constant(null), () => {
      const data = fake(UserSchema)
      expect(UserSchema.safeParse(data).success).toBe(true)
    }),
    { numRuns: 100 }
  )
})

Rules

1. Always use safeParse() in tests — parse() crashes the test instead of failing it
2. Test both valid and invalid — don't only test the happy path
3. Test boundary values — min, max, min-1, max+1 for numeric constraints
4. Test optional/nullable combinations — undefined, null, missing key
5. Assert specific error fields — use z.flattenError() to check which field failed
6. Don't test schema internals — test parse results, not .shape or ._def
7. Use z.toJSONSchema() snapshots — catch unintended schema changes
8. Seed random generators — non-deterministic tests are flaky tests
9. Test transforms separately — verify input validation AND output conversion
10. Don't duplicate schema logic in assertions — test behavior, not implementation

Anti-Patterns

See references/anti-patterns.md for BAD/GOOD examples of:

• Testing schema internals instead of behavior
• Not testing error paths
• Using parse() in tests (crashes instead of failing)
• Not testing boundary values
• Hardcoding mock data instead of generating
• Snapshot testing raw ZodError instead of formatted output
• Not testing at boundaries (schema tests pass but handler doesn't validate)
• No snapshot regression testing (field removal goes unnoticed)
• Testing schema shape but not error observability (never assert on flattenError)
• No drift detection workflow (schema changes land without mechanical review)

References

• API Reference — Testing patterns, assertion helpers, mock generation
• Anti-Patterns — Common testing mistakes to avoid