package tezt

  1. Overview
  2. Docs

Command-line interface.

When this module is loaded, it parses command line options unconditionally as a side-effect.

type log_level =
  1. | Quiet
  2. | Error
  3. | Warn
  4. | Report
  5. | Info
  6. | Debug

Log levels for standard output.

The list below is sorted from the most quiet level to the most verbose level.

  • Absolutely no log has log level Quiet. In other words, setting log level Quiet inhibits all logs.
  • Error logs are about errors which imply that the current test failed. This includes messages given to Test.fail and uncaught exceptions.
  • Warn logs are about errors that do not cause the current test to fail. This includes failure to clean up temporary files, for instance.
  • Report logs are informational messages that report the result of the current test. They tell the user whether the test was successful or not. They may also include information about how to re-run the test.
  • Info logs are informational messages that summarize what the test is doing. They tell the user that a particular milestone was reached. In tests, it is a good idea to log Info messages at significant checkpoints.
  • Debug logs give more details about exactly what is happening. They include external process outputs, exit codes, and signals which are sent.

Additionally, some flags such as --commands and --list cause some information to be printed unconditionally, even with --quiet. Such kind of output is not considered to be log messages.

type temporary_file_mode =
  1. | Delete
  2. | Delete_if_successful
  3. | Keep

What to do with temporary files after the test is finished.

type loop_mode =
  1. | Infinite
  2. | Count of int

How many times to loop.

type on_unknown_regression_files_mode =
  1. | Warn
  2. | Ignore
  3. | Fail
  4. | Delete
type options = {
  1. mutable color : bool;
  2. mutable log_level : log_level;
  3. mutable log_file : Stdlib.out_channel option;
  4. mutable log_buffer_size : int;
  5. mutable commands : bool;
  6. mutable temporary_file_mode : temporary_file_mode;
  7. mutable keep_going : bool;
  8. mutable files_to_run : string list;
  9. mutable tests_to_run : string list;
  10. mutable tests_not_to_run : string list;
  11. mutable tags_to_run : string list;
  12. mutable tags_not_to_run : string list;
  13. mutable list : [ `Ascii_art | `Tsv ] option;
  14. mutable global_timeout : float option;
  15. mutable test_timeout : float option;
  16. mutable retry : int;
  17. mutable regression_dir : string;
  18. mutable reset_regressions : bool;
  19. mutable on_unknown_regression_files_mode : on_unknown_regression_files_mode;
  20. mutable loop_mode : loop_mode;
  21. mutable time : bool;
  22. mutable starting_port : int;
  23. mutable record : string option;
  24. mutable from_records : string list;
  25. mutable job : (int * int) option;
  26. mutable job_count : int;
  27. mutable suggest_jobs : bool;
  28. mutable junit : string option;
  29. mutable skip : int;
  30. mutable only : int option;
  31. mutable test_args : string Tezt.Base.String_map.t;
}

Command-line options.

log_file is Some channel where channel is open on filename if --log-file filename was specified on the command line. channel is automatically replaced by another channel if init is called again with --log-file. channel is automatically closed either when replaced by another one or at exit.

val options : options

Values for command-line options.

val get : ?default:'a -> (string -> 'a option) -> string -> 'a

Get the value for a parameter specified with --test-arg.

Usage: get parse parameter

If --test-arg parameter=value was specified on the command-line, this calls parse on value. If parse returns None, this fails. If parse returns Some x, this returns x.

If no value for parameter was specified on the command-line, this returns default if default was specified. Else, this fails.

It is recommended to make it so that specifying parameters with --test-arg is not mandatory for everyday use. This means it is recommended to always give default values, and that those default values should be suitable for typical test runs. For parameters that can take a small number of values, it is usually better to register multiple tests, one for each possible value, and to use tags to select from the command-line.

  • raises Failure

    if parse returns None or if parameter was not specified on the command-line using --test-arg and no default value was provided.

val get_bool : ?default:bool -> string -> bool

Same as get bool_of_string_opt.

val get_int : ?default:int -> string -> int

Same as get int_of_string_opt.

val get_float : ?default:float -> string -> float

Same as get float_of_string_opt.

val get_string : ?default:string -> string -> string

Same as get (fun x -> Some x).