OUnit user guide : OUnit2

# Module OUnit2

    module OUnit2: sig .. end

Unit test building blocks (v2).
Author(s): Sylvain Le Gall

## Types

    type test_ctxt = OUnitTest.ctxt

Context of a test.

    type test_fun = test_ctxt -> unit

The type of test function.

    type test = OUnitTest.test

The type of test.

    type test_length = OUnitTest.test_length

The expected length of the test.

## 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 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 ->
           ?backtrace:bool ->
           ?chdir:string ->
           ?env:string array -> ctxt:test_ctxt -> string -> string list -> unit

`assert_command prg args` Run the command provided.
`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`
`backtrace` : Set OCAMLRUNPARAM=b
`chdir` : Chdir into a directory before running the command.
`env` : Unix environment

    val assert_equal : ?ctxt:test_ctxt ->
           ?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.
Raises `Failure` signal a failure
`ctxt` : if provided, always print expected and real value
`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"`.

    val todo : string -> unit

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

## 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 registered object with setUp and tearDown in unit tests. Data generated during the setUp will be automatically tearDown when the test ends.

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

`bracket set_up tear_down test_ctxt` set up an object and register it to be tore down in `test_ctxt`.

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

`bracket_tmpfile test_ctxt` Create a temporary filename and matching output channel. The temporary file is removed after the test.
`prefix` : see `Filename.open_temp_file`
`suffix` : see `Filename.open_temp_file`
`mode` : see `Filename.open_temp_file`

    val bracket_tmpdir : ?prefix:string -> ?suffix:string -> test_ctxt -> string

`bracket_tmpdir test_ctxt` Create a temporary dirname. The temporary directory is removed after the test.
`prefix` : see `Filename.open_temp_file`
`suffix` : see `Filename.open_temp_file`

    val with_bracket_chdir : test_ctxt -> string -> (test_ctxt -> 'a) -> 'a

`with_bracket_chdir test_ctxt dn f` change directory to `dn` during execution of function `f`. In order to `Sys.chdir`, we need to take a lock to avoid other tests trying to do change the current directory at the same time. So this bracket is not directly accessible in order to use it only on shorter piece of code.

## Constructing 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

    val test_case : ?length:test_length -> test_fun -> test

Generic function to create a test case.

    val test_list : test list -> test

Generic function to create a test list.
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 _ -> ())))]))`

## Performing Tests

    type log_severity = [ `Error | `Info | `Warning ]

Severity level for log.

    val logf : test_ctxt ->
           log_severity -> ('a, unit, string, unit) Pervasives.format4 -> 'a

Log into OUnit logging system.

    val in_testdata_dir : test_ctxt -> string list -> string

Build a filename for a file that should be located in the test data dir.

The test data dir, can be defined on the command line (preferably absolute) The default option is to locate it in topsrcdir/test/data.

    val non_fatal : test_ctxt -> (test_ctxt -> unit) -> unit

`non_fatal ctxt f` Run `f` but if an exception is raised or an assert fails, don't stop, just register the result. The global test running result will mix in the non fatal result to determine the success or failure of the test.

    module Conf: sig .. end

Define command line options, environment variables and file configuration.

    val run_test_tt_main : ?exit:(int -> unit) -> test -> unit

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.