<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" href="style.css" type="text/css">
<meta content="text/html; charset=iso-8859-1" http-equiv="Content-Type">
<link rel="Start" href="index.html">
<link rel="previous" href="OUnit.html">
<link rel="next" href="OUnitThreads.html">
<link rel="Up" href="index.html">
<link title="Index of types" rel=Appendix href="index_types.html">
<link title="Index of exceptions" rel=Appendix href="index_exceptions.html">
<link title="Index of values" rel=Appendix href="index_values.html">
<link title="Index of modules" rel=Appendix href="index_modules.html">
<link title="Index of module types" rel=Appendix href="index_module_types.html">
<link title="OUnit" rel="Chapter" href="OUnit.html">
<link title="OUnit2" rel="Chapter" href="OUnit2.html">
<link title="OUnitThreads" rel="Chapter" href="OUnitThreads.html">
<link title="OUnitUtils" rel="Chapter" href="OUnitUtils.html">
<link title="OUnitPropList" rel="Chapter" href="OUnitPropList.html">
<link title="OUnitPlugin" rel="Chapter" href="OUnitPlugin.html">
<link title="OUnitChooser" rel="Chapter" href="OUnitChooser.html">
<link title="OUnitResultSummary" rel="Chapter" href="OUnitResultSummary.html">
<link title="OUnitLoggerStd" rel="Chapter" href="OUnitLoggerStd.html">
<link title="OUnitLoggerHTML" rel="Chapter" href="OUnitLoggerHTML.html">
<link title="OUnitLoggerHTMLData" rel="Chapter" href="OUnitLoggerHTMLData.html">
<link title="OUnitLoggerJUnit" rel="Chapter" href="OUnitLoggerJUnit.html">
<link title="OUnitAssert" rel="Chapter" href="OUnitAssert.html">
<link title="OUnitBracket" rel="Chapter" href="OUnitBracket.html">
<link title="OUnitTest" rel="Chapter" href="OUnitTest.html">
<link title="OUnitState" rel="Chapter" href="OUnitState.html">
<link title="OUnitRunner" rel="Chapter" href="OUnitRunner.html">
<link title="OUnitRunnerProcesses" rel="Chapter" href="OUnitRunnerProcesses.html">
<link title="OUnitCore" rel="Chapter" href="OUnitCore.html">
<link title="OUnitLogger" rel="Chapter" href="OUnitLogger.html">
<link title="OUnitConf" rel="Chapter" href="OUnitConf.html">
<link title="OUnitShared" rel="Chapter" href="OUnitShared.html">
<link title="OUnitCache" rel="Chapter" href="OUnitCache.html">
<link title="OUnitTestData" rel="Chapter" href="OUnitTestData.html">
<link title="OUnitCheckEnv" rel="Chapter" href="OUnitCheckEnv.html">
<link title="OUnitDiff" rel="Chapter" href="OUnitDiff.html"><link title="Types" rel="Section" href="#2_Types">
<link title="Assertions" rel="Section" href="#2_Assertions">
<link title="Skipping tests " rel="Section" href="#2_Skippingtests">
<link title="Compare Functions" rel="Section" href="#2_CompareFunctions">
<link title="Bracket" rel="Section" href="#2_Bracket">
<link title="Constructing Tests" rel="Section" href="#2_ConstructingTests">
<link title="Performing Tests" rel="Section" href="#2_PerformingTests">
<title>OUnit user guide : OUnit2</title>
</head>
<body>
<div class="navbar"><a href="OUnit.html">Previous</a>
<a href="index.html">Up</a>
<a href="OUnitThreads.html">Next</a>
</div>
<center><h1>Module <a href="type_OUnit2.html">OUnit2</a></h1></center>
<br>
<pre><span class="keyword">module</span> OUnit2: <code class="code"><span class="keyword">sig</span></code> <a href="OUnit2.html">..</a> <code class="code"><span class="keyword">end</span></code></pre>Unit test building blocks (v2).<br>
<b>Author(s):</b> Sylvain Le Gall<br>
<hr width="100%">
<br>
<span id="2_Types"><h2>Types</h2></span><br>
<pre><span id="TYPEtest_ctxt"><span class="keyword">type</span> <code class="type"></code>test_ctxt</span> = <code class="type"><a href="OUnitTest.html#TYPEctxt">OUnitTest.ctxt</a></code> </pre>
<div class="info">
Context of a test.<br>
</div>
<pre><span id="TYPEtest_fun"><span class="keyword">type</span> <code class="type"></code>test_fun</span> = <code class="type"><a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> unit</code> </pre>
<div class="info">
The type of test function.<br>
</div>
<pre><span id="TYPEtest"><span class="keyword">type</span> <code class="type"></code>test</span> = <code class="type"><a href="OUnitTest.html#TYPEtest">OUnitTest.test</a></code> </pre>
<div class="info">
The type of test.<br>
</div>
<pre><span id="TYPEtest_length"><span class="keyword">type</span> <code class="type"></code>test_length</span> = <code class="type"><a href="OUnitTest.html#TYPEtest_length">OUnitTest.test_length</a></code> </pre>
<div class="info">
The expected length of the test.<br>
</div>
<br>
<span id="2_Assertions"><h2>Assertions</h2></span>
<p>
Assertions are the basic building blocks of unittests.<br>
<pre><span id="VALassert_failure"><span class="keyword">val</span> assert_failure</span> : <code class="type">string -> 'a</code></pre><div class="info">
Signals a failure. This will raise an exception with the specified
string.<br>
<b>Raises</b> <code>Failure</code> signal a failure<br>
</div>
<pre><span id="VALassert_bool"><span class="keyword">val</span> assert_bool</span> : <code class="type">string -> bool -> unit</code></pre><div class="info">
Signals a failure when bool is false. The string identifies the
failure.<br>
<b>Raises</b> <code>Failure</code> signal a failure<br>
</div>
<pre><span id="VALassert_string"><span class="keyword">val</span> assert_string</span> : <code class="type">string -> unit</code></pre><div class="info">
Signals a failure when the string is non-empty. The string identifies the
failure.<br>
<b>Raises</b> <code>Failure</code> signal a failure<br>
</div>
<pre><span id="VALassert_command"><span class="keyword">val</span> assert_command</span> : <code class="type">?exit_code:Unix.process_status -><br> ?sinput:char Stream.t -><br> ?foutput:(char Stream.t -> unit) -><br> ?use_stderr:bool -><br> ?backtrace:bool -><br> ?chdir:string -><br> ?env:string array -> ctxt:<a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> string -> string list -> unit</code></pre><div class="info">
<code class="code">assert_command prg args</code> Run the command provided.<br>
</div>
<div class="param_info"><code class="code">exit_code</code> : expected exit code</div>
<div class="param_info"><code class="code">sinput</code> : provide this <code class="code">char <span class="constructor">Stream</span>.t</code> as input of the process</div>
<div class="param_info"><code class="code">foutput</code> : run this function on output, it can contains an
<code class="code">assert_equal</code> to check it</div>
<div class="param_info"><code class="code">use_stderr</code> : redirect <code class="code">stderr</code> to <code class="code">stdout</code></div>
<div class="param_info"><code class="code">backtrace</code> : Set OCAMLRUNPARAM=b</div>
<div class="param_info"><code class="code">chdir</code> : Chdir into a directory before running the command.</div>
<div class="param_info"><code class="code">env</code> : Unix environment</div>
<pre><span id="VALassert_equal"><span class="keyword">val</span> assert_equal</span> : <code class="type">?ctxt:<a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -><br> ?cmp:('a -> 'a -> bool) -><br> ?printer:('a -> string) -><br> ?pp_diff:(Format.formatter -> 'a * 'a -> unit) -><br> ?msg:string -> 'a -> 'a -> unit</code></pre><div class="info">
<code class="code">assert_equal expected real</code> Compares two values, when they are not equal a
failure is signaled.<br>
<b>Raises</b> <code>Failure</code> signal a failure<br>
</div>
<div class="param_info"><code class="code">ctxt</code> : if provided, always print expected and real value</div>
<div class="param_info"><code class="code">cmp</code> : customize function to compare, default is <code class="code">=</code></div>
<div class="param_info"><code class="code">printer</code> : value printer, don't print value otherwise</div>
<div class="param_info"><code class="code">pp_diff</code> : if not equal, ask a custom display of the difference
using <code class="code">diff fmt exp real</code> where <code class="code">fmt</code> is the formatter to use</div>
<div class="param_info"><code class="code">msg</code> : custom message to identify the failure</div>
<pre><span id="VALassert_raises"><span class="keyword">val</span> assert_raises</span> : <code class="type">?msg:string -> exn -> (unit -> 'a) -> unit</code></pre><div class="info">
Asserts if the expected exception was raised.<br>
<b>Raises</b> <code>Failure</code> description<br>
</div>
<div class="param_info"><code class="code">msg</code> : identify the failure</div>
<br>
<span id="2_Skippingtests"><h2>Skipping tests </h2></span>
<p>
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.
<p>
A test skipped is counted as success. A test todo is counted as failure.<br>
<pre><span id="VALskip_if"><span class="keyword">val</span> skip_if</span> : <code class="type">bool -> string -> unit</code></pre><div class="info">
<code class="code">skip cond msg</code> If <code class="code">cond</code> is true, skip the test for the reason explain in
<code class="code">msg</code>. For example <code class="code">skip_if (<span class="constructor">Sys</span>.os_type = <span class="string">"Win32"</span>) <span class="string">"Test a doesn't run on
windows"</span></code>.<br>
</div>
<pre><span id="VALtodo"><span class="keyword">val</span> todo</span> : <code class="type">string -> unit</code></pre><div class="info">
The associated test is still to be done, for the reason given.<br>
</div>
<br>
<span id="2_CompareFunctions"><h2>Compare Functions</h2></span><br>
<pre><span id="VALcmp_float"><span class="keyword">val</span> cmp_float</span> : <code class="type">?epsilon:float -> float -> float -> bool</code></pre><div class="info">
Compare floats up to a given relative error.<br>
</div>
<div class="param_info"><code class="code">epsilon</code> : if the difference is smaller <code class="code">epsilon</code> values are equal</div>
<br>
<span id="2_Bracket"><h2>Bracket</h2></span>
<p>
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.<br>
<pre><span id="VALbracket"><span class="keyword">val</span> bracket</span> : <code class="type">(<a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> 'a) -><br> ('a -> <a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> unit) -> <a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> 'a</code></pre><div class="info">
<code class="code">bracket set_up tear_down test_ctxt</code> set up an object and register it to be
tore down in <code class="code">test_ctxt</code>.<br>
</div>
<pre><span id="VALbracket_tmpfile"><span class="keyword">val</span> bracket_tmpfile</span> : <code class="type">?prefix:string -><br> ?suffix:string -><br> ?mode:Pervasives.open_flag list -><br> <a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> string * Pervasives.out_channel</code></pre><div class="info">
<code class="code">bracket_tmpfile test_ctxt</code> Create a temporary filename and matching output
channel. The temporary file is removed after the test.<br>
</div>
<div class="param_info"><code class="code">prefix</code> : see <code class="code"><span class="constructor">Filename</span>.open_temp_file</code></div>
<div class="param_info"><code class="code">suffix</code> : see <code class="code"><span class="constructor">Filename</span>.open_temp_file</code></div>
<div class="param_info"><code class="code">mode</code> : see <code class="code"><span class="constructor">Filename</span>.open_temp_file</code></div>
<pre><span id="VALbracket_tmpdir"><span class="keyword">val</span> bracket_tmpdir</span> : <code class="type">?prefix:string -> ?suffix:string -> <a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> string</code></pre><div class="info">
<code class="code">bracket_tmpdir test_ctxt</code> Create a temporary dirname. The temporary
directory is removed after the test.<br>
</div>
<div class="param_info"><code class="code">prefix</code> : see <code class="code"><span class="constructor">Filename</span>.open_temp_file</code></div>
<div class="param_info"><code class="code">suffix</code> : see <code class="code"><span class="constructor">Filename</span>.open_temp_file</code></div>
<pre><span id="VALwith_bracket_chdir"><span class="keyword">val</span> with_bracket_chdir</span> : <code class="type"><a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> string -> (<a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> 'a) -> 'a</code></pre><div class="info">
<code class="code">with_bracket_chdir test_ctxt dn f</code> change directory to <code class="code">dn</code> during
execution of function <code class="code">f</code>. In order to <code class="code"><span class="constructor">Sys</span>.chdir</code>, 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.<br>
</div>
<br>
<span id="2_ConstructingTests"><h2>Constructing Tests</h2></span><br>
<pre><span id="VAL(>:)"><span class="keyword">val</span> (>:)</span> : <code class="type">string -> <a href="OUnit2.html#TYPEtest">test</a> -> <a href="OUnit2.html#TYPEtest">test</a></code></pre><div class="info">
Create a TestLabel for a test<br>
</div>
<pre><span id="VAL(>::)"><span class="keyword">val</span> (>::)</span> : <code class="type">string -> <a href="OUnit2.html#TYPEtest_fun">test_fun</a> -> <a href="OUnit2.html#TYPEtest">test</a></code></pre><div class="info">
Create a TestLabel for a TestCase<br>
</div>
<pre><span id="VAL(>:::)"><span class="keyword">val</span> (>:::)</span> : <code class="type">string -> <a href="OUnit2.html#TYPEtest">test</a> list -> <a href="OUnit2.html#TYPEtest">test</a></code></pre><div class="info">
Create a TestLabel for a TestList<br>
</div>
<pre><span id="VALtest_case"><span class="keyword">val</span> test_case</span> : <code class="type">?length:<a href="OUnit2.html#TYPEtest_length">test_length</a> -> <a href="OUnit2.html#TYPEtest_fun">test_fun</a> -> <a href="OUnit2.html#TYPEtest">test</a></code></pre><div class="info">
Generic function to create a test case.<br>
</div>
<pre><span id="VALtest_list"><span class="keyword">val</span> test_list</span> : <code class="type"><a href="OUnit2.html#TYPEtest">test</a> list -> <a href="OUnit2.html#TYPEtest">test</a></code></pre><div class="info">
Generic function to create a test list.<br>
</div>
<br>
Some shorthands which allows easy test construction.
<p>
Examples:
<p>
<ul>
<li><code class="code"><span class="string">"test1"</span> >: <span class="constructor">TestCase</span>((<span class="keyword">fun</span> _ <span class="keywordsign">-></span> ()))</code> =>
<code class="code"><span class="constructor">TestLabel</span>(<span class="string">"test2"</span>, <span class="constructor">TestCase</span>((<span class="keyword">fun</span> _ <span class="keywordsign">-></span> ())))</code></li>
<li><code class="code"><span class="string">"test2"</span> >:: (<span class="keyword">fun</span> _ <span class="keywordsign">-></span> ())</code> =>
<code class="code"><span class="constructor">TestLabel</span>(<span class="string">"test2"</span>, <span class="constructor">TestCase</span>((<span class="keyword">fun</span> _ <span class="keywordsign">-></span> ())))</code></li>
<li><code class="code"><span class="string">"test-suite"</span> >::: [<span class="string">"test2"</span> >:: (<span class="keyword">fun</span> _ <span class="keywordsign">-></span> ());]</code> =>
<code class="code"><span class="constructor">TestLabel</span>(<span class="string">"test-suite"</span>, <span class="constructor">TestSuite</span>([<span class="constructor">TestLabel</span>(<span class="string">"test2"</span>,
<span class="constructor">TestCase</span>((<span class="keyword">fun</span> _ <span class="keywordsign">-></span> ())))]))</code></li>
</ul>
<br>
<br>
<span id="2_PerformingTests"><h2>Performing Tests</h2></span><br>
<pre><span id="TYPElog_severity"><span class="keyword">type</span> <code class="type"></code>log_severity</span> = <code class="type">[ `Error | `Info | `Warning ]</code> </pre>
<div class="info">
Severity level for log.<br>
</div>
<pre><span id="VALlogf"><span class="keyword">val</span> logf</span> : <code class="type"><a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -><br> <a href="OUnit2.html#TYPElog_severity">log_severity</a> -> ('a, unit, string, unit) Pervasives.format4 -> 'a</code></pre><div class="info">
Log into OUnit logging system.<br>
</div>
<pre><span id="VALin_testdata_dir"><span class="keyword">val</span> in_testdata_dir</span> : <code class="type"><a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> string list -> string</code></pre><div class="info">
Build a filename for a file that should be located in the test data dir.
<p>
The test data dir, can be defined on the command line (preferably absolute)
The default option is to locate it in topsrcdir/test/data.<br>
</div>
<pre><span id="VALnon_fatal"><span class="keyword">val</span> non_fatal</span> : <code class="type"><a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> (<a href="OUnit2.html#TYPEtest_ctxt">test_ctxt</a> -> unit) -> unit</code></pre><div class="info">
<code class="code">non_fatal ctxt f</code> Run <code class="code">f</code> 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.<br>
</div>
<pre><span class="keyword">module</span> <a href="OUnit2.Conf.html">Conf</a>: <code class="code"><span class="keyword">sig</span></code> <a href="OUnit2.Conf.html">..</a> <code class="code"><span class="keyword">end</span></code></pre><div class="info">
Define command line options, environment variables and file configuration.
</div>
<pre><span id="VALrun_test_tt_main"><span class="keyword">val</span> run_test_tt_main</span> : <code class="type">?exit:(int -> unit) -> <a href="OUnit2.html#TYPEtest">test</a> -> unit</code></pre><div class="info">
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.<br>
</div>
</body></html>
