Add cookbook for ModulesTest.

NEWS.rst

@@ -158,6 +158,8 @@ Modules 4.3.0 (2019-XX-XX)
   superseded with the ``MODULES_SET_SHELL_STARTUP`` environment variable, that
   could be set with ``config`` module sub-command through the
   ``set_shell_startup`` option.
+* Cookbook: add the *test-modulefiles* recipe. (fix issue #182 with
+  contribution from Colin Marquardt)
 
 
 Modules 4.2.4 (2019-04-26)

doc/example/test-modulefiles/modulefiles/test_dir_and_file

@@ -0,0 +1,39 @@
+#%Module1.0 # -*- mode: tcl; -*-
+
+proc ModulesTest { } {
+    set retcode 1  ;# default: 1 meaning PASS
+
+    puts stderr "Running ModulesTest for directory existence..."
+    if { [file isdirectory $::env(TESTDIR)] } {
+        puts stderr "Is a directory: $::env(TESTDIR)"
+    } else {
+        puts stderr "ERROR: Is not a directory: $::env(TESTDIR)"
+        set retcode 0
+    }
+    puts stderr "Running ModulesTest for directory existence...done"
+
+    puts stderr "Running ModulesTest for directory permissions..."
+    set cmd { cd $::env(TESTDIR) }
+    if { [catch $cmd errmsg] } {
+        puts stderr "ERROR: Was not able to enter directory $::env(TESTDIR): ${errmsg}"
+        set retcode 0
+    } else {
+        puts stderr "Was able to enter directory $::env(TESTDIR)"
+    }
+    puts stderr "Running ModulesTest for directory permissions...done"
+
+    puts stderr "Running ModulesTest for file creation..."
+    set cmd { open $::env(TESTFILE) w }
+    if { [catch $cmd errmsg] } {
+        puts stderr "ERROR: Was not able to create file $::env(TESTFILE): ${errmsg}"
+        set retcode 0
+    } else {
+        puts stderr "Was able to create file $::env(TESTFILE)"
+    }
+    puts stderr "Running ModulesTest for file creation...done"
+
+    return ${retcode}
+}
+
+setenv TESTDIR  /tmp/$::env(USER)/testdir
+setenv TESTFILE $::env(TESTDIR)/testfile

doc/source/cookbook/test-modulefiles.rst

@@ -0,0 +1,58 @@
+.. _test-modulefiles:
+
+Testing Modulefiles
+===================
+
+The following is an example for a ``ModulesTest`` proc of a Modulefile and its output.
+It checks whether the ``TESTDIR`` is a directory, checks that it can enter it,
+and whether a file ``TESTFILE`` can successfully be created there.
+
+This code gets executed when you use the ``test`` command.
+
+Code
+----
+
+.. literalinclude:: ../../example/test-modulefiles/modulefiles/test_dir_and_file
+   :caption: test_dir_and_file
+
+
+Usage example
+-------------
+
+Enable the modulepath where the example modulefiles are located::
+
+   $ module use example/test-modulefiles/modulefiles
+
+Run the test both with the test directory not existing and existing::
+
+    $ module test test_dir_and_file
+    -------------------------------------------------------------------
+    Module Specific Test for .../modulefiles/test_dir_and_file:
+
+    Running ModulesTest for directory existence...
+    ERROR: Is not a directory: /tmp/testuser/testdir
+    Running ModulesTest for directory existence...done
+    Running ModulesTest for directory permissions...
+    ERROR: Was not able to enter directory /tmp/testuser/testdir: couldn't change working directory to "/tmp/testuser/testdir": no such file or directory
+    Running ModulesTest for directory permissions...done
+    Running ModulesTest for file creation...
+    ERROR: Was not able to create file /tmp/testuser/testdir/testfile: couldn't open "/tmp/testuser/testdir/testfile": no such file or directory
+    Running ModulesTest for file creation...done
+    Test result: FAIL
+    -------------------------------------------------------------------
+    $ mkdir /tmp/$USER/testdir
+    $ module test test_dir_and_file
+    -------------------------------------------------------------------
+    Module Specific Test for .../modulefiles/test_dir_and_file:
+
+    Running ModulesTest for directory existence...
+    Is a directory: /tmp/testuser/testdir
+    Running ModulesTest for directory existence...done
+    Running ModulesTest for directory permissions...
+    Was able to enter directory /tmp/testuser/testdir
+    Running ModulesTest for directory permissions...done
+    Running ModulesTest for file creation...
+    Was able to create file /tmp/testuser/testdir/testfile
+    Running ModulesTest for file creation...done
+    Test result: PASS
+    -------------------------------------------------------------------