Usage

• Usage - Configuration
• Usage - Hello World
• Usage - Preprocessor
• Compiling and Executing The Test

Usage

Usage - Configuration

For regular use, after installation, the same compiler/MPI development configuration that was used to build pFUnit should be used. Once the environment variables and paths associated with the environment are set, to configure pFUnit, please set the following.

PFUNIT - set to the directory into which pFUnit was installed.

F90_VENDOR - set to Intel, GNU, NAG, or PGI accordingly.

Usage - Hello World

For an example of a simple usage of pFUnit, see Examples/Simple/tests.

The simplest way to write a test is to write a preprocessor input file (extension ".pf"), which is a Fortran free format file with preprocessor directives added. An example from "helloWorld.pf" follows.

! from helloWorld.pf
@test
subroutine testHelloWorld()
   use pfunit_mod
   implicit none
   @assertEqual("Hello World!","Hello World!")
end subroutine testHelloWorld

One then instructs the preprocessor to construct a suite to execute these tests via the "testSuites.inc" file as follows.

! from testSuites.inc
ADD_TEST_SUITE(helloWorld_suite)

At this point, one can invoke the preprocessor to generate a Fortran file that when compiled and linked with pFUnit will execute the tests. For more information please see The Preprocessor - pFUnitParser or try out the examples in Example/Simple.

Usage - Preprocessor

Please see The Preprocessor - pFUnitParser.

Compiling and Executing The Test

An example of a GNU make rule for for the final step of compiling a test follows.

# This step presumes "include $(PFUNIT)/include/base.mk" earlier in the makefile.
tests.x: testSuites.inc myTests.pf
         $(F90) -o $@ -I$(PFUNIT)/mod -I$(PFUNIT)/include \
                $(PFUNIT)/include/driver.F90 \
                ./*$(OBJ_EXT) $(LIBS) $(FFLAGS)

To execute the tests, one invokes "./tests.x" with the appropriate command line options (see below).

In some cases, since include/driver.F90 is "implicit none," it may be necessary to insert a "use" clause to identify external suite-wide fixture code to the compiler. As a convenience, the CPP macro PFUNIT_EXTRA_USAGE can be set to a module of fixture code via a compiler command line argument turning on a "use PFUNIT_EXTRA_USAGE" line at the beginning of include/driver.F90.

- Compiling and Executing the Tests (MPI PARALLEL)

One invokes MPI-based parallel tests according to the MPI framework being used. For example:

$ mpirun -np 4 tests.x

Command Line Options

The executable test program provides several command line options, when "include/driver.F90" is used, as it is automatically when using the PFUNIT preprocessor.

-v or -verbose	Verbose execution.
-d or -debug	Provide debugging information.
-h	Print help message.
-o <outputfile>	Direct pFUnit messages to a file.
-robust	Use the robust runner. Runs tests as processes so failures do not halt testing.
-max-timeout-duration <duration> Limit detection time for robust runner.
-max-launch-duration <duration> Limit detection time for robust runner.
-skip <number of tests to skip>	Use the subset runner, which runs a subset of the tests in a suite.
-xml <xmlfile>	Generate XML output in JUnit compatible format, write it to given file. This XML output can be used in integration with e.g. Jenkins. To ensure the XML file is written correctly, it is recommended to also use the -robust flag.
-name <name>	Give the set of tests an identifying name, which is used in the XML output.

An example from Examples/Robust:

$ ./tests.x -robust

XML output

To output JUnit XML, execute tests with the -xml flag:

$ ./tests.x -robust -xml test.xml -name my_suite_name

This creates a file named test.xml. As an example, the output may look like this:

<testsuite name="my_suite_name" errors="1" failures="1" tests="3" time="2.1020">
<testcase name="test_math_suite.test_addition"/>
<testcase name="test_math_suite.test_division">
<error message="Location: [[unknown location]], RUNTIME-ERROR: terminated during execution "/>
</testcase>
<testcase name="test_other_suite.test_foo">
<failure message="Location: [ test_other.pf:24],  "/>
</testcase>
</testsuite>

Output explained: The test suite took 2.1020 seconds to execute. One test (test_addition) succeeded, one (test_division) crashed for some reason, and one test (test_foo) failed at line 24 of test_other.pf.