package bonsai

  1. Overview
  2. Docs
package bonsai
Legend:
Library
Module
Module type
Parameter
Class
Class type
module Incr = Ui_incr
include module type of struct include Expect_test_helpers_core end
include module type of struct include Expect_test_helpers_base end
module type With_compare = Expect_test_helpers_core.With_compare
module type With_equal = Expect_test_helpers_core.With_equal
module type With_round_trip = Expect_test_helpers_core.With_round_trip
module type With_sexpable = Expect_test_helpers_core.With_sexpable
module type With_stringable = Expect_test_helpers_core.With_stringable
val hide_positions_in_string : Base.string -> Base.string

hide_positions_in_string does line-based regexp matching to replace line numbers and column numbers that appear in source-code positions with constant text LINE and COL. This can be useful in making displayed test output less fragile.

val hide_temp_files_in_string : Base.string -> Base.string

hide_temp_files_in_string replaces .tmp.______, where each _ represents some alphanumeric character, with ".tmp.RANDOM". This can make output deterministic when describing temporary files generated by, e.g., Core_unix.mkstemp.

val sexp_to_string : ?hide_positions:Base.bool -> Base.Sexp.t -> Base.string

Renders an s-expression as a string. With ~hide_positions:true, patterns in the string that match OCaml-style file positions are modified to hide the line number, column number, and character positions, to make output less fragile.

val replace : Base.string -> pattern:Base.string -> with_:Base.string -> Base.string

Substitutes with_ for every occurrence of pattern in a string.

val replace_s : Base.Sexp.t -> pattern:Base.string -> with_:Base.string -> Base.Sexp.t

Like replace, for every atom in a sexp.

val smash_sexp : Base.Sexp.t -> f:(Base.Sexp.t -> Base.Sexp.t) -> Base.Sexp.t

Applies f at every node in the given sexp, top-down, recurring on the contents of the output. The word "smash" is used as in the sexp command-line tool's query language. See: https://github.com/janestreet/sexp

val remove_backtraces : Base.Sexp.t -> Base.Sexp.t

Removes OCaml backtraces from sexps.

val print_s : ?hide_positions:Base.bool -> Base.Sexp.t -> Base.unit

For printing an s-expression to stdout. hide_positions works as in sexp_to_string.

val print_string : ?hide_positions:Base.bool -> Base.string -> Base.unit
val print_endline : ?hide_positions:Base.bool -> Base.string -> Base.unit
val expect_test_output : Base.Source_code_position.t -> Base.string

Behaves like [%expect.output].

val am_running_expect_test : Base.unit -> Base.bool

Returns true if running inside the body of let%expect_test, or false otherwise. Use to test whether expect_test_output will raise, for example. Unlike Core.am_running_test, this is not configured by an environment variable, and is not inherited by child processes.

val assert_am_running_expect_test : Base.Source_code_position.t -> Base.unit

If am_running_expect_test () = false, raises with an explanatory error message. Do not use require am_running_expect_test, as outside of an expect test that may not accomplish anything.

val print_cr : ?cr:CR.t -> ?hide_positions:Base.bool -> Base.Source_code_position.t -> Base.Sexp.t -> Base.unit

print_cr here message prints a CR require-failed, which will appear in expect-test output. The CR will appear in the feature owner's fe todo, thus preventing release of the feature. print_cr is an expect-test-friendly version of assert false. It works with the normal expect-test workflow because it does not raise, and it prevents mistakenly releasing features that violate a required property. There is no need to 'X' a CR require-failed; simply fix the property that triggered the print_cr and re-run the test to restore the empty output.

val require : ?cr:CR.t -> ?hide_positions:Base.bool -> ?if_false_then_print_s:Base.Sexp.t Base.Lazy.t -> Base.Source_code_position.t -> Base.bool -> Base.unit

require here bool is a no-op if bool = true, but if not, prints a CR require-failed similarly to print_cr, with a message determined by the if_false_then_print_s argument, if any.

if_false_then_print_s is useful for including information that may help debug the problem, but that would otherwise be too voluminous. if_false_then_print_s is lazy to avoid construction of the sexp except when needed.

