TestSchema

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.

3 exports Added in v4.0.0 Source

Testing

Asserts

Added in v4.0.0 Source

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?: {
      readonly params?: any;
    }): void;
  };
  decoding(options?: {
    readonly parseOptions?: ParseOptions;
  }): Decoding<S>;
  encoding(options?: {
    readonly parseOptions?: ParseOptions;
  }): Encoding<S>;
  make(options?: MakeOptions): {
    succeed: {
      (input: S["Type"]): Promise<void>;
      (input: S["~type.make.in"], expected: S["Type"]): Promise<void>;
    };
    fail(input: unknown, message: string): Promise<void>;
  };
  verifyLosslessTransformation<S extends ConstraintCodec<unknown, unknown, never, never>>(this: Asserts<S>, options?: {
    readonly params?: any;
  }): any;
}

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

Added in v4.0.0 Source

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.

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>;
  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>;
}

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

Added in v4.0.0 Source

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.

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>;
  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>;
}

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