package tezt
-
tezt.json
Legend:
Library
Module
Module type
Parameter
Class
Class type
Library
Module
Module type
Parameter
Class
Class type
Base test management (registering, initializations, etc).
include module type of struct include Tezt_core.Test end
Add a function to be called before each test start.
Used to reset counters such as the ones which are used to choose default process names.
val declare_clean_up_function : (Tezt_core.Log.test_result -> unit) -> unit
Add a function to be called at the end of each test.
The function is called before the automatic clean up of external processes and temporary files, whether the test succeeded, failed or was aborted.
If the function raises an exception, the exception is logged as a warning, but this does not fail the test.
Log an error and stop the test right here.
If the optional location __LOC__
is provided, it is prepended to the error message. You would typically use it simply as Test.fail ~__LOC__ "..."
to prepend location of the failure.
How to initialize Stdlib.Random
at the beginning of a test.
Fixed seed
: the test is initialized using Random.init seed
. This makes sure that using the Random
module does not cause the test to be non-deterministic. Note that --seed
has no effect in this case.Random
: the test is initialized using a random seed, unless --seed
is specified on the command-line, in which case this seed is used. The random seed that is chosen is logged at the beginning of the test.val register :
__FILE__:string ->
title:string ->
tags:string list ->
?seed:seed ->
(unit -> unit Lwt.t) ->
unit
Register a test.
The __FILE__
argument, which should be equal to __FILE__
(i.e. just write Test.register ~__FILE__
), is used to let the user select which files to run from the command-line.
One should be able to infer, from title
, what the test will do. It is typically a short sentence like "addition is commutative"
or "server runs until client tells it to stop"
.
The list of tags
must be composed of short strings which are easy to type on the command line (lowercase letters, digits and underscores). Run the test executable with --list
to get the list of tags which are already used by existing tests. Try to reuse them if possible.
The last argument is a function f
which implements the test. If f
needs to spawn external processes, it should use the Process
module to do so, so that those processes are automatically killed at the end of the test. Similarly, if this function needs to create temporary files, it should declare them with Temp
, and if it needs to have promises that run in the background, it should use Background.register
(and not Lwt.async
in particular).
If f
raises an exception, act as if fail
was called (without the error location unfortunately).
You can call register
several times in the same executable if you want it to run several tests. Each of those tests should be standalone, as the user is able to specify the list of tests to run on the command-line.
The test is not actually run until you call run
.
Get the current worker id.
In single-process mode (with -j 1
), this always returns None
.
In multi-process mode, this returns either:
None
(if called in the scheduler process, i.e. outside of a test);Some id
where 0 <= id < Cli.options.job_count
and where id
uniquely identifies the current worker process that is running the current test.Get the filename of the currently running test.
Return ""
if not currently running a test.
Get the title of the currently running test.
Return ""
if not currently running a test.
Get the list of tags of the currently running test.
Return the empty list if not currently running a test.
Test whether the current test has a given tag.
current_test_has_tag tag
is the same as List.mem tag (current_test_tags ())
.
An example of use case is to enable a function that runs an external executable only if a tag is present, to force tests that depend on this executable to have a given tag. In turn, this allows you to configure your CI to not run tests with this tag if the executable was not modified.
Get the random seed of the currently running test.
Return 0
if not currently running a test.
The rest of this module is used by other modules of Tezt. You usually do not need to use it yourself.
Add a function to be called by run_with_scheduler
before it does anything.
How the seed for the PRNG was chosen.
Used_fixed
: used the Fixed
seed given to Test.register
.Used_random seed
: chose seed
using self-initialization or from the --seed
command-line argument.type test_result = Tezt_core.Test.test_result = {
test_result : Tezt_core.Log.test_result;
seed : used_seed;
}
Data that a test sends to the scheduler after it is done.
module type SCHEDULER = Tezt_core.Test.SCHEDULER
val run_with_scheduler : (module SCHEDULER) -> unit
Generic function to run registered tests that should be run.
Depending on command-line options, this may do something else, such as printing the list of tests.
Instead of calling this directly, call Test.run
, which is provided by the particular variant of Tezt you are using (Unix or JavaScript).
type t = Tezt_core.Test.t
Test descriptions.
val get_test_by_title : string -> t option
Get a test by its title.
Return None
if no test was register
ed with this title.
val run_one :
sleep:(float -> unit Lwt.t) ->
clean_up:(unit -> unit Lwt.t) ->
temp_start:(unit -> string) ->
temp_stop:(unit -> unit) ->
temp_clean_up:(unit -> unit) ->
t ->
test_result Lwt.t
Run one test.
sleep
is a function such as Lwt_unix.sleep
or Lwt_js.sleep
. It is used to implement timeouts.
clean_up
is a function such as Process.clean_up
(plus a wrapper to handle exceptions). It is ran at the end of the test.
module String_tree = Tezt_core.Test.String_tree