ᯓ𝘁𝗿𝗮𝘃𝗲𝗿𝘀𝗮𝗯𝗹𝗲/𝘁𝘆𝗽𝗲𝗯𝗼𝘅-𝘁𝗲𝘀𝘁

Testing utility that generates arbitrary, pseudorandom TypeBox schemas, powered by fast-check

       

Requirements

@traversable/typebox-test has 2 peer dependencies:

1. @sinclair/typebox (v0.34)
2. fast-check

Usage

$ pnpm add -D @traversable/typebox-test @sinclair/typebox fast-check
Copy

Here's an example of importing the library:

import * as T from '@sinclair/typebox'
import { boxTest } from '@traversable/typebox-test'

// see below for specifc examples
Copy

Table of contents

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

boxTest.seedToSchema

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

Example

import * as T from '@sinclair/typebox'
import { boxTest } from '@traversable/typebox-test'
import * as fc from 'fast-check'

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

const mySchema = boxTest.seedToSchema(mySeed)
//    ^? const mySchema: T.TSchema
Copy

boxTest.seedToValidData

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

Example

import * as T from '@sinclair/typebox'
import * as Value from '@sinclair/typebox/value'
import { boxTest } from '@traversable/typebox-test'
import * as fc from 'fast-check'

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

const mySchema = boxTest.seedToSchema(mySeed)
//    ^? const mySchema: T.TSchema

const validData = boxTest.seedToValidData(mySeed)

Value.Check(mySchema, validData) // always `true`
Copy

boxTest.seedToInvalidData

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

Example

import * as T from '@sinclair/typebox'
import * as Value from '@sinclair/typebox/value'
import { boxTest } from '@traversable/typebox-test'
import * as fc from 'fast-check'

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

const mySchema = boxTest.seedToSchema(mySeed)
//    ^? const mySchema: T.TSchema

const invalidData = boxTest.seedToValidData(mySeed)

Value.Check(mySchema, invalidData) // always `false`
Copy

boxTest.SeedGenerator

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

• Use boxTest.seedToSchema to convert a seed into a TypeBox schema
• Use boxTest.seedToValidData to convert a seed into valid data
• Use boxTest.seedToInvalidData to convert a seed into invalid data

Example

import { type } from '@sinclair/typebox'
import * as fc from 'fast-check'
import { boxTest } from '@traversable/typebox-test'

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

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

const mySchema = boxTest.seedToSchema(mySeed)
//    ^? const mySchema: type.Any

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

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

boxTest.SeedValidDataGenerator

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

boxTest.SeedInvalidDataGenerator

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