Unit test directory for CLMBuildNamelist.pm
-------------------------------------------

The goal of the unit test suite for build namelist is to have machine
independent tests that will run anywhere in seconds and have high
coverage of the critical decision making code.

Running
=======

To run the unit tests for CLMBuildNamelist.pm:

$ prove test_build_namelist.pl 

The test output has been optimized to most useful when run through
prove (a standard part of all modern perl distributions). Developers
who prefer standard Test::More output can run the tests by running the
script:

$ ./test_build_namelist.pl


Creating New Tests
==================

To create a new test suite, copy the file:

t/template_test_XXX.pm 

to t/test_what_you_want_to_test.pm

Note: the contents of template_test_XXX.pm are valid tests and are
part of the test suite. This file should always be valid.

New test files are picked up automatically by test_build_namelist.pl.

Inside the new test module:

* WWW, XXX, YYY, ZZZ are used as place holder text for things that
  need to be replaced.

* startup and shutdown - common fixtures for all tests. These methods
  are only called once for each suite. The objects in these functions
  should NOT BE MODIFIED by any tests, e.g. config_cache,
  namelist_definition.xml, namelist_defaults.xml

* setup and teardown - common fixtures for all tests. These methods
  are called once for each test. Objects that ARE MODIFIED should be
  created here. For example, the namelist object should be created
  here so each test starts with a clean object.

* Tests are automatically detected by functions starting with
  'test_'. The proposed naming conventions are 'test_XXX__YYY' where
  XXX is the function or namelist variable being tested. YYY is a
  descriptor of the branch (if phys==clm4_5) or condition being
  tested. This will make the failure output more useful.

* To create each test, simply create a minimal opts and nl_flags hash
  and pass them into the function you want to test, then check the results.

* Multiple tests can be placed in each function (including loops), but
  this make it harder to what failed and why. By using one test per
  test function, the failure messages will be more useful.

* Rather than describing the test in comments, it should be described
  in the message string. The message string should be printed to the
  screen when the test fails with "... || diag($msg)". This provides a
  useful failure message without duplicating information comments that
  will become out of date.

* To keep the tests machine independent, we don't want to require the
  presence of the cesm input data repository. To meet this requirement
  but still allow for testing of key functionality, modify or add new
  mock xml files in t/input to point to mock files in the source
  tree. Since build-namelist will not be reading netcdf data files,
  mocks can be empty text files.


CPAN modules
============

The perl5lib directory contains the following modules from CPAN:

 * Test-Class-0.41 - test class that provides startup and shutdown methods
 * Test-Exception-0.32 - allow testing for exceptions, e.g. tests that should die
 * MRO-Compat-0.12 - dependency
 * Sub-Uplevel-0.24 - dependency

All modules were licensed under the same license as perl (Artistic
License or GNU GPL). As of 2014-03-17 see:

http://search.cpan.org/~rjbs/Test-Class-0.41/lib/Test/Class.pm
http://search.cpan.org/~adie/Test-Exception-0.32/lib/Test/Exception.pm
http://search.cpan.org/~bobtfish/MRO-Compat-0.12/lib/MRO/Compat.pm
http://search.cpan.org/~dagolden/Sub-Uplevel-0.24/lib/Sub/Uplevel.pm



