Requirements

@traversable/valibot-test has 2 peer dependencies:

1. valibot (v1)
2. fast-check

Usage

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

Here's an example of importing the library:

import * as v from 'valibot'
import { vxTest } from '@traversable/valibot-test'

// see below for specifc examples

Table of contents

• vxTest.seedToSchema
• vxTest.seedToValidData
• vxTest.seedToInvalidData
• vxTest.SeedGenerator
• vxTest.SeedValidDataGenerator
• vxTest.SeedInvalidDataGenerator

vxTest.seedToSchema

Use vxTest.seedToSchema to convert a seed generated by vxTest.SeedGenerator into a valibot schema that satisfies the configuration options you specified.

Example

import { vxTest } from '@traversable/valibot-test'
import * as fc from 'fast-check'

const builder = vxTest.SeedGenerator()['*']
const [mySeed] = fc.sample(builder.object, 1)

const mySchema = vxTest.seedToSchema(mySeed)
//    ^? const mySchema: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>

vxTest.seedToValidData

Use vxTest.seedToValidData to convert a seed generated by vxTest.SeedGenerator into data that satisfies the schema that the seed represents.

Example

import type * as v from 'valibot'
import { vxTest } from '@traversable/valibot-test'
import * as fc from 'fast-check'

const builder = vxTest.SeedGenerator()['*']
const [mySeed] = fc.sample(builder.object, 1)

const mySchema = vxTest.seedToSchema(mySeed)
//    ^? const mySchema: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>

const validData = vxTest.seedToValidData(mySeed)

mySchema.parse(validData) // will never throw

vxTest.seedToInvalidData

Use vxTest.seedToInvalidData to convert a seed generated by vxTest.SeedGenerator into data that does not satisfy the schema that the seed represents.

Example

import { vxTest } from '@traversable/valibot-test'
import * as fc from 'fast-check'

const builder = vxTest.SeedGenerator()['*']
const [mySeed] = fc.sample(builder.object, 1)

const mySchema = vxTest.seedToSchema(mySeed)
//    ^? const mySchema: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>

const invalidData = vxTest.seedToValidData(mySeed)

mySchema.parse(invalidData) // should always throw

vxTest.SeedGenerator

[!NOTE]

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

Generates a configurable, pseudo-random "seed builder".

• Use vxTest.seedToSchema to convert a seed into a Valibot schema
• Use vxTest.seedToValidData to convert a seed into valid data
• Use vxTest.seedToInvalidData to convert a seed into invalid data

Example

import type * as v from 'valibot'
import * as fc from 'fast-check'
import { vxTest } from '@traversable/valibot-test'

const builder = vxTest.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 `vxTest.seedToSchema`,
 * `vxTest.seedToValidData` or `vxTest.seedToInvalidData`:
 */

const [mySeed] = fc.sample(builder.object, 1)

const mySchema = vxTest.seedToSchema(mySeed)
//    ^? const mySchema: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>

const validData = vxTest.seedToValidData(mySeed)
//    ^? since the `mySeed` was also used to generate `mySchema`,
//       parsing `validData` should always succeed

const invalidData = vxTest.seedToInvalidData(mySeed)
//    ^? since the `mySeed` was also used to generate `mySchema`,
//       parsing `invalidData` should always fail

vxTest.SeedValidDataGenerator

Like vxTest.SeedGenerator, except vxTest.SeedValidDataGenerator comes pre-configured to exclude schemas that make it impossible to reliably generate valid data.

[!NOTE]

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

vxTest.SeedInvalidDataGenerator

Like vxTest.SeedGenerator, except vxTest.SeedValidDataGenerator comes pre-configured to exclude schemas that make it impossible to reliably generate invalid data.

[!NOTE]

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