OUnit user guide

Index of types
Index of exceptions
Index of values
Index of modules
Index of module types

What is unit Testing?

A test-oriented methodology for software development is most effective whent tests are easy to create, change, and execute. The JUnit tool pioneerded for test-first development in Java. OUnit is an adaptation of JUnit to OCaml.

With OUnit, as with JUnit, you can easily create tests, name them, group them into suites, and execute them, with the framework checking the results automatically.

Getting Started

The basic principle of a test suite is to have a file test.ml which will contain the tests, and an OCaml module under test, named foo.ml.

File foo.ml:

(* The functions we wish to test *)
let unity x = x;;
let funix ()= 0;;
let fgeneric () = failwith "Not implemented";;

The main point of a test is to check that the function under test has the expected behavior. You check the behavior using assert functions. The most simple one is OUnit2.assert_equal. This function compares the result of the function with an expected result.

The most useful functions are:

File test.ml:
open OUnit2;;

let test1 test_ctxt = assert_equal "x" (Foo.unity "x");;

let test2 test_ctxt = assert_equal 100 (Foo.unity 100);;

(* Name the test cases and group them together *)
let suite =
"suite">:::
 ["test1">:: test1;
  "test2">:: test2]
;;

let () =
  run_test_tt_main suite
;;

And compile the module

$ ocamlfind ocamlc -o test -package oUnit -linkpkg -g foo.ml test.ml

A executable named "test" will be created. When run it produces the following output.

$ ./tests
..
Ran: 2 tests in: 0.00 Seconds
OK

When using OUnit2.run_test_tt_main, a non zero exit code signals that the test suite was not successful.

Advanced usage

The topics, cover here, are only for advanced users who wish to unravel the power of OUnit.


OUnit2
Unit test building blocks (v2).

Error reporting

The error reporting part of OUnit is quite important. If you want to identify the failure, you should tune the display of the value and the test.

Here is a list of thing you can display:

open OUnit2;;

let _ =
  "mytest">::
  (fun test_ctxt ->
    assert_equal
      ~msg:"int value"
      ~printer:string_of_int
      1
      (Foo.unity 1))
;;

Command line arguments

OUnit2.run_test_tt_main already provides a set of command line argument to help user to run only the test he wants:

It is also possible to add your own command-line arguments, environment variable and config file variable. You should do it if you want to define some extra arguments.

For example:

open OUnit2;;

let my_program =
  Conf.make_exec "my_program"
;;

let test1 test_ctxt =
  assert_command (my_program test_ctxt) []
;;

let () =
  run_test_tt_main ("test1" >:: test1)
;;

The Conf.make_* creates a command line argument, an environment variable and a config file variable.

Skip and todo tests

Tests are not always meaningful and can even fail because something is missing in the environment. In order to manage this, you can define a skip condition that will skip the test.

If you start by defining your tests rather than implementing the functions under test, you know that some tests will just fail. You can mark these tests as to do tests, this way they will be reported differently in your test suite.

open OUnit2;;

let _ =
  "allfuns" >:::
  [
    "funix">::
    (fun test_ctxt ->
      skip_if (Sys.os_type = "Win32""Don't work on Windows";
      assert_equal
        0
        (Foo.funix ()));

    "fgeneric">::
    (fun test_ctxt ->
      todo "fgeneric not implemented";
      assert_equal
        0
        (Foo.fgeneric ()));
  ]
;;

Effective OUnit

This section is about general tips about unit testing and OUnit. It is the result of some years using OUnit in real world applications.

open OUnit2;;

let _ =
  "Family">:::
  (List.map
    (fun (arg,res) ->
      let title =
        Printf.sprintf "%s->%s" arg res
      in
        title >::
        (fun test_ctxt ->
          assert_equal res (Foo.unity arg)))
      ["abcd""abcd";
       "defg""defg";
       "wxyz""wxyz"])
;;

open OUnit2;;

let _ =
  (* We need to call a function in a particular directory *)
  "change-dir-and-run">::
  (fun test_ctxt ->
    assert_command ~chdir:"/foo/test" "ls" [])
;;


The unit testing scope is always hard to define. Unit testing should be about
testing a single features. But OUnit can help you to test higher level behavior,
by running a full program for example. While it isn't real unit testing, you
can use OUnit to do it and should not hesitate to do it.

In term of line of codes, a test suite can represent from 10% to 150% of the code under test. With time, your test suite will grow faster than your program/library. A good ratio is 33%.
Author(s): Maas-Maarten Zeeman, Sylvain Le Gall