readme: clarify/extend few entries in 't/README'

* t/README (Writing test cases): Here.

Signed-off-by: Stefano Lattarini <stefano.lattarini@gmail.com>

diff --git a/t/README b/t/README
index 829b97ad548e53e6c2eb9467c3e38f4e7a85b6ea..3f56400f2fd8c354a0fb17a9f15fb781640d0118 100644 (file)
--- a/t/README
+++ b/t/README
@@ -143,7 +143,8 @@ Writing test cases
 
 * Add a copyright/license paragraph.
 
-* Explain what the test does.
+* Explain what the test does, i.e., which features it checks, which
+  invariants it verifies, or what bugs/issues it guard against.
 
 * Cite the PR number (if any), and the original reporter (if any), so
   we can find or ask for information if needed.
@@ -171,14 +172,15 @@ Writing test cases
   set-up of a test scenario, you can use the 'framework_fail_' function
   instead.
 
-* For those tests checking the Automake-provided test harnesses that are
-  expected to work also when the 'serial-tests' Automake option is used
-  (thus causing the serial testsuite harness to be used in the generated
-  Makefile), place a line containing "try-with-serial-tests" somewhere
-  in the file.  That will ensure that the 'gen-testsuite-part' script
-  generates a sibling of that test which uses the serial harness instead
-  of the parallel one.  For those tests that are *not* meant to work with
-  the parallel testsuite harness at all (these should be very very few),
+* For those tests checking the Automake-provided test harnesses that
+  are expected to work also when the 'serial-tests' Automake option
+  is used (thus causing the serial testsuite harness to be used in the
+  generated Makefile), place a line containing "try-with-serial-tests"
+  somewhere in the file (usually in a comment).
+  That will ensure that the 'gen-testsuite-part' script generates a
+  sibling of that test which uses the serial harness instead of the
+  parallel one.  For those tests that are *not* meant to work with the
+  parallel testsuite harness at all (these should be very very few),
   set the shell variable 'am_serial_tests' to "yes" before including
   ./defs.
 
@@ -206,18 +208,18 @@ Writing test cases
   disable the errexit flag (but please do so only if you have a very
   good reason).
 
-* End the test script with a ":" or "Exit 0".  Otherwise, when somebody
+* End the test script with a ':' command.  Otherwise, when somebody
   changes the test by adding a failing command after the last command,
-  the test will spuriously fail because $? is nonzero at the end.  Note
-  that this is relevant even if the errexit shell flag is on, in case
-  the test contains commands like "grep ... Makefile.in && Exit 1" (and
-  there are indeed a lot of such tests).
+  the test will spuriously fail because '$?' is nonzero at the end.
+  Note that this is relevant even if the errexit shell flag is on, in
+  case the test contains commands like "grep ... Makefile.in && Exit 1"
+  (and there are indeed a lot of such tests).
 
 * Use $ACLOCAL, $AUTOMAKE, $AUTOCONF, $AUTOUPDATE, $AUTOHEADER,
   $PERL, $MAKE, $EGREP, and $FGREP, instead of the corresponding
   commands.
 
-* Use $sleep when you have to make sure that some file is newer
+* Use '$sleep' when you have to make sure that some file is newer
   than another.
 
 * Use cat or grep or similar commands to display (part of) files that