%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% $Id: testUnit.tex,v 1.1.1.1 2004/10/04 17:25:13 nthiery Exp $
% File:		lib/PROG/DOC/testUnit.tex
% Authors:	Nicolas M. Thiéry <nthiery@users.sourceforge.net>
% Purpose:	Documentation for the domain prog::testUnit
% Created:	Thu Apr 29 09:31:47 2004
% License:	LGPL
% Project:	MuPAD-Combinat, http://mupad-combinat.sf.net
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\begin{Mhelppage}{testUnit}{Nicolas M. Thiéry}
  [ImplState=beta,TestState=beta,DocState=beta]
%\Mproofread{user}{date}{comment}

\begin{MInfo}
  \eng{xUnit-style extensions to the \mupad{} test framework}
  \de{}
\end{MInfo}

\begin{MIntro}
  \eng{\Mthis{} provides xUnit-style extensions to the \mupad{} test framework.}
  \de{}
\end{MIntro}

\begin{MMethodDetails}{runTests}
  \infoEng{runs the test}
  \call{x}
  \eng{Try to runs the tests corresponding to the \mupad{} object \Mpar{x}.}
\end{MMethodDetails}

\begin{MDetails}
  \eng{The purpose of this library is to support test-driven
    programming, and in general to help the developer analyzing
    quickly failing tests. To this end, it provides tools to run tests
    from the test suite from an interactive \mupad{} session,
    typically within the debugger. Ultimately one would want to be
    able to run each tests or section of test individually, as in the
    \href{xUnit}{http://www.xunit.org/} world. }
  
  \eng{This library is designed to work as much as possible with a
    standard \mupad{} test file. However it works best if the test
    file is designed with individual testing in mind and gives some
    extra hints to the framework. }
\end{MDetails}

Here is a typical test file for a domain \Mex{tric::trac}. Following the
standard \mupad{} package layout it would reside in the file
"lib/TRIC/trac.tst".

\begin{Mvin}{test=false}
export(prog::testUnit, Alias):

////////////////////////////////////////////////////////////
testinit("trac"):

// Global setup for all the tests
export(tric, Alias, trac):
export(combinat, Alias, partitions):

////////////////////////////////////////////////////////////
testfunc(tric::trac::f):

test(f(1), 2):
test(f(2), 2):
test(f(3), 2):

////////////////////////////////////////////////////////////
testfunc("tric::trac::f with option Bla"):

test(f(1, Bla), 2):
...

////////////////////////////////////////////////////////////
testfunc(tric::trac::g):

// extra setup for the tests in this section
...

test(g(1), 2):
...

// extra cleanup for the tests in this section
...

////////////////////////////////////////////////////////////
testexit():
prog::check(tric::trac, 3):
// Clean up common to all the tests
\end{Mvin}{test=false}
\begin{Mvout}{test=false, hide=true}
\end{Mvout}

Note that this is perfectly compatible with the \mupad{} standard test
files: if the setup or \Mex{tear_down} functions are not defined, the
code inside will be safely executed, and the function call ignored.

The goal of the library is to allow for the following:
\begin{Mvin}{test=false}
  // runs all the tests:
  prog::testUnit::runTests(tric::trac);

  // runs all the tests concerning f, while
  // skipping the execution of all code in the setup,
  // test, or tear_down calls of other sections:
  prog::testUnit::runTests(tric::trac::f);

  // runs only the tests in the section "tric::trac::f"
  prog::testUnit::runTests("tric::trac::f");

  // runs only the tests in the section "tric::trac::f with option Bla":
  prog::testUnit::runTests("tric::trac::f with option Bla");

  // runs the setup code required for section "tric::trac::g"
  prog::testUnit::setupTest("tric::trac::g")
  // execute some tests of this section manually
  debug(g(1))
\end{Mvin}
\begin{Mvout}{test=false, hide=true}
\end{Mvout}

This is essentially compatible with standard \mupad{} test files. Of
course, there is no guarantee that running tests in individual
sections will work.  Same thing if there are interdependency between
sections. Just use your common sense.

So far, running individual tests is not yet implemented. While running
the tests, \Mup{prog::test} is temporarily modified so as not to trap
errors; this is helpful to analyze those errors with the debugger.

\begin{MChanges}
  \version{3.1}
  \eng[New domain]{\Mthis{} is a new domain} %
\end{MChanges}

\end{Mhelppage}
