Adding documentation to the "test" script

git-svn-id: https://reductivelabs.com/svn/puppet/trunk@2713 980ebf18-57e1-0310-9a29-db15c13687c0

1 files changed, 110 insertions, 38 deletions

diff --git a/test/test b/test/test
index 172625b41..a8efd50bc 100755
--- a/test/test
+++ b/test/test
@@ -1,14 +1,111 @@
 #!/usr/bin/env ruby
 
-#------------------------------------------------------------
-# Run any or all test suites.  This script is different from
-# the Rakefile because it allows one to run one or more individual test methods
-# easily.
+#
+# = Synopsis
+#
+# Run unit tests, usually with the goal of resolving some conflict
+# between tests.
+#
+# = Usage
+#
+#   test [-d|--debug] [-f|--files] [-h|--help] [-n method] [-v|--verbose] <file> [file] ...
+#
+# = Description
+#
+# This script is useful for running a specific subset of unit tests, especially
+# when attempting to find a conflict between tests.  By default, it will take
+# the first argument you pass it and run that test or test directory with each
+# test directory in turn, looking for a failure.  If any tests fail, then
+# the script will drill into that test directory, looking for the specific conflict.
+#
+# In this way, when you have deduced you have two conflicting unit tests (tests which
+# pass in isolation but fail when run together), you can tell this script where
+# the failure is and leave it alone to find the conflict.
+#
+# This script is different from the Rakefile because it will run all tests in
+# a single process, whereas if you ask the Rakefile to run multiple tests, it will
+# run them in separate processes thus making it impossible to find conflicts.
+#
+# = Examples
+#
+# Attempt to resolve a conflict between a single test suite that could be anywhere:
+#
+#   ./test ral/providers/user.rb
+#
+# Determine whether two individual files conflict:
+#
+#   ./test --files language/functions.rb ral/providers/provider.rb
+#
+# Run the same test, but only run a specific unit test:
+#
+#   ./test -d -n test_search --files language/functions.rb ral/providers/provider.rb
+#
+# = Options
+#
+# debug::
+#   Enable full debugging.
+#
+# files::
+#   Specify exactly which files to test.
+#
+# help::
+#   Print this help message
+#
+# n::
+#   Specify a single unit test to run.  You can still specify as many files
+#   as you want.
+#
+# verbose::
+#   Print extra information.
+#
+# = Example
+#
+#   puppet -l /tmp/script.log script.pp
+#
+# = Author
+#
+# Luke Kanies
+#
+# = Copyright
+#
+# Copyright (c) 2005 Reductive Labs, LLC
+# Licensed under the GNU Public License
 
 require 'find'
 require 'getoptlong'
 include Find
 
+result = GetoptLong.new(
+    [ "--debug",	"-d",			GetoptLong::NO_ARGUMENT ],
+    [ "--verbose",	"-v",			GetoptLong::NO_ARGUMENT ],
+    [ "-n",			                GetoptLong::REQUIRED_ARGUMENT ],
+    [ "--files",    "-f",           GetoptLong::NO_ARGUMENT ],
+    [ "--help",		"-h",			GetoptLong::NO_ARGUMENT ]
+)
+
+usage = "USAGE: %s [--help] suite" % $0
+
+$options = {}
+keep = []
+
+result.each { |opt,arg|
+    case opt
+    when "--verbose"
+        $options[:verbose] = true
+    when "--files"
+        $options[:files] = true
+    when "--debug"
+        $options[:debug] = true
+        $options[:verbose] = true
+    when "--help"
+        puts usage
+        exit
+    else
+        keep << opt
+        keep << arg if arg
+    end
+}
+
 def dirs
     Dir.glob("*").find_all { |d| FileTest.directory?(d) }.reject { |d|
         ["lib", "data"].include?(d)
@@ -31,6 +128,15 @@ end
 def resolve(dir)
     dirs = dirs()
 
+    # If the passed dir is a subdir or file, put the basedir last
+    if dir.include?(File::SEPARATOR)
+        basedir = dir.split(File::SEPARATOR)[0]
+        if dirs.include?(basedir)
+            dirs.delete(basedir) 
+            dirs << basedir
+        end
+    end
+
     failed = nil
     dirs.each do |d|
         next if d == dir
@@ -104,40 +210,6 @@ def run(files, flags = nil)
     end
 end
 
-result = GetoptLong.new(
-    [ "--build",    "-b",			GetoptLong::NO_ARGUMENT ],
-    [ "--debug",	"-d",			GetoptLong::NO_ARGUMENT ],
-    [ "--verbose",	"-v",			GetoptLong::NO_ARGUMENT ],
-    [ "-n",			                GetoptLong::REQUIRED_ARGUMENT ],
-    [ "--files",    "-f",           GetoptLong::NO_ARGUMENT ],
-    [ "--help",		"-h",			GetoptLong::NO_ARGUMENT ]
-)
-
-usage = "USAGE: %s [--help] suite" % $0
-
-$options = {}
-keep = []
-
-result.each { |opt,arg|
-    case opt
-    when "--build"
-        $options[:build] = true
-    when "--verbose"
-        $options[:verbose] = true
-    when "--files"
-        $options[:files] = true
-    when "--debug"
-        $options[:debug] = true
-        $options[:verbose] = true
-    when "--help"
-        puts usage
-        exit
-    else
-        keep << opt
-        keep << arg if arg
-    end
-}
-
 if $options[:files]
     run(ARGV, keep)
 else