update test.py documentation
authorCraig Dowell <craigdo@ee.washington.edu>
Tue, 06 Oct 2009 22:47:07 -0700
changeset 5371 6020e8d86ffa
parent 5370 a27163124701
child 5372 716ca842b52c
update test.py documentation
doc/testing/testing-framework.texi
test.py
--- a/doc/testing/testing-framework.texi	Tue Oct 06 22:01:40 2009 -0700
+++ b/doc/testing/testing-framework.texi	Tue Oct 06 22:47:07 2009 -0700
@@ -216,15 +216,16 @@
   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 @@
   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 @@
 
 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
--- a/test.py	Tue Oct 06 22:01:40 2009 -0700
+++ b/test.py	Tue Oct 06 22:47:07 2009 -0700
@@ -745,7 +745,7 @@
     # 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: