TestSchema unstable

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.

Methods with an Effect suffix return lazy assertions that use the calling fiber's services. The Promise-returning methods can be used with any test runner.

3 exports Since v4.0.0 Source

Testing

Asserts

unstable

Since v4.0.0

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.

See

Signature

declare class Asserts<S extends Schema.Constraint> {
  constructor<S extends Constraint>(schema: S);
  readonly schema: S;
  static ast: {
    readonly elements: {
      readonly equals: (a: Elements, b: Elements) => void;
    };
    readonly fields: {
      readonly equals: (a: Fields, b: Fields) => void;
    };
  };
  arbitrary<S extends ConstraintCodec<unknown, unknown, never, never>>(this: Asserts<S>): {
    verifyGeneration(options?: CheckOptions): void;
  };
  decoding(options?: {
    readonly parseOptions?: ParseOptions;
  }): Decoding<S>;
  encoding(options?: {
    readonly parseOptions?: ParseOptions;
  }): Encoding<S>;
  make(options?: MakeOptions): {
    failEffect: (input: unknown, message: string) => Effect<void>;
    succeed: {
      (input: S["Type"]): Promise<void>;
      (input: S["~type.make.in"], expected: S["Type"]): Promise<void>;
    };
    succeedEffect: {
      (input: S["Type"]): Effect<void>;
      (input: S["~type.make.in"], expected: S["Type"]): Effect<void>;
    };
    fail(input: unknown, message: string): Promise<void>;
  };
  verifyRoundTrip<S extends ConstraintCodec<unknown, unknown, never, never>>(this: Asserts<S>, options?: CheckOptions): Promise<void>;
  verifyRoundTripEffect(options?: CheckOptions): Effect<void, never, S["DecodingServices"] | S["EncodingServices"]>;
}

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" }) // => undefined

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

Decoding

unstable

Since v4.0.0

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

succeed and fail return Promises. succeedEffect and failEffect return lazy effects that preserve required decoding services. All assertions use assert.deepStrictEqual internally. With one argument, success assertions compare the output to the input; with two, they compare it to expected. Failure assertions compare the formatted schema issue to message. provide(key, impl) returns a new Decoding with the service injected.

See

Signature

declare class Decoding<S extends Schema.Constraint> {
  constructor<S extends Constraint>(schema: S, options?: {
    readonly parseOptions?: ParseOptions;
  });
  readonly decodeUnknownEffect: (input: unknown, options?: ParseOptions) => Effect<S["Type"], Issue, S["DecodingServices"]>;
  readonly options?: {
    readonly parseOptions?: ParseOptions;
  };
  readonly schema: S;
  fail<S extends ConstraintDecoder<unknown, never>>(this: Decoding<S>, input: unknown, message: string): Promise<void>;
  failEffect(input: unknown, message: string): Effect<void, never, S["DecodingServices"]>;
  provide<Id, Service>(service: Key<Id, Service>, implementation: Service): Decoding<middlewareDecoding<S, Exclude<S["DecodingServices"], Id>>>;
  succeed<S extends ConstraintDecoder<unknown, never>>(this: Decoding<S>, input: unknown): Promise<void>;
  succeed<S extends ConstraintDecoder<unknown, never>>(this: Decoding<S>, input: unknown, expected: S["Type"]): Promise<void>;
  succeedEffect(input: unknown): Effect<void, never, S["DecodingServices"]>;
  succeedEffect(input: unknown, expected: S["Type"]): Effect<void, never, S["DecodingServices"]>;
}

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") // => undefined

Encoding

unstable

Since v4.0.0

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

succeed and fail return Promises. succeedEffect and failEffect return lazy effects that preserve required encoding services. All assertions use assert.deepStrictEqual internally. With one argument, success assertions compare the output to the input; with two, they compare it to expected. Failure assertions compare the formatted schema issue to message. provide(key, impl) returns a new Encoding with the service injected.

See

Signature

declare class Encoding<S extends Schema.Constraint> {
  constructor<S extends Constraint>(schema: S, options?: {
    readonly parseOptions?: ParseOptions;
  });
  readonly encodeUnknownEffect: (input: unknown, options?: ParseOptions) => Effect<S["Encoded"], Issue, S["EncodingServices"]>;
  readonly options?: {
    readonly parseOptions?: ParseOptions;
  };
  readonly schema: S;
  fail<S extends ConstraintEncoder<unknown, never>>(this: Encoding<S>, input: unknown, message: string): Promise<void>;
  failEffect(input: unknown, message: string): Effect<void, never, S["EncodingServices"]>;
  provide<Id, Service>(service: Key<Id, Service>, implementation: Service): Encoding<middlewareEncoding<S, Exclude<S["EncodingServices"], Id>>>;
  succeed<S extends ConstraintEncoder<unknown, never>>(this: Encoding<S>, input: unknown): Promise<void>;
  succeed<S extends ConstraintEncoder<unknown, never>>(this: Encoding<S>, input: unknown, expected: S["Encoded"]): Promise<void>;
  succeedEffect(input: unknown): Effect<void, never, S["EncodingServices"]>;
  succeedEffect(input: unknown, expected: S["Encoded"]): Effect<void, never, S["EncodingServices"]>;
}

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") // => undefined