TESTING.md

   1 # Unit Testing
   2
   3 FMS includes a suite of MPI unit tests using the testing infrastructure included in the GNU autotools build system
   4 in order to check the functionality of the library's modules.
   5
   6 It consists of programs in the test_fms/ directory, with shell scripts to handle directory set up and input files.
   7 test_lib.sh.in and tap-driver.sh provide additional helper functions used in the scripts and manage output.
   8
   9 ### Running the Tests
  10
  11 1. Configure with autotools
  12 ```
  13 mkdir build # create a build directory in FMS
  14 autoreconf -if ../configure.ac
  15 ../configure <configure options>
  16 ```
  17
  18 2. Build and run suite
  19 ```
  20 make check
  21 ```
  22 This will compile any code not already compiled and then proceed to run the test scripts.
  23
  24 ### Debugging Output and Test Options
  25
  26 Setting the environment variable TEST_VERBOSE will direct output to stdout as the test runs, while setting VERBOSE will only output on failure.
  27 Logs are created for each test as well, with the name \<test script name\>.log in it's corresponding test_fms/ directory.
  28
  29 To run an individual test:
  30 ```
  31 make check -C test_fms/<test directory> TESTS=<test script name>
  32 ```
  33
  34 SKIP_TESTS can be set to in order to skip specific tests in a script. It uses the script name and test number, and takes ranges as well:
  35 ```
  36 SKIP_TESTS="test_name.4 test_name.[1-3]"
  37 ```
  38
  39 Some options that effect the test suite can be set by passing options to the ./configure script that creates the makefiles
  40 for the build system:
  41
  42 -    `--enable-code-coverage` allows for compilation with flags for coverage information.
  43      If enabled a coverage report can be generated with `make check-code-coverage`
  44 -    `--enable-test-input=/path/to/input` turns on test scripts that require input netcdf files (interpolator, xgrid, data_override).
  45      This option is mainly used internally and in automated testing since we do not host the input data publicly.
  46 -    `--with-yaml` compile with yaml input and enable it's associated tests