OUnit user guide : OUnit

# Module OUnit

    module OUnit: sig .. end

Unit test building blocks
Author(s): Maas-Maarten Zeeman, Sylvain Le Gall

## Assertions

Assertions are the basic building blocks of unittests.

    val assert_failure : string -> 'a

Signals a failure. This will raise an exception with the specified string.
Raises `Failure` signal a failure

    val assert_bool : string -> bool -> unit

Signals a failure when bool is false. The string identifies the failure.
Raises `Failure` signal a failure

    val (@?) : string -> bool -> unit

Shorthand for assert_bool
Raises `Failure` to signal a failure

    val assert_string : string -> unit

Signals a failure when the string is non-empty. The string identifies the failure.
Raises `Failure` signal a failure

    val assert_command : ?exit_code:Unix.process_status ->
           ?sinput:char Stream.t ->
           ?foutput:(char Stream.t -> unit) ->
           ?use_stderr:bool ->
           ?env:string array -> ?verbose:bool -> string -> string list -> unit

`assert_command prg args` Run the command provided.
Since 1.1.0
`exit_code` : expected exit code
`sinput` : provide this `char Stream.t` as input of the process
`foutput` : run this function on output, it can contains an `assert_equal` to check it
`use_stderr` : redirect `stderr` to `stdout`
`env` : Unix environment
`verbose` : if failed, dump stdout/stderr of the process to stderr

    val assert_equal : ?cmp:('a -> 'a -> bool) ->
           ?printer:('a -> string) ->
           ?pp_diff:(Format.formatter -> 'a * 'a -> unit) ->
           ?msg:string -> 'a -> 'a -> unit

`assert_equal expected real` Compares two values, when they are not equal a failure is signaled.
Version: 1.1.0
Raises `Failure` signal a failure
`cmp` : customize function to compare, default is `=`
`printer` : value printer, don't print value otherwise
`pp_diff` : if not equal, ask a custom display of the difference using `diff fmt exp real` where `fmt` is the formatter to use
`msg` : custom message to identify the failure

    val assert_raises : ?msg:string -> exn -> (unit -> 'a) -> unit

Asserts if the expected exception was raised.
Raises `Failure` description
`msg` : identify the failure

## Skipping tests

In certain condition test can be written but there is no point running it, because they are not significant (missing OS features for example). In this case this is not a failure nor a success. Following functions allow you to escape test, just as assertion but without the same error status.

A test skipped is counted as success. A test todo is counted as failure.

    val skip_if : bool -> string -> unit

`skip cond msg` If `cond` is true, skip the test for the reason explain in `msg`. For example `skip_if (Sys.os_type = "Win32") "Test a doesn't run on windows"`.
Since 1.0.3

    val todo : string -> unit

The associated test is still to be done, for the reason given.
Since 1.0.3

## Compare Functions

    val cmp_float : ?epsilon:float -> float -> float -> bool

Compare floats up to a given relative error.
`epsilon` : if the difference is smaller `epsilon` values are equal

## Bracket

A bracket is a functional implementation of the commonly used setUp and tearDown feature in unittests. It can be used like this:

`"MyTestCase" >:: (bracket test_set_up test_fun test_tear_down)`

    val bracket : (unit -> 'a) -> ('a -> unit) -> ('a -> unit) -> unit -> unit

`bracket set_up test tear_down` The `set_up` function runs first, then the `test` function runs and at the end `tear_down` runs. The `tear_down` function runs even if the `test` failed and help to clean the environment.

    val bracket_tmpfile : ?prefix:string ->
           ?suffix:string ->
           ?mode:Pervasives.open_flag list ->
           (string * Pervasives.out_channel -> unit) -> unit -> unit

`bracket_tmpfile test` The `test` function takes a temporary filename and matching output channel as arguments. The temporary file is created before the test and removed after the test.
Since 1.1.0
`prefix` : see `Filename.open_temp_file`
`suffix` : see `Filename.open_temp_file`
`mode` : see `Filename.open_temp_file`

## Constructing Tests

    type test_fun = unit -> unit

The type of test function

    type test =

`|` | `TestCase of `test_fun``
`|` | `TestList of `test list``
`|` | `TestLabel of `string * test``

The type of tests

    val (>:) : string -> test -> test

Create a TestLabel for a test

    val (>::) : string -> test_fun -> test

Create a TestLabel for a TestCase

    val (>:::) : string -> test list -> test

Create a TestLabel for a TestList
Some shorthands which allows easy test construction.

Examples:

- `"test1" >: TestCase((fun _ -> ()))` => `TestLabel("test2", TestCase((fun _ -> ())))`
- `"test2" >:: (fun _ -> ())` => `TestLabel("test2", TestCase((fun _ -> ())))`
- `"test-suite" >::: ["test2" >:: (fun _ -> ());]` => `TestLabel("test-suite", TestSuite([TestLabel("test2", TestCase((fun _ -> ())))]))`

    val test_decorate : (test_fun -> test_fun) -> test -> test

`test_decorate g tst` Apply `g` to test function contains in `tst` tree.
Since 1.0.3

    val test_filter : ?skip:bool -> string list -> test -> test option

`test_filter paths tst` Filter test based on their path string representation.
Since 1.0.3
`skip` : if set, just use `skip_if` for the matching tests.

## Retrieve Information from Tests

    val test_case_count : test -> int

Returns the number of available test cases

    type node =

`|` | `ListItem of `int``
`|` | `Label of `string``

Types which represent the path of a test

    type path = node list

The path to the test (in reverse order).

    val string_of_node : node -> string

Make a string from a node

    val string_of_path : path -> string

Make a string from a path. The path will be reversed before it is tranlated into a string

    val test_case_paths : test -> path list

Returns a list with paths of the test

## Performing Tests

    type test_result =

`|` | `RSuccess of `path``
`|` | `RFailure of `path * string``
`|` | `RError of `path * string``
`|` | `RSkip of `path * string``
`|` | `RTodo of `path * string``

The possible results of a test

    type test_event =

`|` | `EStart of `path`` | `(*` | A test start. | `*)`
`|` | `EEnd of `path`` | `(*` | A test end. | `*)`
`|` | `EResult of `test_result`` | `(*` | Result of a test. | `*)`

Events which occur during a test run.

    type test_results = test_result list

Results of a test run.

    val perform_test : (test_event -> unit) -> test -> test_results

Perform the test, allows you to build your own test runner

    val run_test_tt : ?verbose:bool -> test -> test_results

A simple text based test runner.
`verbose` : print verbose message

    val run_test_tt_main : ?arg_specs:(Arg.key * Arg.spec * Arg.doc) list ->
           ?set_verbose:(bool -> unit) -> test -> test_results

Main version of the text based test runner. It reads the supplied command line arguments to set the verbose level and limit the number of test to run.
Version: 1.1.0
`arg_specs` : add extra command line arguments
`set_verbose` : call a function to set verbosity

    val ounit2_of_ounit1 : test -> OUnit2.test