package windtrap

  1. Overview
  2. Docs

Module Windtrap.TestableSource

Type-safe equality witnesses. See Testable.

Type-safe equality witnesses for assertions and property testing.

A testable bundles pretty-printing, equality, and optionally a random generator for a given type. Built-in testables are provided for primitives and common containers. Compose them with pair, list, option, etc.

Container testables (list, array, string) produce highlighted diffs on assertion failure, pinpointing changed elements.

Sourcetype 'a t

A testable witness for values of type 'a.

Result of a Custom Check

Sourcetype 'a check_result =
  1. | Pass
    (*

    The values are equal.

    *)
  2. | Fail of {
    1. expected_str : string;
    2. actual_str : string;
    3. diff : Windtrap__.Failure.diff_output option;
    }
    (*

    The values differ, with optional structured diff.

    *)

Construction

Sourceval make : pp:'a Pp.t -> ?equal:('a -> 'a -> bool) -> ?gen:'a Windtrap_prop.Gen.t -> ?check:('a -> 'a -> 'a check_result) -> unit -> 'a t

make ~pp ~equal () creates a testable.

  • parameter equal

    Equality function for assertions. Defaults to structural equality (=). For property-only testables (used with Windtrap.prop but not Windtrap.equal), this can be omitted.

  • parameter gen

    Random generator for property-based testing with Windtrap.prop.

  • parameter check

    Custom comparison that produces structured diff output on failure. When provided, assertions use check instead of equal.

Accessors

Sourceval pp : 'a t -> 'a Pp.t

pp t returns the pretty-printer.

Sourceval equal : 'a t -> 'a -> 'a -> bool

equal t returns the equality function.

Sourceval gen : 'a t -> 'a Windtrap_prop.Gen.t option

gen t returns the random generator, if any.

Sourceval check : 'a t -> ('a -> 'a -> 'a check_result) option

check t returns the custom check function, if any.

Sourceval to_string : 'a t -> 'a -> string

to_string t v pretty-prints v to a string using t's printer.

Sourceval with_gen : 'a Windtrap_prop.Gen.t -> 'a t -> 'a t

with_gen gen t returns a copy of t that uses gen as its random generator. Useful when the default generator produces values outside the domain of the property under test.

  (* int with bounded range to avoid overflow in arithmetic *)
  let safe_int = Testable.(with_gen Gen.small_int int)

Primitive Testables

Sourceval unit : unit t
Sourceval bool : bool t
Sourceval int : int t
Sourceval small_int : int t

Like int but uses Windtrap_prop.Gen.small_int, which generates integers in [-10_000, 10_000]. Useful for properties involving arithmetic that would overflow with full-range integers.

Sourceval nat : int t

Like int but generates non-negative integers in [0, 10_000], biased towards small values. Useful for indices, sizes, and counts.

Sourceval int32 : int32 t
Sourceval int64 : int64 t
Sourceval nativeint : nativeint t
Sourceval float : float -> float t

float eps creates a testable with absolute tolerance eps. Two floats a and b are equal when |a - b| <= eps. NaN equals NaN for testing purposes.

Sourceval float_rel : rel:float -> abs:float -> float t

float_rel ~rel ~abs creates a testable with both relative and absolute tolerance. Two floats a and b are equal when their difference is within abs or within rel * max(|a|, |b|). NaN equals NaN.

Sourceval char : char t
Sourceval string : string t
Sourceval bytes : bytes t

Container Testables

Sourceval option : 'a t -> 'a option t
Sourceval result : 'a t -> 'b t -> ('a, 'b) result t
Sourceval either : 'a t -> 'b t -> ('a, 'b) Either.t t

either left right creates a testable for Either.t values.

Sourceval list : 'a t -> 'a list t

list t creates a testable for lists. Produces highlighted diffs on failure, pinpointing changed elements using Levenshtein edit distance.

Sourceval array : 'a t -> 'a array t

array t creates a testable for arrays. Produces highlighted diffs on failure, like list.

Sourceval pair : 'a t -> 'b t -> ('a * 'b) t
Sourceval triple : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t
Sourceval quad : 'a t -> 'b t -> 'c t -> 'd t -> ('a * 'b * 'c * 'd) t

Combinators

Sourceval pass : 'a t

pass always considers values equal. Useful for ignoring parts of a structure.

Sourceval slist : 'a t -> ('a -> 'a -> int) -> 'a list t

slist t cmp compares lists as sets, ignoring order. Both lists are sorted with cmp before comparison.

Sourceval of_equal : ('a -> 'a -> bool) -> 'a t

of_equal eq creates a testable from an equality function. Uses "<opaque>" as the printed representation.

Sourceval contramap : ('a -> 'b) -> 'b t -> 'a t

contramap f t transforms values with f before comparing with t.

The resulting testable has no generator.

  type user = { id : int; name : string }

  let user_id = Testable.contramap (fun u -> u.id) Testable.int
Sourceval seq : 'a t -> 'a Seq.t t

seq t creates a testable for sequences. Consumes both sequences during comparison.

Sourceval lazy_t : 'a t -> 'a Lazy.t t

lazy_t t creates a testable for lazy values. Forces both values before comparing.