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.
Testing
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;
}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>;
}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>;
}
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
DecodingEncoding