package expect_test_helpers_core

  1. Overview
  2. Docs

Helpers for producing output inside let%expect_test. Designed for code using Base. See also Expect_test_helpers_core and Expect_test_helpers_async.

module type With_comparator = sig ... end
module type With_compare = sig ... end
module type With_equal = sig ... end
module CR : sig ... end
module Sexp_style : sig ... end
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 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 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 With_comparator with type comparator_witness = 'cmp and type t = 'elt) -> ('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 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.

OCaml

Innovation. Community. Security.