$ pnpm add -D @traversable/zod-test zod fast-check

import { z } from 'zod'
import { zxTest } from '@traversable/zod-test'
// see below for specifc examples

Note

zxTest.fuzz is the only schema-to-generator function that has itself been fuzz tested to ensure that no matter what schema you give it, the data-generator it returns will always produce valid data.

This excludes schemas that make it impossible to generate valid data, for example:

• z.never
• z.nonoptional(z.undefined())
• z.enum([])
• z.union([])
• z.intersection(z.number(), z.string())

import * as vi from 'vitest'
import * as fc from 'fast-check'
import { fuzz } from '@traversable/zod-test'
const Schema = z.record(
  z.string(),
  z.union(
    z.number(),
    z.string(),
  )
)
const generator = fuzz(
  Schema,
  { record: { minKeys: 1 }, number: { noDefaultInfinity: true } },
  { string: () => fc.stringMatching(/[\S\s]+[\S]+/) },
)
vi.test('fuzz test example', () => {
  fc.assert(
    fc.property(generator, (data) => {
      vi.assert.doesNotThrow(() => Schema.parse(data))
    }),
    { numRuns: 1_000 }
  )
})

import { zxTest } from '@traversable/zod-test'
import * as fc from 'fast-check'
const builder = zxTest.SeedGenerator()['*']
const [mySeed] = fc.sample(builder.object, 1)
const mySchema = zxTest.seedToSchema(mySeed)
//    ^? const mySchema: z.ZodType

import { zxTest } from '@traversable/zod-test'
import * as fc from 'fast-check'
const builder = zxTest.SeedGenerator()['*']
const [mySeed] = fc.sample(builder.object, 1)
const mySchema = zxTest.seedToSchema(mySeed)
//    ^? const mySchema: z.ZodType
const validData = zxTest.seedToValidData(mySeed)
mySchema.parse(validData) // will never throw

import { zxTest } from '@traversable/zod-test'
import * as fc from 'fast-check'
const builder = zxTest.SeedGenerator()['*']
const [mySeed] = fc.sample(builder.object, 1)
const mySchema = zxTest.seedToSchema(mySeed)
//    ^? const mySchema: z.ZodType
const invalidData = zxTest.seedToValidData(mySeed)
mySchema.parse(invalidData) // should always throw

import { zxTest } from '@traversable/zod-test'
import * as fc from 'fast-check'
const builder = zxTest.SeedGenerator()['*']
const [mySeed] = fc.sample(builder.object, 1)
const mySchema = zxTest.seedToSchema(mySeed)
//    ^? const mySchema: z.ZodType
const validDataGenerator = zxTest.seedToValidDataGenerator(mySeed)
const [validData] = fc.sample(validDataGenerator, 1)
mySchema.parse(validData) // will never throw

import type * as z from 'zod'
import * as fc from 'fast-check'
import { zxTest } from '@traversable/zod-test'
const builder = zxTest.SeedGenerator()['*']
const [mySeed] = fc.sample(builder.object, 1)
const mySchema = zxTest.seedToSchema(mySeed)
//    ^? const mySchema: z.ZodType
const invalidDataGenerator = zxTest.seedToInvalidDataGenerator(mySeed)
const [invalidData] = fc.sample(invalidDataGenerator, 1)
mySchema.parse(invalidData) // will always throw

Note

zxTest.SeedGenerator is fairly low-level. All of the other exports of this library have been implemented in terms of zxTest.SeedGenerator.

import { zxTest } from '@traversable/zod-test'
import * as fc from 'fast-check'
const builder = zxTest.SeedGenerator({
  include: ["boolean", "string", "object"],
  // 𐙘 use `include` to only include certain schema types
  exclude: ["boolean", "any"],
  // 𐙘 use `exclude` to exclude certain schema types altogether (overrides `include`)
  object: { maxKeys: 5 },
  // 𐙘 specific arbitraries are configurable by name
})
// included schemas are present as properties on your generator...
builder.string
builder.object
// ...excluded schemas are not present...
builder.boolean // 🚫 TypeError
// ...a special wildcard `"*"` property (pronounced "surprise me") is always present:
builder["*"]
/**
 * `fast-check` will generate a seed, which is a data structure containing
 * integers that represent a kind of AST.
 *
 * To use a seed, you need to pass it to an interpreter like `zxTest.seedToSchema`,
 * `zxTest.seedToValidData` or `zxTest.seedToInvalidData`:
 */
const [mySeed] = fc.sample(builder.object, 1)
const mySchema = zxTest.seedToSchema(mySeed)
//    ^? const mySchema: z.ZodType
const validData = zxTest.seedToValidData(mySeed)
//    ^? since the `mySeed` was also used to generate `mySchema`,
//       parsing `validData` should always succeed
const invalidData = zxTest.seedToInvalidData(mySeed)
//    ^? since the `mySeed` was also used to generate `mySchema`,
//       parsing `invalidData` should always fail

Note

zxTest.SeedValidDataGenerator does not accept any options. If you need more fine-grained control of the schemas being generated, use zxTest.SeedGenerator.

Note

zxTest.SeedInvalidDataGenerator does not accept any options. If you need more fine-grained control of the schemas being generated, use zxTest.SeedGenerator.