<!DOCTYPE book PUBLIC "-//Davenport//DTD DocBook V3.0//EN">

<book>

<title>OUnit User's Guide</title>

<bookinfo>
  <authorgroup>
    <author>
      <firstname>Maas-Maarten Zeeman</firstname>
      <surname>Zeeman</firstname>
      <authorblurb>
        <para>
          <address>
            <email>maas@wanadoo.nl</email>
          </address>
        </para>
      </authorblurb>
    </author>
  </authorgroup>

  <copyright>
    <year>2003</year>
  </copyright>

  <abstract>
    <para>
      Ounit is a unit testing framework for Ocaml, inspired by HUnit
      for Haskell, and JUnit for Java. This guide describes how to use
      OUnit, assuming you are familiar with Ocaml, though not
      necessarily with JUnit.
    </para>

    <para>
      Warning!, this is largely unfinished
    </para>
  </abstract>
    
  <legalnotice>
    <title>License</title>
    <para>
    </para>
  </legalnotice>
</bookinfo>

<!~~~~~--> 

<chapter>
<title>Introduction into test oriented programming</test>

  <para>
    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, a general purpose functional
    programming language.
  </para>

  <para>
    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. Test specification in OUnit is
    even more concise and flexible than in JUnit, thanks to the nature
    of the Ocaml language, or the functional programming paradigm in
    general.
  </para>

  <para>
    The next section helps you to get started using OUnit in simple
    ways.
  </para>

Getting Started

  In the Ocaml module 'tests.ml' where your tests will reside, import
  module OUnit::

    open OUnit

  Define test cases as appropriate::

    let test1 = TestCase(fun _ -> assert_equal "x" (foo "x"));; 
    let test2 = TestCase(fun _ -> assert_equal 100 (foo 100));;

  Name the test cases and group them together::

    let suite = TestLabel ("suite", TestList [TestLabel ("test1", test1); 
                                              TestLabel ("test2", test2)])

  And compile the module::

    $ocamlc -c tests.ml
    File "tests.ml", line 3, characters 48-51:    Unbound value foo

  Now it is time to program 'foo', create a new module named 'foo.ml',
  and type::

    let foo x = x

  And compile::

    $ocamlc -c foo.ml

  The 'Foo' module must now also be opened in the 'Tests' module, so
  we need to add the following line.::

    open Foo

  Now it is possible to compile 'Tests'::

    $ocamlc -c foo.cmo tests.ml

  With the ocamlunit toplevel it is possible to run the tests
  interactively::

    $ ./ocamlunit
    #         Objective Caml version 3.04

    # load "tests.cmo";;
    # OUnit.run_test_tt Tests.suite;;
    ..
    Ran: 2 tests in: 0.00 Seconds
    OK
    - : OUnit.counts =
    {OUnit.cases = 2; OUnit.tried = 2; OUnit.errors = 0; OUnit.failures = 0}
    #

  Isn't that easy?

  You can specify the tests even more succinctly using special
  operators::

    let suite = "suite" >::: ["test1" >:: test1;
			      "test2" >:: test2;] 

  It is also possible to add the following line to the 'Tests'
  module.::
  
    let main = run_tess_tt suite

  When compiled as follows::

    $ocamlfind ocamlc -o tests -package oUnit -linkpkg foo.cmo tests.ml

  A executable name 'tests' will be created. When run it produces the
  following output.

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

    

Test Case

  A test case is the unit of test execution. That is distinct test
  cases are executed independently. The failure of one is independant
  of the failure of any other, provided the test case does not rely on
  side-effects. 
    

</book>
    

