package tezos-test-services

You can search for identifiers within the package.

in-package search v0.2.0

tezos-test-services
- Tezos_test_services
  - Test_services
    
    Alcotest_extra
    
    Mock_sink
    
    Pattern
  - Test_services_base

Legend:
Library
Module
Module type
Parameter
Class
Class type

test_services collects Alcotest testable definitions for base OCaml types and Tezos specific types.

include module type of struct include Alcotest end

include Alcotest_engine.V1.Cli.S with type return = unit

exception Test_error

The exception return by run in case of errors.

Testable values

The following combinators represent types that can be used with the check functions below.

Assertion functions

Functions for asserting various properties within unit-tests. A failing assertion will cause the testcase to fail immediately.

Versioned APIs

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.

include module type of struct include Test_services_base end

include module type of struct include Alcotest end

include Alcotest_engine.V1.Cli.S with type return = unit

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.

type speed_level = [

| `Quick
| `Slow

]

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).

exception Test_error

The exception return by run in case of errors.

val test_case : string -> speed_level -> ('a -> return) -> 'a test_case

test_case n s f is the test case n running at speed s using the function f.

type 'a test = string * 'a test_case list

A 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 =
  ?stdout:Alcotest_engine.Formatters.stdout ->
  ?stderr:Alcotest_engine.Formatters.stderr ->
  ?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 | `Unknown | `Disabled ] ->
  'a

The various options taken by the tests runners run and run_with_args:

stdout (default to Fmt.stdout). The formatter used to print on the standard output.
stderr (default to Fmt.stderr). The formatter used to print ont the standard error output.
and_exit (default true). Once the tests have completed, exit with return code 0 if all tests passed, otherwise 1.
verbose (default false). Display the test std.out and std.err (rather than redirecting to a log file).
compact (default false). Compact the output of the tests.
tail_errors (default unlimited). Show only the last N lines of output of failed tests.
quick_only (default false). Don't run tests with the `Slow speed level.
show_errors (default false). Display the test errors.
json (default false). 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 (if verbose is not set).
bail (default false). If true, stop running the tests after the first failure.
record_backtrace (default true). 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_options

run 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_options

run_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 = Test_services_base.TESTABLE

TESTABLE provides an abstract description for testable values.

type 'a testable = (module TESTABLE with type t = 'a)

The type for testable values.

val testable : 'a Fmt.t -> ('a -> 'a -> bool) -> 'a testable

testable pp eq is a new testable with the pretty-printer pp and equality eq.

val pp : 'a testable -> 'a Fmt.t

pp t is t's pretty-printer.

val equal : 'a testable -> 'a -> 'a -> bool

equal t is t's equality.

val bool : bool testable

bool tests booleans.

val int : int testable

int tests integers.

val int32 : int32 testable

int32 tests 32-bit integers.

val int64 : int64 testable

int64 tests 64-bit integers.

val float : float -> float testable

float tests floats with specified absolute error.

val char : char testable

char tests characters.

val string : string testable

string tests OCaml strings.

val bytes : bytes testable

bytes tests OCaml bytes.

val unit : unit testable

unit tests unit values (useful for functions with side-effects).

val list : 'a testable -> 'a list testable

list t tests lists of ts.

val slist : 'a testable -> ('a -> 'a -> int) -> 'a list testable

slist t comp tests sorted lists of ts. The list are sorted using comp.

val array : 'a testable -> 'a array testable

array t tests arrays of ts.

val option : 'a testable -> 'a option testable

option t tests optional ts.

val result : 'a testable -> 'e testable -> ('a, 'e) result testable

result t e tests ts on success and es on failure.

val pair : 'a testable -> 'b testable -> ('a * 'b) testable

pair a b tests pairs of as and bs.

val triple : 
  'a testable ->
  'b testable ->
  'c testable ->
  ('a * 'b * 'c) testable

triple a b c tests triples of as, bs and cs.

val of_pp : 'a Fmt.t -> 'a testable

of_pp pp tests values which can be printed using pp and compared using Stdlib.compare

val pass : 'a testable

pass tests values of any type and always succeeds.

val reject : 'a testable

reject tests values of any type and always fails.

val neg : 'a testable -> 'a testable

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 =
  Tezos_test_services.Test_services_base.Source_code_position

type 'a extra_info =
  ?here:Source_code_position.here ->
  ?pos:Source_code_position.pos ->
  'a

The 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_info

check testable msg expected actual checks that two values are equal.

msg is printed if the check fails.

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_info

Check that two values are equal (labeled variant of check).

val fail : (string -> 'a) extra_info

Simply fail.

val failf : (('a, Format.formatter, unit, 'b) format4 -> 'a) extra_info

Simply fail with a formatted message.

val check_raises : (string -> exn -> (unit -> unit) -> unit) extra_info

Check that an exception is raised.

val match_raises : 
  (string -> (exn -> bool) -> (unit -> unit) -> unit) extra_info

Check that an exception is raised.

val skip : unit -> 'a

Skip the current test case.

since 1.7.0

Versioned APIs

module V1 = Tezos_test_services.Test_services_base.V1

An 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.

module Unix_platform = Tezos_test_services.Test_services_base.Unix_platform

val exn : exn testable

val map : ('b -> 'a) -> 'a testable -> 'b testable

val pair3 : ('a * ('b * 'c)) testable -> ('a * 'b * 'c) testable

val pair4 : ('a * ('b * ('c * 'd))) testable -> ('a * 'b * 'c * 'd) testable

val tuple3 : 
  'a testable ->
  'b testable ->
  'c testable ->
  ('a * 'b * 'c) testable

val tuple4 : 
  'a testable ->
  'b testable ->
  'c testable ->
  'd testable ->
  ('a * 'b * 'c * 'd) testable

val assert_true : string -> bool -> unit

val assert_false : string -> bool -> unit

val impossible : string -> unit

val lwt_assert_true : string -> bool -> unit Lwt.t

val lwt_assert_false : string -> bool -> unit Lwt.t

val lwt_check : 'a Alcotest.testable -> string -> 'a -> 'a -> unit Lwt.t

val lwt_impossible : string -> unit Lwt.t

val lwt_fail : string -> unit Lwt.t

val lwt_assert_catch : (unit -> unit Lwt.t) -> exn -> unit Lwt.t

val contains : 'a testable -> string -> 'a -> 'a list -> unit

val trace : Tezos_error_monad.TzCore.error list testable

val tzresults : 
  'a testable ->
  ('a, Tezos_error_monad.TzCore.error list) result testable

val p2p_peer_id : Tezos_base.P2p_peer.Id.t Alcotest.testable

val json : Data_encoding.json testable

val tztest : 
  string ->
  Alcotest.speed_level ->
  (unit -> (unit, Tezos_error_monad.TzCore.error list) result Lwt.t) ->
  unit Alcotest_lwt.test_case

Transorm a function running in the error monad into an Alcotest, taking care of failing the test if the function results is an error. Note that the given function must still take care of test assertions.

module Alcotest_extra : sig ... end

module Mock_sink : sig ... end

val mock_sink : Mock_sink.t Tezos_event_logging.Internal_event.sink_definition

val with_empty_mock_sink : (unit -> unit Lwt.t) -> unit Lwt.t

with_empty_mock_sink f executes f after activating or clearing a Mock_sink sink.

Sinks can only be registered and activated once, and not removed thereafter.