TestSchema.ts

TestSchema.ts overview

Provides helpers for testing Schema behavior.

These utilities assert how schemas construct values, decode input, encode output, generate arbitrary values, and round-trip between encoded and decoded forms. The Asserts class groups the common checks for one schema, while Decoding and Encoding can be used directly when a test only needs one direction.

Since v4.0.0

---

Exports Grouped by Category

• testing
  • Asserts (class)
    • make (method)
    • verifyLosslessTransformation (method)
    • decoding (method)
    • encoding (method)
    • arbitrary (method)
    • schema (property)
  • Decoding (class)
    • succeed (method)
    • fail (method)
    • provide (method)
    • schema (property)
    • decodeUnknownEffect (property)
    • options (property)
  • Encoding (class)
    • succeed (method)
    • fail (method)
    • provide (method)
    • schema (property)
    • encodeUnknownEffect (property)
    • options (property)

---

testing

Asserts (class)

Provides schema test assertions for decoding, encoding, make, arbitrary generation, and round-trip verification.

When to use

Use when writing schema unit tests for decoding, encoding, construction, property-based round-trip, or generation behavior.

Example (Decoding and encoding a struct)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const schema = Schema.Struct({ name: Schema.String })
const asserts = new TestSchema.Asserts(schema)

// decoding
await asserts.decoding().succeed({ name: "Alice" })

// encoding
await asserts.encoding().succeed({ name: "Alice" })

See

• Decoding
• Encoding

Signature

declare class Asserts<S> {
  constructor(schema: S)
}

Source

Since v4.0.0

make (method)

Returns an object with succeed and fail helpers for testing the schema’s make operation.

When to use

Use to assert how Schema.make accepts, transforms, or rejects construction input for this schema.

Details

succeed(input) asserts make returns the input unchanged. succeed(input, expected) asserts make returns expected. fail(input, message) asserts make fails with message.

Example (Testing make)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const schema = Schema.String
const asserts = new TestSchema.Asserts(schema)
await asserts.make().succeed("hello")

See

• decoding for assertions against decoded input
• encoding for assertions against encoded output

Signature

declare const make: (options?: Schema.MakeOptions) => {
  succeed: { (input: S["Type"]): Promise<void>; (input: S["~type.make.in"], expected: S["Type"]): Promise<void> }
  fail(input: unknown, message: string): Promise<void>
}

Source

verifyLosslessTransformation (method)

Runs a property-based test that encodes arbitrary values and then decodes them, asserting the decoded value equals the original.

When to use

Use to verify that generated schema values survive an encode-then-decode round trip.

Details

FastCheck generates arbitrary values matching the schema’s Type. The assertion fails if any generated value does not round-trip. Pass options.params to control FastCheck parameters such as numRuns.

Example (Verifying round trips)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const asserts = new TestSchema.Asserts(Schema.NumberFromString)
await asserts.verifyLosslessTransformation()

See

• arbitrary for checking that generated values satisfy the schema

Signature

declare const verifyLosslessTransformation: <S extends Schema.Codec<unknown, unknown>>(
  this: Asserts<S>,
  options?: { readonly params?: FastCheck.Parameters<[S["Type"]]> }
) => Promise<void>

Source

decoding (method)

Returns a Decoding instance for this schema with helpers for decoding assertions.

When to use

Use to test how unknown input is decoded into the schema’s type.

Details

Pass parseOptions to control error reporting, for example { errors: "all" }.

Example (Decoding assertions)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const asserts = new TestSchema.Asserts(Schema.NumberFromString)
const decoding = asserts.decoding()
await decoding.succeed("42", 42)
await decoding.fail(null, "Expected string, got null")

See

• Decoding
• encoding for assertions in the opposite direction

Signature

declare const decoding: (options?: { readonly parseOptions?: SchemaAST.ParseOptions | undefined }) => Decoding<S>

Source

encoding (method)

Returns an Encoding instance for this schema with helpers for encoding assertions.

When to use

Use to test how schema values are encoded into their external form.

Details

Pass parseOptions to control error reporting, for example { errors: "all" }.

Example (Encoding assertions)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const asserts = new TestSchema.Asserts(Schema.NumberFromString)
const encoding = asserts.encoding()
await encoding.succeed(42, "42")

See

• Encoding
• decoding for assertions in the opposite direction

Signature

declare const encoding: (options?: { readonly parseOptions?: SchemaAST.ParseOptions | undefined }) => Encoding<S>

Source

arbitrary (method)

Returns an object with property-based testing helpers for the schema’s arbitrary generator.

When to use

Use to verify that arbitrary values generated for this schema satisfy the schema’s predicate.

Details

verifyGeneration() generates arbitrary values and asserts each value satisfies the schema’s is predicate. It defaults to 20 runs. Pass options.params to override FastCheck parameters.

Example (Verifying arbitrary generation)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const asserts = new TestSchema.Asserts(Schema.String)
asserts.arbitrary().verifyGeneration()

See

• verifyLosslessTransformation for property-based round-trip checks

Signature

declare const arbitrary: <S extends Schema.Codec<unknown, unknown, never, unknown>>(
  this: Asserts<S>
) => { verifyGeneration(options?: { readonly params?: FastCheck.Parameters<[S["Type"]]> | undefined }): void }

Source

schema (property)

Signature

readonly schema: S

Source

Decoding (class)

Provides decoding test assertions through succeed and fail methods that run the schema’s decoder and compare the result.

When to use

Use when you want to assert that specific inputs decode to expected values, invalid inputs produce specific error messages, or schemas receive required decoding services.

Details

All assertions are async and use assert.deepStrictEqual internally. succeed(input) asserts the decoded output equals input; succeed(input, expected) asserts it equals expected; fail(input, message) asserts decoding fails and the stringified issue equals message. provide(key, impl) returns a new Decoding with the service injected into the decoding context.

