From 104b676108da653d8a17266bc5d08f9f5546536d Mon Sep 17 00:00:00 2001
From: Craig Dowell <craigdo@ee.washington.edu>
Date: Tue, 6 Oct 2009 22:47:07 -0700
Subject: [PATCH] update test.py documentation

---
 doc/testing/testing-framework.texi | 53 +++++++++++++++++++++++++-----
 test.py                            |  2 +-
 2 files changed, 46 insertions(+), 9 deletions(-)

diff --git a/doc/testing/testing-framework.texi b/doc/testing/testing-framework.texi
index 4e20905e4..ce954331b 100644
--- a/doc/testing/testing-framework.texi
+++ b/doc/testing/testing-framework.texi
@@ -216,15 +216,16 @@ will result in the following list being displayed:
   Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
   'build' finished successfully (0.939s)Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
   bvt:         Build Verification Tests (to see if build completed successfully)
-  unit:        Unit Tests (within modules to check basic functionality)
-  system:      System Tests (spans modules to check integration of modules)
+  core:        Run all TestSuite-based tests (exclude examples)
   example:     Examples (to see if example programs run successfully)
   performance: Performance Tests (check to see if the system is as fast as expected)
+  system:      System Tests (spans modules to check integration of modules)
+  unit:        Unit Tests (within modules to check basic functionality)
 @end verbatim
 @end smallformat
 
-This list is displayed in increasing order of complexity of the tests.  Any of these
-kinds of test can be provided as a constraint using the @code{--constraint} option.
+Any of these kinds of test can be provided as a constraint using the @code{--constraint} 
+option.
 
 To see a quick list of all of the test suites available, you can ask for them
 to be listed.  The following command,
@@ -240,12 +241,23 @@ will result in a list of the test suite being displayed, similar to :
   Waf: Entering directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
   Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone-test/ns-3-dev/build'
   'build' finished successfully (0.939s)
-  ns3-wifi-propagation-loss-models
+  histogram
+  ns3-wifi-interference
   ns3-tcp-cwnd
   ns3-tcp-interoperability
-  pcap-file-object
+  sample
+  devices-mesh-flame
+  devices-mesh-dot11s
+  devices-mesh
+  ...
   object-name-service
-  random-number-generators
+  callback
+  attributes
+  config
+  global-value
+  command-line
+  basic-random-number
+  object
 @end verbatim
 @end smallformat
 
@@ -301,9 +313,34 @@ will result in a list of the currently built test suites being displayed, simila
 
 Note the absence of the @command{Waf} build messages.
 
+@code{test.py} also supports running the test suites and examples under valgrind.
+Valgrind is a flexible program for debugging and profiling Linux executables.  By
+default, valgrind runs a tool called memcheck, which performs a range of memory-
+checking functions, including detecting accesses to uninitialised memory, misuse 
+of allocated memory (double frees, access after free, etc.) and detecting memory 
+leaks.  This can be selected by using the @code{--grind} option.
+
+@verbatim
+  ./test.py --grind
+@end verbatim
+
 Finally, @code{test.py} provides a @command{--verbose} option which will print
 large amounts of information about its progress.  It is not expected that this
-will be terribly useful for most users.
+will be terribly useful unless there is an error.  In this case, you can get
+access to the standard output and standard error reported by running test suites
+and examples.  Select verbose in the following way:
+
+@verbatim
+  ./test.py --verbose
+@end verbatim
+
+All of these options can be mixed and matched.  For example, to run all of the 
+ns-3 core test suites under valgrind, in verbose mode, while generating an HTML
+output file, one would do:
+
+@verbatim
+  ./test.py --verbose --grind --constrain=core --html=results.html 
+@end verbatim
 
 @node TestTaxonomy
 @section Test Taxonomy
diff --git a/test.py b/test.py
index 2dfca1665..accacd289 100755
--- a/test.py
+++ b/test.py
@@ -745,7 +745,7 @@ def run_tests():
     # handle them without doing all of the hard work.
     #
     if options.kinds:
-        (rc, standard_out, standard_err) = run_job_synchronously("utils/test-runner --kinds", os.getcwd(). False)
+        (rc, standard_out, standard_err) = run_job_synchronously("utils/test-runner --kinds", os.getcwd(), False)
         print standard_out
 
     if options.list: