Library
Module
Module type
Parameter
Class
Class type
Helpers for producing output inside let%expect_test
. Designed for code using Core
. See also Expect_test_helpers_base
and Expect_test_helpers_async
.
include module type of struct include Expect_test_helpers_base end
module type With_comparator = Expect_test_helpers_base.With_comparator
module type With_compare = Expect_test_helpers_base.With_compare
module type With_equal = Expect_test_helpers_base.With_equal
module CR = Expect_test_helpers_base.CR
module Phys_equal = Expect_test_helpers_base.Phys_equal
module Sexp_style = Expect_test_helpers_base.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 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 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 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 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 = sig ... end
module type With_comparable = sig ... end
module type With_hashable = sig ... end
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.
module Allocation_limit : sig ... end
val require_allocation_does_not_exceed :
?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 ()
.
See documentation above about CRs and workflows for failing allocation tests.
val require_no_allocation :
?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.