Unit Tests

For the unit testing of ug4 the Boost Testing Library is used. The test are run by the Continuous Integration Service "Jenkins" (currently on cave1.gcsc.uni-frankfurt.de) daily. If a test fails reporting email will be sent to the causing developers.

Unit Tests can be carried out in two ways:

• Testing Code
• Testing Scripts

For any questions, contact marti.nosp@m.n.sc.nosp@m.herer.nosp@m.@gcs.nosp@m.c.uni.nosp@m.-fra.nosp@m.nkfur.nosp@m.t.de or andre.nosp@m.as.v.nosp@m.ogel@.nosp@m.gcsc.nosp@m..uni-.nosp@m.fran.nosp@m.kfurt.nosp@m..de.

---

Testing Code

In order to test the C++-Code directly one can write a piece of code, that is tested automatically. All unit test code should be placed in unit_tests/src/*.cpp.

If you want to test your own code, add a *.cpp file in that section and add your file in the CMakeList.txt file.

Then start your own test suite as shown by this self-explanatory example:

// register test suite
BOOST_AUTO_TEST_SUITE(myNameSuiteNumProc1);
 
// add a test
BOOST_AUTO_TEST_CASE(myTest)
{
  int a = 1, b = 2;
 
  // write a message
  BOOST_MESSAGE("Starting some test")
  
  // check 
  BOOST_CHECK_MESSAGE(a+b == 3, "1+2 must be 3");
  BOOST_REQUIRE_MESSAGE(a+b == 3, "1+2 must be 3");
}
 
// end of test suite
BOOST_AUTO_TEST_SUITE_END();

In Detail:

A test suite is used to group several test together and all test suits will be detected and tested. BOOST_AUTO_TEST_SUITE starts a new test suite, that is ended by BOOST_AUTO_TEST_SUITE_END. The name of suite must be a valid C++-Name.

Note

The Ending of a Suite must be (by our convention) *NumProcsXX, where XX is the number of processes the suite should be run with (i.e. MPI-Processes).

BOOST_AUTO_TEST_CASE defines a test. There can be as many test cases in a suite as you like. Using the macros BOOST_REQUIRE_MESSAGE, BOOST_CHECK_MESSAGE you can now assert several conditions in your code.

---

Testing Scripts

In order to test Lua-Scripts you just have to add the script, that you want to test in the file unit_tests/data/script_tests/{script_test_param.xml, experimental_plugin.xml}. The file name depends on whether you are testing a script which depends on a core or an experimental plugin.

See this example:

<script>
  <path>conv_diff/laplace_test.lua</path>
  <!-- on how many processors test this script with all its configurations -->
  <numProcs>1 3 4 7</numProcs>
  <!-- every config element leads to a separate test case.
    nested configs will inherit parameters sets from parent
   -->
  <config-set>
    <config>
      <!-- Default config => all nested configs will inherit these parameters.
        Configs may be nested recursively. -->
      <parameters>
        <param name="-numRefs">2</param>
        <!-- -distType : possible values => [grid2d | bisect | metis] -->
        <param name="-distType">grid2d</param>
        <!-- timeout of 6 seconds -->
        <param name="timeout">12</param>
      </parameters>
      
      <config>
        <parameters>
          <param name="-dim">1</param>
          <!-- todo test other dist types for all dimension -->
        </parameters>
      </config>
      
      <config>
        <parameters>
          <param name="-dim">2</param>
        </parameters>
      </config>
      
      <config>
        <parameters>
          <param name="-dim">3</param>
        </parameters>
      </config>
    </config>
  </config-set>
</script>

If you want to add your plugin to the Jenkins automated test procedure, add a line -DMyPlugin=ON to the cmake build step section of the Job "ug-build-plugins" and add a <script> ... </script> section to the experimental_plugin.xml file. It is recommended to ensure your script file is able to be executed outside of UG4_ROOT (e.g grids should be not be loaded via absolute path or relative one relying to an unknown runtime location)

Now, two things are tested for each script configuration:

1. In any case the successful run of the script (i.e. no UGError/LuaError/... reported) exception
2. In your script you can add additional requirements and tests as shown in the example below.

In your script use the functions test.require(cond, "message") and test.check(cond,"message") to ensure conditions during the run of the script. Please note, that this functions are available when ug_util.lua is included in your script and that — if no Boost is available — the test functions are replaced by dummy methods (see scripts/util/test_utils.lua). An example:

-- Create, Load, Refine and Distribute Domain
neededSubsets = {"Inner", "Boundary"}
dom = util.CreateAndDistributeDomain(gridName, numRefs, numPreRefs, neededSubsets)
test.require(dom ~= nil, "Domain loaded.")
 
-- create Approximation Space
approxSpace = ApproximationSpace(dom)
approxSpace:add_fct("c", "Lagrange", 1)
approxSpace:print_statistic()
 
-- lets order indices using Cuthill-McKee
OrderCuthillMcKee(approxSpace, true);