Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
package alcotest
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
A lightweight and colourful test framework.
Alcotest provides a simple interface to perform unit tests. It exposes a simple TESTABLE module type, a check function to assert test predicates and a run function to perform a list of unit -> unit test callbacks.
From these descriptions, Alcotest builds a quiet and colorful output where only faulty runs are fully displayed at the end of the run (with the full logs ready to inspect).
Release 1.7.0
include Alcotest_engine.V1.Cli.S with type return = unit
The return type of each test case run by Alcotest. For the standard Alcotest module, return = unit. The concurrent backends Alcotest_lwt and Alcotest_async set return = unit Lwt.t and return = Async_kernel.Deferred.t respectively.
Speed level of a test. Tests marked as `Quick are always run. Tests marked as `Slow are skipped when the `-q` flag is passed.
type 'a test_case = string * speed_level * ('a -> return)A test case is a UTF-8 encoded documentation string, a speed level and a function to execute. Typically, the testing function calls the helper functions provided below (such as check and fail).
The exception return by run in case of errors.
val test_case : string -> speed_level -> ('a -> return) -> 'a test_casetest_case n s f is the test case n running at speed s using the function f.
type 'a test = string * 'a test_case listA test is a UTF-8 encoded name and a list of test cases. The name can be used for filtering which tests to run on the CLI.
type 'a with_options =
?and_exit:bool ->
?verbose:bool ->
?compact:bool ->
?tail_errors:[ `Unlimited | `Limit of int ] ->
?quick_only:bool ->
?show_errors:bool ->
?json:bool ->
?filter:(name:string -> index:int -> [ `Run | `Skip ]) ->
?log_dir:string ->
?bail:bool ->
?record_backtrace:bool ->
?ci:[ `Github_actions | `OCamlci | `Unknown | `Disabled ] ->
'aThe various options taken by the tests runners run and run_with_args:
and_exit(defaulttrue). Once the tests have completed, exit with return code0if all tests passed, otherwise1.verbose(defaultfalse). Display the test std.out and std.err (rather than redirecting to a log file).compact(defaultfalse). Compact the output of the tests.tail_errors(default unlimited). Show only the last N lines of output of failed tests.quick_only(defaultfalse). Don't run tests with the`Slowspeed level.show_errors(defaultfalse). Display the test errors.json(defaultfalse). Print test results in a JSON-compatible format.filter. Filter tests according to~name, the name of the test, and~index, the number of the test case.log_dir(default"$PWD/_build/_tests/"). The directory in which to log the output of the tests (ifverboseis not set).bail(defaultfalse). If true, stop running the tests after the first failure.record_backtrace(defaulttrue). Enable backtrace recording before beginning testing.ci(default auto-detected). Whether to enable specific logging for a CI system.
val run :
(?argv:string array -> string -> unit test list -> return) with_optionsrun n t runs the test suite t. n is the name of the tested library.
The optional argument and_exit controls what happens when the function ends. By default, and_exit is set, which makes the function exit with 0 if everything is fine or 1 if there is an issue. If and_exit is false, then the function raises Test_error on error.
The optional argument argv specifies command line arguments sent to alcotest like "--json", "--verbose", etc. Note that this array will be treated like a regular Sys.argv, so the array must have at least one element, and the first element will be treated as if it was the command name and thus ignored for the purposes of option processing. So ~argv:[||] is an error, ~argv:[| "--verbose" |] will have no effect, and ~argv:[| "ignored"; "--verbose" |] will successfully pass the verbose option.
val run_with_args :
(?argv:string array ->
string ->
'a Cmdliner.Term.t ->
'a test list ->
return)
with_optionsrun_with_args n a t Similar to run a t but take an extra argument a. Every test function will receive as argument the evaluation of the Cmdliner term a: this is useful to configure the test behaviors using the CLI.
Testable values
The following combinators represent types that can be used with the check functions below.
module type TESTABLE = sig ... endTESTABLE provides an abstract description for testable values.
val testable : 'a Fmt.t -> ('a -> 'a -> bool) -> 'a testabletestable pp eq is a new testable with the pretty-printer pp and equality eq.
val pp : 'a testable -> 'a Fmt.tpp t is t's pretty-printer.
val equal : 'a testable -> 'a -> 'a -> boolequal t is t's equality.
val bool : bool testablebool tests booleans.
val int : int testableint tests integers.
val int32 : int32 testableint32 tests 32-bit integers.
val int64 : int64 testableint64 tests 64-bit integers.
val float : float -> float testablefloat tests floats with specified absolute error.
val char : char testablechar tests characters.
val string : string testablestring tests OCaml strings.
val bytes : bytes testablebytes tests OCaml bytes.
val unit : unit testableunit tests unit values (useful for functions with side-effects).
slist t comp tests sorted lists of ts. The list are sorted using comp.
result t e tests ts on success and es on failure.
triple a b c tests triples of as, bs and cs.
val of_pp : 'a Fmt.t -> 'a testableof_pp pp tests values which can be printed using pp and compared using Stdlib.compare
val pass : 'a testablepass tests values of any type and always succeeds.
val reject : 'a testablereject tests values of any type and always fails.
neg t is t's negation: it is true when t is false and it is false when t is true.
Assertion functions
Functions for asserting various properties within unit-tests. A failing assertion will cause the testcase to fail immediately.
module Source_code_position : sig ... endtype 'a extra_info =
?here:Source_code_position.here ->
?pos:Source_code_position.pos ->
'aThe assertion functions optionally take information about the location at which they are called in the source code. This is used for giving more descriptive error messages in the case of failure.
val check : ('a testable -> string -> 'a -> 'a -> unit) extra_infoCheck that two values are equal.
If check isn't in a tail-call position, Alcotest may guess the location of the check. Otherwise, use extra_info to report the location.
val check' :
('a testable -> msg:string -> expected:'a -> actual:'a -> unit) extra_infoCheck that two values are equal (labeled variant of check).
val fail : (string -> 'a) extra_infoSimply fail.
val failf :
(('a, Stdlib.Format.formatter, unit, 'b) Stdlib.format4 -> 'a) extra_infoSimply fail with a formatted message.
val check_raises : (string -> exn -> (unit -> unit) -> unit) extra_infoCheck that an exception is raised.
Versioned APIs
module V1 : sig ... endAn alias of the above API that provides a stability guarantees over major version changes.
Unix-specific engine constructors
The Alcotest_engine package provides the most general form of the Alcotest API, parameterised over the thread implementation and the platform. This package provides the Unix platform implementation.