val require_equal : ?cr:CR.t -> ?hide_positions:Base.bool -> ?if_false_then_print_s:Base.Sexp.t Base.Lazy.t -> ?message:Base.string -> Base.Source_code_position.t -> (module With_equal with type t = 'a) -> 'a -> 'a -> Base.unit

require_equal compares its two arguments using the equality predicate of the provided module. If the comparison fails, prints a message that renders the arguments as sexps.

val require_compare_equal : ?cr:CR.t -> ?hide_positions:Base.bool -> ?message:Base.string -> Base.Source_code_position.t -> (module With_compare with type t = 'a) -> 'a -> 'a -> Base.unit

Like require_equal, but derives an equality predicate from a comparison function.

val require_not_equal : ?cr:CR.t -> ?hide_positions:Base.bool -> ?if_false_then_print_s:Base.Sexp.t Base.Lazy.t -> ?message:Base.string -> Base.Source_code_position.t -> (module With_equal with type t = 'a) -> 'a -> 'a -> Base.unit

Like require_equal but instead requires that the arguments are *not* equal.

val require_compare_not_equal : ?cr:CR.t -> ?hide_positions:Base.bool -> ?message:Base.string -> Base.Source_code_position.t -> (module With_compare with type t = 'a) -> 'a -> 'a -> Base.unit

Like require_not_equal, but derives an equality predicate from a comparison function.

val require_sets_are_equal : ?cr:CR.t -> ?hide_positions:Base.bool -> ?names:(Base.string * Base.string) -> Base.Source_code_position.t -> ('elt, 'cmp) Base.Set.t -> ('elt, 'cmp) Base.Set.t -> Base.unit

Like require_equal, but when equality fails produces a message including sexps of both Set.diff first second and Set.diff second first to aid in debugging.

val show_raise : ?hide_positions:Base.bool -> ?show_backtrace:Base.bool -> (Base.unit -> _) -> Base.unit

show_raise calls f () and prints the exception that it raises, or, if it doesn't raise, prints did not raise. show_raise ignores the result of f so that one doesn't have to put an ignore inside the body of an f that is expected to raise. ~hide_positions:true operates as in print_s, to make output less fragile. Using ~show_backtrace:true will result in a CR in the expectation, but it's still available here as it is still valuable when initially writing tests and debugging.

val require_does_not_raise : ?cr:CR.t -> ?hide_positions:Base.bool -> ?show_backtrace:Base.bool -> Base.Source_code_position.t -> (Base.unit -> Base.unit) -> Base.unit

require_does_not_raise is like show_raise, but does not print anything if the function does not raise, and prints a CR along with the exception if it does raise. Unlike for show_raise, the supplied function is required to return unit to avoid mistakes like incomplete partial application that silently would not raise, but for the wrong reason.

val require_does_raise : ?cr:CR.t -> ?hide_positions:Base.bool -> ?show_backtrace:Base.bool -> Base.Source_code_position.t -> (Base.unit -> _) -> Base.unit

require_does_raise is like show_raise, but additionally prints a CR if the function does not raise.

val require_some : ?cr:CR.t -> ?hide_positions:Base.bool -> ?print_some:('some -> Base.Sexp.t) -> Base.Source_code_position.t -> 'some Base.option -> Base.unit

require_some here option is like require here (is_some option), with improved output. If option = None, it prints a CR. If option = Some some and ~print_some is provided, it prints print_some some.

val require_none : ?cr:CR.t -> ?hide_positions:Base.bool -> Base.Source_code_position.t -> ('some -> Base.Sexp.t) -> 'some Base.option -> Base.unit

require_none here sexp_of_some option is like require here (is_none option), with improved output. If option = Some some, it prints a CR including sexp_of_some some. If option = None, it does not print.

val require_ok : ?cr:CR.t -> ?hide_positions:Base.bool -> ?print_ok:('ok -> Base.Sexp.t) -> Base.Source_code_position.t -> 'ok Base.Or_error.t -> Base.unit

require_ok here or_error is like require here (is_ok or_error), with improved output. If or_error = Error error, it prints a CR including error. If or_error = Ok ok and ~print_ok is provided, it prints print_ok ok.

val require_error : ?cr:CR.t -> ?hide_positions:Base.bool -> ?print_error:Base.bool -> Base.Source_code_position.t -> ('ok -> Base.Sexp.t) -> 'ok Base.Or_error.t -> Base.unit

require_error here sexp_of_ok or_error is like require here (is_error or_error), with improved output. If or_error = Ok ok, it prints a CR including sexp_of_ok ok. If or_error = Error error and print_error = true, it prints error.

val require_ok_result : ?cr:CR.t -> ?hide_positions:Base.bool -> ?print_ok:('ok -> Base.Sexp.t) -> Base.Source_code_position.t -> ('error -> Base.Sexp.t) -> ('ok, 'error) Base.Result.t -> Base.unit

require_ok_result here sexp_of_error result is like require here (is_ok or_error), with improved output. If result = Error error, it prints a CR including sexp_of_error error. If result = Ok ok and ~print_ok is provided, it prints print_ok ok.

val require_error_result : ?cr:CR.t -> ?hide_positions:Base.bool -> ?print_error:('error -> Base.Sexp.t) -> Base.Source_code_position.t -> ('ok -> Base.Sexp.t) -> ('ok, 'error) Base.Result.t -> Base.unit

require_error_result here sexp_of_ok result is like require here (is_error result), with improved output. If result = Ok ok, it prints a CR including sexp_of_ok ok. If result = Error error and ~print_error is supplied, it prints print_error error.

val require_first : ?cr:CR.t -> ?hide_positions:Base.bool -> ?print_first:('first -> Base.Sexp.t) -> Base.Source_code_position.t -> ('second -> Base.Sexp.t) -> ('first, 'second) Base.Either.t -> Base.unit

require_first here print_second either is like require here (is_first either), with improved output. If either = Second second, it prints a CR including sexp_of_second second. If either = First first and ~print_first is provided, it prints print_first first.

val require_second : ?cr:CR.t -> ?hide_positions:Base.bool -> ?print_second:('second -> Base.Sexp.t) -> Base.Source_code_position.t -> ('first -> Base.Sexp.t) -> ('first, 'second) Base.Either.t -> Base.unit

require_second here sexp_of_first either is like require here (is_second either), with improved output. If either = First first, it prints a CR including sexp_of_first first. If either = Second second and ~print_second is provided, it prints print_second second.

val print_and_check_stringable : ?cr:CR.t -> ?hide_positions:Base.bool -> Base.Source_code_position.t -> (module With_stringable with type t = 'a) -> 'a Base.list -> Base.unit

Print string representations of the given values, and test that to_string / of_string round-trip.

val print_and_check_sexpable : ?cr:CR.t -> ?hide_positions:Base.bool -> Base.Source_code_position.t -> (module With_sexpable with type t = 'a) -> 'a Base.list -> Base.unit

Print sexp representations of the given values, and test that sexp_of_t / t_of_sexp round-trip.

val print_and_check_round_trip : ?cr:CR.t -> ?hide_positions:Base.bool -> Base.Source_code_position.t -> (module With_equal with type t = 'a) -> (module With_round_trip with type t = 'a) Base.list -> 'a Base.list -> Base.unit

Print the With_round_trip representations of the given values. If there are multiple representations, includes the repr_name of each in the output. Tests that to_repr and of_repr round-trip for each representation.

val quickcheck : Base.Source_code_position.t -> ?cr:CR.t -> ?hide_positions:Base.bool -> ?seed:Base_quickcheck.Test.Config.Seed.t -> ?sizes:Base.int Base.Sequence.t -> ?trials:Base.int -> ?shrinker:'a Base_quickcheck.Shrinker.t -> ?shrink_attempts:Base.int -> ?examples:'a Base.list -> sexp_of:('a -> Base.Sexp.t) -> f:('a -> Base.unit) -> 'a Base_quickcheck.Generator.t -> Base.unit

quickcheck is similar to Base_quickcheck.Test.run, but

1. quickcheck takes separate arguments for the values which Base_quickcheck.Test.run takes in a first-class module.

2. quickcheck stops after the first iteration that raises or prints a CR, as detected by on_print_cr.

val quickcheck_m : Base.Source_code_position.t -> ?config:Base_quickcheck.Test.Config.t -> ?cr:CR.t -> ?examples:'a Base.list -> ?hide_positions:Base.bool -> (module Base_quickcheck.Test.S with type t = 'a) -> f:('a -> Base.unit) -> Base.unit

quickcheck_m is similar to Base_quickcheck.Test.run. It stops after the first iteration that raises or prints a CR, as detected by on_print_cr.

val sexp_style : Sexp_style.t Base.ref

sexp_style determines the sexp format used by sexp_to_string, print_s, and other functions in this module. Defaults to Sexp_style.default_pretty.

val on_print_cr : (Base.string -> Base.unit) Base.ref

on_print_cr determines the behavior of all functions above that print CRs, such as print_cr and require. The rendered string form of the CR is passed to !on_print_cr. The default value is print_endline; this can be overridden to replace or extend the default behavior. For example, some testing harnesses may choose to abort a series of tests after the first CR is printed.

module type With_containers = Expect_test_helpers_core.With_containers
module type With_comparable = Expect_test_helpers_core.With_comparable
module type With_hashable = Expect_test_helpers_core.With_hashable

Serialization tests

val print_and_check_stable_type : ?cr:CR.t -> ?hide_positions:bool -> ?max_binable_length:int -> Core.Source_code_position.t -> (module Core.Stable_without_comparator with type t = 'a) -> 'a list -> unit

print_and_check_stable_type prints the bin-io digest for the given type, and the bin-io and sexp serializations of the given values. Prints an error message for any serializations that fail to round-trip, and for any bin-io serializations that exceed max_binable_length.

val print_and_check_stable_int63able_type : ?cr:CR.t -> ?hide_positions:bool -> ?max_binable_length:int -> Core.Source_code_position.t -> (module Core.Stable_int63able with type t = 'a) -> 'a list -> unit

print_and_check_stable_int63able_type works like print_and_check_stable_type, and includes Int63.t serializations.

val print_and_check_container_sexps : ?cr:CR.t -> ?hide_positions:bool -> Core.Source_code_position.t -> (module With_containers with type t = 'a) -> 'a list -> unit

print_and_check_container_sexps prints the sexp representation of maps, sets, hash tables, and hash sets based on the given values. For sets and hash sets, prints a CR if the sexp does not correspond to a list of elements. For maps and hash tables, prints a CR if the sexp does not correspond to an association list keyed on elements.

val print_and_check_comparable_sexps : ?cr:CR.t -> ?hide_positions:bool -> Core.Source_code_position.t -> (module With_comparable with type t = 'a) -> 'a list -> unit

print_and_check_comparable_sexps is like print_and_check_container_sexps for maps and sets only.

val print_and_check_hashable_sexps : ?cr:CR.t -> ?hide_positions:bool -> Core.Source_code_position.t -> (module With_hashable with type t = 'a) -> 'a list -> unit

print_and_check_hashable_sexps is like print_and_check_container_sexps for hash tables and hash sets only.

val remove_time_spans : string -> string

Removes strings that look like time spans; see Time.Span.

Allocation tests

val require_allocation_does_not_exceed : ?print_limit:int -> ?hide_positions:bool -> Allocation_limit.t -> Core.Source_code_position.t -> (unit -> 'a) -> 'a

require_allocation_does_not_exceed is a specialized form of require that only produces output when f () allocates more than the given limits. The output will include the actual number of major and minor words allocated. We do NOT include these numbers in the successful case because those numbers are not stable with respect to compiler versions and build flags.

If f returns a value that should be ignored, use this idiom:

ignore (require_allocation_does_not_exceed ... f : t)

rather than this idiom:

require_allocation_does_not_exceed ... (fun () -> ignore (f () : t))

With the latter idiom, the compiler may optimize the computation of f () taking advantage of the fact that the result is ignored, and eliminate allocation that is intended to be measured. With the former idiom, the compiler cannot do such optimization and must compute the result of f ().

Also prints up to print_limit allocation locations.

See documentation above about CRs and workflows for failing allocation tests.

val require_no_allocation : ?print_limit:int -> ?hide_positions:bool -> Core.Source_code_position.t -> (unit -> 'a) -> 'a

require_no_allocation here f is equivalent to require_allocation_does_not_exceed (Minor_words 0) here f.

See documentation above about CRs and workflows for failing allocation tests.

val dummy_source_code_position : Core.Source_code_position.t
val opaque_const : 'a -> 'a Bonsai.Computation.t
val opaque_const_value : 'a -> 'a Bonsai.Value.t
val opaque_computation : 'a Bonsai.Computation.t -> 'a Bonsai.Computation.t
module Result_spec : sig ... end
module Handle : sig ... end
module Effect : sig ... end
module Arrow : sig ... end
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct