# Mode: -*- readme-debian -*-

FeelV Testing Framework
-----------------------

The FeelV testing framework uses AutoTest from autoconf. The latter
is the configuration system of FeelV.

AutoTest uses the same underlying scripting preprocessor m4. It provides
a few marcos that allows to define tests, test groups, data for the tests
and a keyword system to allow running only tests that are tagged with a
particular keyword.

Prerequisites
-------------

* The feelv libraries have been compiled using the autoconf/automake/libtool
  framework. It is not explained here how to compile the libraries.

* Read the section regarding AutoTest in the autoconf manual.

How to run the testsuite
------------------------

* using 'make'

type:

  make check           # ensures that all tests are compiled
  make check-testsuite # runs the testsuite 

* using the 'testsuite' script

make sure that the 'testsuite' exists, type:

  cd testsuite
  make testsuite # the script is stored in $(srcdir)

then execute the 'testsuite' script, type:

  cd testsuite # in the build directory
  <path to top_srcdir>/testsuite/testsuite # execute the scripts

* run only a group of tests based on keywords

say that you want to run all tests regarding naviar-stokes(ns)

  <path to top_srcdir>/testsuite/testsuite -k ns

Note: some of the keywords were generated using the name of the tests
      for example test_ns_bdf will be executed with both the keywords
      'ns' and 'bdf'

How to create a test for the testsuite
--------------------------------------

There are already a lot of tests in the testsuite, so you
should have a look and copy the behaviour.

Say that you want to create the 'foo' test

 1- create a directory test_foo
 2- create test_foo/Makefile.am
 3- create test_foo/test_foo.cpp # contains the main function
 4- create test_foo/*.{cpp|hpp} that could be needed for the 'foo' test
 5- create test_foo/data if needed # GetPot data file
 6- create test_foo/testsuite.at

    test_foo/testsuite.at should look like this

   AT_SETUP([test_foo])
   AT_KEYWORDS([test_foo foo])
   AT_DATA([data],[[
   # put here the data file for the test
   [./discretization]
   mesh_dir    = ./ # the directory where the mesh file is
   mesh_file   = foo.mesh
   post_dir = ./    # the directory for postprocessing files

   ]])
   AT_CHECK([ln -sf $top_builddir/testsuite/data/mesh/inria/foo.mesh
             && $top_builddir/testsuite/test_foo/test_foo],[0],
            [put here the expected standard output],
            [put here the expected standard error output])
   AT_CLEANUP([put here any files that were created by the test])

 7- edit testsuite/testsuite.at to add the new into its proper category
    follow what has been done for the other tests.
 8- make sure to regenerate the 'testsuite' script (see previous section)
 9- run all the tests(see previous section) and go drink a coffee/beer
10- check that everything went fine

11- In case of problems in the automatic testing:
    Look at testsuite/testsuite.log file
    Go in the testsuite/testsuite.dir directory :
    all failed tests are listed in directories, according to their number.
    Let's say that toto has the number 42
    cd testsuite/testsuite.dir/42
    Explore the problems!
    Known problems:
    a) check that your meshes are correctly treated (the symbolic
    link must exist in testsuite.dir/42)
    b) check that you don't read your mesh in a "../data/mesh/inria/"
    directory: it does NOT exist in testsuite.dir/42!! Check
    "AT_DATA([data],...)".
    c) check that you don't write result files in a "./Post" directory that
    does NOT exist! Advice: in the "AT_DATA([data],...)" of testsuite.at, DO
    NOT use "./Post" directories but "./" directory to write results files.
    d) ...?

 -- Christophe Prud'homme <prudhomm@debian.org>, Thu Jan 12 15:58:33 2006