expect_test_helpers v0.12.0

An extension of Expect_test_helpers_kernel with Async-aware functions.

include module type of struct include Expect_test_helpers_kernel end

include module type of struct include Expect_test_helpers_base end

module type Set = Expect_test_helpers_kernel.Set

module type With_compare = Expect_test_helpers_kernel.With_compare

module type With_equal = Expect_test_helpers_kernel.With_equal

module CR = Expect_test_helpers_kernel.CR

module Sexp_style = Expect_test_helpers_kernel.Sexp_style

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 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 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_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_sets_are_equal : 
  ?cr:CR.t ->
  ?hide_positions:Base.bool ->
  ?names:(Base.string * Base.string) ->
  Base.Source_code_position.t ->
  (module Set with type t = 'a) ->
  'a ->
  'a ->
  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 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. 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_kernel.With_containers

module type With_comparable = Expect_test_helpers_kernel.With_comparable

module type With_hashable = Expect_test_helpers_kernel.With_hashable

module Allocation_limit = Expect_test_helpers_kernel.Allocation_limit

val print_and_check_stable_type : 
  ?cr:CR.t ->
  ?hide_positions:bool ->
  ?max_binable_length:int ->
  Core_kernel.Source_code_position.t ->
  (module Core_kernel.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_kernel.Source_code_position.t ->
  (module Core_kernel.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 prepare_heap_to_count_minor_allocation : unit -> unit

prepare_heap_to_count_minor_allocation calls Gc functions to setup the heap so that one can subsequently measure minor allocation via:

let minor_words_before = Gc.minor_words () in
(* ... do stuff ... *)
let minor_words_after = Gc.minor_words () in
let minor_words_allocated = minor_words_after - minor_words_before in

val require_allocation_does_not_exceed : 
  ?cr:CR.t ->
  ?hide_positions:bool ->
  Allocation_limit.t ->
  Core_kernel.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 (show_allocation f : t)

rather than this idiom:

show_allocation (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 ().

val require_no_allocation : 
  ?cr:CR.t ->
  ?hide_positions:bool ->
  Core_kernel.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.

val print_and_check_container_sexps : 
  ?cr:CR.t ->
  ?hide_positions:bool ->
  Core_kernel.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_kernel.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_kernel.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 with_temp_dir : (string -> 'a Async.Deferred.t) -> 'a Async.Deferred.t

with_temp_dir f creates a temporary directory which is fed to f. The directory is removed after f exits.

val within_temp_dir : 
  ?links:(string * [ `In_path_as | `In_temp_as ] * string) list ->
  (unit -> 'a Async.Deferred.t) ->
  'a Async.Deferred.t

within_temp_dir ?links f creates a temporary directory, $T, and:

1. Adds $T/bin to the PATH environment variable. 2. For each file, `In_path_as, name in links, links file as $T/bin/name. 3. For each file, `In_temp_as, name in links, links file as $T/name.

It then cds to $T and calls f. After f exits, it cds back, removes the temporary directory, and restores the original PATH.

within_temp_dir creates hard links to ensure that files remain available and unchanged even if jenga starts to rebuild while the test is running. If file and $T are not on the same file system, within_temp_dir copies the files instead of creating hard links.

val run : 
  ?enable_ocaml_backtraces:bool ->
  ?extend_env:(string * string) list ->
  ?hide_positions:bool ->
  ?postprocess:(string -> string) ->
  ?print_cmdline:bool ->
  ?print_stdout:bool ->
  ?print_stderr:bool ->
  ?stdin:string ->
  ?working_dir:string ->
  string ->
  string list ->
  unit Async.Deferred.t

run prog args creates a child process that runs prog, with arguments args, its environment extended with extend_env and its stdin coming from stdin. No expansion or escaping is done to args or stdin. The child process's stdout and stderr are captured separately for comparison.

val system : 
  ?enable_ocaml_backtraces:bool ->
  ?hide_positions:bool ->
  ?print_cmdline:bool ->
  ?stdin:string ->
  string ->
  unit Async.Deferred.t

system ?stdin cmd creates a child process that runs /bin/sh, with arguments "-c"; cmd and its stdin coming from stdin. The child process's stdout and stderr are captured separately for comparison. Unlike with Unix.system, the child shell's stdin is never a tty, even if the stdin of this process is a tty, and the child shell's stderr is never copied to this process's stderr.

val show_raise' : 
  ?hide_positions:bool ->
  (unit -> _ Async.Deferred.t) ->
  unit Async.Deferred.t

show_raise' ?hide_positions ?rest f calls f () and prints either the exception raised by f or "did not raise". show_raise' ignores the result of f so that one doesn't have to put an ignore inside f. ~hide_positions operates as in print_s, to make output less fragile. Once a result is returned, the rest of the errors are printed to stdout.

val require_does_not_raise' : 
  ?cr:CR.t ->
  ?hide_positions:bool ->
  ?show_backtrace:bool ->
  Core.Source_code_position.t ->
  (unit -> unit Async.Deferred.t) ->
  unit Async.Deferred.t

require_does_not_raise' is like require_does_not_raise, but for functions that produce a deferred result.

val require_does_raise' : 
  ?cr:CR.t ->
  ?hide_positions:bool ->
  ?show_backtrace:bool ->
  Core.Source_code_position.t ->
  (unit -> _ Async.Deferred.t) ->
  unit Async.Deferred.t

require_does_raise' is like require_does_raise, but for functions that produce a deferred result.

module Expect_test_config = Async.Expect_test_config

We export Expect_test_config so that the %expect syntax uses Async, to prevent a confusing situation in which one is using Expect_test_helpers functions, which expect Async to be running, but Async isn't running.

package expect_test_helpers