zod-testing

# 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

```typescript
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

| Approach | Purpose | Use When |
|----------|---------|----------|
| `safeParse()` result checking | Sch...

# Zod Testing

Created by **[Anivar Aravind](https://anivar.net)**

An AI agent skill for testing Zod schemas with Jest and Vitest.

## The Problem

AI agents often write schema tests that only check the happy path, use `parse()` instead of `safeParse()` (crashing instead of failing), test schema internals (`.shape`, `._def`) instead of behavior, or hardcode mock data instead of generating it from the schema. The result: tests that miss regressions and break on harmless refactors.

## This Solution

A focused testing skill covering schema correctness testing, error assertion patterns, mock data generation, snapshot testing with `z.toJSONSchema()`, property-based testing, structural testing, and drift detection — with 14 anti-patterns showing exactly what goes wrong and how to fix it.

## Install

```bash
npx skills add anivar/zod-testing -g
```

Or with full URL:

```bash
npx skills add https://github.com/anivar/zod-testing
```

## Baseline

- zod ^4.0.0
- Jest or Vitest
- TypeScript ^5.5

## What's Inside

### Testing Approaches

| Approach | Type | Use When |
|----------|------|----------|
| `safeParse()` result checking | Correctness | Default — always use safeParse in tests |
| `z.flattenError()` assertions | Error messages | Verifying specific field errors |
| `z.toJSONSchema()` snapshots | Schema shape | Detecting unintended schema changes |
| Mock data generation | Fixtures | Need valid/randomized test data |
| Property-based testing | Fuzz testing | Schemas must handle arbitrary valid inputs |
| Structural testing | Architecture | Verify schemas are only imported at boundaries |
| Drift detection | Regression | Catch unintended schema changes via JSON Schema snapshots |

### Anti-Patterns

14 common testing mistakes with BAD/GOOD code examples:
- Testing schema internals instead of behavior
- Not testing error paths (only happy path)
- Using `parse()` in tests (crashes instead of failing)
- Not testing boundary values (min/max edges)
- Hardcoding mock data i...