Example (Decoding with service provision)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const asserts = new TestSchema.Asserts(Schema.String)
const decoding = asserts.decoding()
await decoding.succeed("hello")

See

• Asserts
• Encoding

Signature

declare class Decoding<S> {
  constructor(
    schema: S,
    options?: {
      readonly parseOptions?: SchemaAST.ParseOptions | undefined
    }
  )
}

Source

Since v4.0.0

succeed (method)

Asserts that decoding input succeeds. With one argument, asserts the output equals the input. With two arguments, asserts the output equals expected.

When to use

Use to verify successful decoding for one input case.

Example (Testing identity and transformed decoding)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const decoding = new TestSchema.Asserts(Schema.NumberFromString).decoding()
await decoding.succeed("1", 1) // transformed

See

• fail for asserting decoding failures

Signature

declare const succeed: {
  <S extends Schema.ConstraintDecoder<unknown, never>>(this: Decoding<S>, input: unknown): Promise<void>
  <S extends Schema.ConstraintDecoder<unknown, never>>(
    this: Decoding<S>,
    input: unknown,
    expected: S["Type"]
  ): Promise<void>
}

Source

fail (method)

Asserts that decoding input fails and the stringified issue equals message.

When to use

Use to verify that invalid decoding input produces the expected issue text.

Example (Asserting a decoding failure)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const decoding = new TestSchema.Asserts(Schema.String).decoding()
await decoding.fail(42, "Expected string, got 42")

See

• succeed for asserting successful decoding

Signature

declare const fail: <S extends Schema.ConstraintDecoder<unknown, never>>(
  this: Decoding<S>,
  input: unknown,
  message: string
) => Promise<void>

Source

provide (method)

Returns a new Decoding instance with the given service injected into the decoding effect context.

When to use

Use when the schema’s decoder requires a service dependency.

See

• Encoding.provide

Signature

declare const provide: <Id, Service>(
  service: Context.Key<Id, Service>,
  implementation: Service
) => Decoding<Schema.middlewareDecoding<S, Exclude<S["DecodingServices"], Id>>>

Source

schema (property)

Signature

readonly schema: S

Source

decodeUnknownEffect (property)

Signature

readonly decodeUnknownEffect: (input: unknown, options?: SchemaAST.ParseOptions) => Effect.Effect<S["Type"], SchemaIssue.Issue, S["DecodingServices"]>

Source

options (property)

Signature

readonly options: { readonly parseOptions?: SchemaAST.ParseOptions | undefined; } | undefined

Source

Encoding (class)

Provides encoding test assertions through succeed and fail methods that run the schema’s encoder and compare the result.

When to use

Use when you want to assert that specific values encode to expected outputs, invalid inputs produce specific error messages, or schemas receive required encoding services.

Details

All assertions are async and use assert.deepStrictEqual internally. succeed(input) asserts the encoded output equals input; succeed(input, expected) asserts it equals expected; fail(input, message) asserts encoding fails and the stringified issue equals message. provide(key, impl) returns a new Encoding with the service injected into the encoding context.

Example (Encoding assertions)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const encoding = new TestSchema.Asserts(Schema.NumberFromString).encoding()
await encoding.succeed(42, "42")

See

• Asserts
• Decoding

Signature

declare class Encoding<S> {
  constructor(
    schema: S,
    options?: {
      readonly parseOptions?: SchemaAST.ParseOptions | undefined
    }
  )
}

Source

Since v4.0.0

succeed (method)

Asserts that encoding input succeeds. With one argument, asserts the output equals the input. With two arguments, asserts the output equals expected.

When to use

Use to verify successful encoding for one input case.

Example (Testing identity and transformed encoding)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const encoding = new TestSchema.Asserts(Schema.NumberFromString).encoding()
await encoding.succeed(1, "1") // transformed

See

• fail for asserting encoding failures

Signature

declare const succeed: {
  <S extends Schema.ConstraintEncoder<unknown, never>>(this: Encoding<S>, input: unknown): Promise<void>
  <S extends Schema.ConstraintEncoder<unknown, never>>(
    this: Encoding<S>,
    input: unknown,
    expected: S["Encoded"]
  ): Promise<void>
}

Source

fail (method)

Asserts that encoding input fails and the stringified issue equals message.

When to use

Use to verify that invalid encoding input produces the expected issue text.

Example (Asserting an encoding failure)

import { Schema } from "effect"
import { TestSchema } from "effect/testing"

const encoding = new TestSchema.Asserts(Schema.NumberFromString).encoding()
await encoding.fail("not-a-number", 'Expected number, got "not-a-number"')

See

• succeed for asserting successful encoding

Signature

declare const fail: <S extends Schema.ConstraintEncoder<unknown, never>>(
  this: Encoding<S>,
  input: unknown,
  message: string
) => Promise<void>

Source

provide (method)

Returns a new Encoding instance with the given service injected into the encoding effect context.

When to use

Use when the schema’s encoder requires a service dependency.

See

• Decoding.provide

Signature

declare const provide: <Id, Service>(
  service: Context.Key<Id, Service>,
  implementation: Service
) => Encoding<Schema.middlewareEncoding<S, Exclude<S["EncodingServices"], Id>>>

Source

schema (property)

Signature

readonly schema: S

Source

encodeUnknownEffect (property)

Signature

readonly encodeUnknownEffect: (input: unknown, options?: SchemaAST.ParseOptions) => Effect.Effect<S["Type"], SchemaIssue.Issue, S["EncodingServices"]>

Source

options (property)

Signature

readonly options: { readonly parseOptions?: SchemaAST.ParseOptions | undefined; } | undefined

Source