Module Tezt_wrapper.TestSource

include module type of Tezt.Test
include module type of struct include Tezt_core.Test end
val declare_reset_function : (unit -> unit) -> unit

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.

val fail : ?__LOC__:string -> ('a, Format.formatter, unit, 'b) format4 -> 'a

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.

type seed = Tezt_core.Test.seed =
  1. | Fixed of int
  2. | Random

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 current_worker_id : unit -> int option

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);
  • or Some id where 0 <= id < Cli.options.job_count and where id uniquely identifies the current worker process that is running the current test.
val current_test_file : unit -> string

Get the filename of the currently running test.

Return "" if not currently running a test.

val current_test_title : unit -> string

Get the title of the currently running test.

Return "" if not currently running a test.

val current_test_tags : unit -> string list

Get the list of tags of the currently running test.

Return the empty list if not currently running a test.

val current_test_has_tag : string -> bool

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.

val current_test_seed : unit -> int

Get the random seed of the currently running test.

Return 0 if not currently running a test.

val current_test_seed_specification : unit -> seed

Return the ~seed parameter of the current test.

Return Random if not currently running a test.

Internals

The rest of this module is used by other modules of Tezt. You usually do not need to use it yourself.

val before_test_run : (unit -> unit) -> unit

Add a function to be called by run_with_scheduler before it does anything.

type used_seed = Tezt_core.Test.used_seed =
  1. | Used_fixed
  2. | Used_random of int

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 = {
  1. test_result : Tezt_core.Log.test_result;
  2. 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).

Test descriptions.

val get_test_by_title : string -> t option

Get a test by its title.

Return None if no test was registered 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
Sourceval run : unit -> unit

Run registered tests that should be run.

This function is not available in tezt.core. It is available in tezt and tezt.js.

Sourceval register : __FILE__:string -> title:string -> tags:string list -> ?uses:Uses.t list -> ?seed:seed -> (unit -> unit Lwt.t) -> unit

Wrapper over Tezt.Test.register that checks test dependencies (?uses).