bahuvrihi-tap 0.10.4 → 0.10.5

data/lib/tap/tasks/dump.rb

@@ -2,21 +2,26 @@ module Tap
   module Tasks
     # :startdoc::manifest the default dump task
     #
-    # A dump task to print application results to a file or IO.  The results are
-    # printed in a format allowing dumped results to be reloaded and used as
-    # inputs to other tasks.  See Tap::Load for more details.
+    # A dump task to print aggregated application results to a file or IO.  
+    # The results are printed as YAML, allowing dumped results to be 
+    # reloaded and used as inputs to other tasks.
     #
-    # Often dump is used as the final task in a round of tasks; if no filepath is 
-    # specified, the results are printed to stdout.
+    # Often dump is used as the final task in a round of tasks; if no filepath 
+    # is specified, the results are printed to stdout.
     #  
-    #   % tap run -- [your tasks] --+ dump FILEPATH
+    #   % tap run -- [tasks] --+ dump FILEPATH
     #
+    # See Tap::Load for more details.
     class Dump < Tap::FileTask
     
       config :date_format, '%Y-%m-%d %H:%M:%S'   # the date format
       config :audit, true, &c.switch             # include the audit trails
       config :date, true, &c.switch              # include a date
-    
+      config :filter, nil, &c.regexp_or_nil      # only dump matching objects
+      
+      # Calls dump_to with the target.  If the target is not an
+      # IO, process assumes the target is a filepath.  In that
+      # case, the file is prepared and the results dumped to it.
       def process(target=$stdout)
         case target
         when IO then dump_to(target)
@@ -34,9 +39,9 @@ module Tap
         trails = []
         results = {}
         app.aggregator.to_hash.each_pair do |src, _results|
-          name = src.respond_to?(:name) ? src.name : ''
-
-          results["#{name} (#{src.object_id})"] = _results.collect {|_audit| _audit._current }
+          next if filter && src.to_s !~ filter
+          
+          results["#{src} (#{src.object_id})"] = _results.collect {|_audit| _audit._current }
           _results.each {|_audit| trails << _audit._to_s }
         end
       

data/lib/tap/tasks/load.rb

@@ -0,0 +1,25 @@
+module Tap
+  module Tasks
+    # :startdoc::manifest the default load task
+    #
+    # Load YAML-formatted data, as may be produced using Tap::Dump,
+    # and makes this data available for other tasks.  Load is often
+    # used as a gateway task to other tasks.
+    #
+    #   % tap run -- load FILEPATH --: [task]
+    #
+    class Load < Tap::Task
+
+      def process(input)
+        obj = case input
+        when StringIO then YAML.load(input.read)
+        else
+          log :load, input
+          YAML.load_file(input)
+        end
+        
+        obj.values.flatten
+      end
+    end 
+  end
+end

data/lib/tap/tasks/rake.rb

@@ -45,9 +45,9 @@ module Tap
     
       class << self
       
-        # Overrides Tap::Support::FrameworkClass#instantiate to do  
+        # Overrides Tap::Support::FrameworkClass#parse! to do  
         # nothing so that all args get passed forward to rake.
-        def instantiate(argv, app=Tap::App.instance) # => instance, argv
+        def parse!(argv, app=Tap::App.instance) # => instance, argv
           if argv.include?('--help')
             puts help
             exit

data/lib/tap/test.rb

@@ -1,21 +1,14 @@
 require 'test/unit'
+$:.unshift File.expand_path("#{File.dirname(__FILE__)}/..")
 
 module Test # :nodoc:
   module Unit # :nodoc:
     
-    # Methods extending TestCase.  
-    #
-    # === Method Availability
-    # Note that these methods are added piecemeal by Tap::Test::SubsetMethods, 
-    # Tap::Test::FileMethods and Tap::Test::TapMethods, but that fact doesn't 
-    # come through in the documentation.  Hence, not all of them will be available 
-    # if you're only using SubsetMethods or FileMethods.  Breaks down like this:
-    #
-    #   Using:           Methods Available:
-    #   TapMethods       all
-    #   FileMethods      all, except acts_as_tap_test
-    #   SubsetMethods    all, except acts_as_tap_test, acts_as_file_test, file_test_root
-    #
+    # Methods extending TestCase. For more information see:
+    # - Tap::Test::SubsetMethods
+    # - Tap::Test::FileMethods
+    # - Tap::Test::TapMethods
+    #   
     #--
     #See the TestTutorial for more information.
     class TestCase
@@ -26,11 +19,12 @@ module Test # :nodoc:
           child.instance_variable_set(:@run_test_suite, true)
         end
         
-        #
-        # Methods for skipping a test suite
-        #
-        
+        # Indicates when the test suite should be run or skipped.
         attr_accessor :run_test_suite
+        
+        # An array of messages printed when a test is skipped
+        # by setting run_test_suite to false.
+        attr_reader :skip_messages
 
         # Causes a test suite to be skipped.  If a message is given, it will
         # print and notify the user the test suite has been skipped.
@@ -39,39 +33,46 @@ module Test # :nodoc:
 
           # experimental -- perhaps use this so that a test can be skipped
           # for multiple reasons?
-          @skip_messages << msg
+          skip_messages << msg
         end
 
         alias :original_suite :suite
 
-        # Modifies the default suite method to include/exclude tests based on platform.
+        # Modifies the default suite method to skip the suit unless
+        # run_test_suite is true.  If the test is skipped, the skip_messages 
+        # will be printed along with the default 'Skipping <Test>' message.
         def suite # :nodoc:
           if run_test_suite
             original_suite
           else
-            skip_message = @skip_messages.compact.join(', ')
+            skip_message = skip_messages.compact.join(', ')
             puts "Skipping #{name}#{skip_message.empty? ? '' : ': ' + skip_message}"
+            
+            # return an empty test suite of the appropriate name
             Test::Unit::TestSuite.new(name)
           end
         end
         
-        # Causes a TestCase to act as a file test, by instantiating a class Tap::Root 
-        # (trs), and including FileMethods.  The root and directories used to 
-        # instantiate trs can be specified as options.  By default file_test_root
-        # and the directories {:input => 'input', :output => 'output', :expected => 'expected'} 
-        # will be used.
+        # Causes a TestCase to act as a file test, by including FileMethods and
+        # instantiating class_test_root (a Tap::Root).  The root and directories 
+        # used by class_test_root may be specified as options.  
         #
-        # Note: file_test_root determines a root directory <em>based on the calling file</em>.  
-        # Be sure to specify the root directory explicitly if you call acts_as_file_test
-        # from a file that is NOT meant to be test file.
+        # Note: by default acts_as_file_test determines a root directory 
+        # <em>based on the calling file</em>.  Be sure to specify the root 
+        # directory manually if you call acts_as_file_test from a file that 
+        # isn't the test file.
         def acts_as_file_test(options={})
           include Tap::Test::FileMethods
           
           options = {
-            :root => file_test_root,
-            :directories => {:input => 'input', :output => 'output', :expected => 'expected'}
+            :root => test_root_dir,
+            :directories => {
+              :input => 'input',
+              :output => 'output',
+              :expected => 'expected'}
           }.merge(options)
-          self.trs = Tap::Root.new(options[:root], options[:directories])
+          
+          self.class_test_root = Tap::Root.new(options[:root], options[:directories])
         end
 
         # Causes a unit test to act as a tap test -- resulting in the following:
@@ -79,23 +80,39 @@ module Test # :nodoc:
         # - inclusion of Tap::Test::SubsetMethods
         # - inclusion of Tap::Test::InstanceMethods 
         #
-        # Note:  Unless otherwise specified, <tt>acts_as_tap_test</tt> infers a root directory
-        # based on the calling file. Be sure to specify the root directory explicitly 
-        # if you call acts_as_file_test from a file that is NOT meant to be test file.
+        # Note: by default acts_as_tap_test determines a root directory 
+        # <em>based on the calling file</em>.  Be sure to specify the root 
+        # directory manually if you call acts_as_file_test from a file that 
+        # isn't the test file.
         def acts_as_tap_test(options={})
           include Tap::Test::SubsetMethods
           include Tap::Test::FileMethods
           include Tap::Test::TapMethods
           
-          acts_as_file_test({:root => file_test_root}.merge(options))
+          acts_as_file_test({:root => test_root_dir}.merge(options))
         end
 
         def acts_as_script_test(options={})
           include Tap::Test::FileMethods
           include Tap::Test::ScriptMethods
           
-          acts_as_file_test({:root => file_test_root}.merge(options))
+          acts_as_file_test({:root => test_root_dir}.merge(options))
+        end
+        
+        private
+        
+        # Infers the test root directory from the calling file.
+        #   'some_class.rb' => 'some_class'
+        #   'some_class_test.rb' => 'some_class'
+        def test_root_dir # :nodoc:
+          # caller[1] is considered the calling file (which should be the test case)
+          # note that the output of calller.first is like:
+          #   ./path/to/file.rb:10
+          #   ./path/to/file.rb:10:in 'method'
+          calling_file = caller[1].gsub(/:\d+(:in .*)?$/, "")
+          calling_file.chomp(File.extname(calling_file)).chomp("_test") 
         end
+         
       end
     end
   end
@@ -110,6 +127,8 @@ module Tap
     autoload(:SubsetMethods, 'tap/test/subset_methods')
     autoload(:FileMethods, 'tap/test/file_methods')
     autoload(:TapMethods, 'tap/test/tap_methods')
+    autoload(:ScriptMethods, 'tap/test/script_methods')
+    autoload(:Utils, 'tap/test/utils')
   end
 end
 

data/lib/tap/test/file_methods.rb

@@ -6,88 +6,57 @@ module Tap
   module Test  
     
 
-    # FileMethods sets up a TestCase with methods for accessing and utilizing
-    # test-specific files and directories.  Each class that acts_as_file_test
-    # is set up with a Tap::Root structure (trs) that mediates the creation of 
-    # test method filepaths. 
+    # FileMethods facilitates access and utilization of test-specific files and
+    # directories. FileMethods provides each test method is setup with a Tap::Root 
+    # (method_root) specific for the method, and defines a new assertion method 
+    # (assert_files) to facilitate tests which involve the production and/or 
+    # modification of files.
     #
+    #   [file_methods_doc_test.rb]
     #   class FileMethodsDocTest < Test::Unit::TestCase
     #     acts_as_file_test
     # 
     #     def test_something
-    #                           #    dir = File.expand_path( File.dirname(__FILE__) )
-    #       trs.root            # => dir + "/file_methods_doc", 
-    #       method_root         # => dir + "/file_methods_doc/test_something", 
-    #       method_dir(:input)  # => dir + "/file_methods_doc/test_something/input"
-    #     end
-    #   end
+    #       # each test class has a class test root (ctr)
+    #       # and each test method has a method-specific
+    #       # root (method_root)
     #
-    # === assert_files
+    #       ctr.root                        # => File.expand_path(__FILE__.chomp('_test.rb'))
+    #       method_root.root                # => File.join(ctr.root, "/test_something")
+    #       method_root[:input]             # => File.join(ctr.root, "/test_something/input")
     #
-    # FileMethods is specifically designed for tests that transform a set of input 
-    # files into output files.  For this type of test, input and expected files can
-    # placed into their respective directories then used within the context of
-    # assert_files to ensure the output files are equal to the expected files.
-    # 
-    # For example, lets define a test that transforms input files into output files
-    # in a trivial way, simply by replacing 'input' with 'output' in the file.
+    #       # files in the output directory are cleared before
+    #       # and after each test; this passes each time the
+    #       # test is run with no additional cleanup:
     #
-    #   class FileMethodsDocTest < Test::Unit::TestCase
-    #     acts_as_file_test
-    # 
-    #     def test_sub
-    #       assert_files do |input_files|
-    #         input_files.collect do |filepath|
-    #           input = File.read(filepath)
-    #           output_file = method_filepath(:output, File.basename(filepath))
-    #
-    #           File.open(output_file, "w") do |f|
-    #             f << input.gsub(/input/, "output")
-    #           end 
+    #       output_file = method_root.filepath(:output, 'sample.txt')
+    #       assert !File.exists?(output_file)
     #
-    #           output_file
-    #         end
-    #       end
-    #     end
-    #   end
+    #       make_test_directories           # makes the input, output, expected directories
+    #       FileUtils.touch(output_file)
     #
-    # Now say you had some input and expected files for the 'test_sub' method:
+    #       assert File.exists?(output_file)
     #
-    #   [file_methods_doc/test_sub/input/one.txt]
-    #   test input 1
+    #       # the assert_files method compares files produced
+    #       # by the block the expected files, ensuring they
+    #       # are the same (see the documentation for the 
+    #       # simplest use of assert_files)
+    #       
+    #       expected_file = method_root.filepath(:expected, 'output.txt')
+    #       File.open(expected_file, 'w') {|file| file << 'expected output' }
     #
-    #   [file_methods_doc/test_sub/input/two.txt]
-    #   test input 2
-    #
-    #   [file_methods_doc/test_sub/expected/one.txt]
-    #   test output 1
-    #
-    #   [file_methods_doc/test_sub/expected/two.txt]
-    #   test output 2
-    #
-    # When you run the FileMethodsDocTest test, the test_sub test will pass
-    # the input files to the assert_files block.  Then assert_files compares
-    # the returned filepaths with the expected files translated from the 
-    # expected directory to the output directory.  In this case, the files 
-    # are equal and the test passes.
-    #
-    # The test fails if the returned files aren't equal to the expected files,
-    # either because there are missing or extra files, or if the file contents
-    # are different. 
-    #
-    # When the test completes, the teardown method cleans up the output directory.  
-    # For ease in debugging, ENV variable flags can be specified to keep all 
-    # output files (KEEP_OUTPUTS) or to keep the output files for just the tests 
-    # that fail (KEEP_FAILURES).  These flags can be specified from the command 
-    # line if you're running the tests with rake or tap:
-    #
-    #   % rake test keep_outputs=true
-    #   % tap run test keep_failures=true
+    #       # passes
+    #       assert_files do 
+    #         output_file = method_root.filepath(:output, 'output.txt')
+    #         File.open(output_file, 'w') {|file| file << 'expected output' }
     #
+    #         output_file
+    #       end 
+    #     end
+    #   end
     #
-    # === Class Methods
-    # 
-    # See {Test::Unit::TestCase}[link:classes/Test/Unit/TestCase.html] for documentation of the class methods added by FileMethods.
+    # See {Test::Unit::TestCase}[link:classes/Test/Unit/TestCase.html] and
+    # FileMethodsClass for more information.
     module FileMethods
       include Tap::Test::EnvVars
       
@@ -96,127 +65,109 @@ module Tap
         base.extend FileMethodsClass
       end
       
-      # Convenience accessor for the test root structure
-      def trs
-        self.class.trs
+      # Convenience method to access the class_test_root.
+      def ctr
+        self.class.class_test_root
       end
-    
-      # Creates the trs.directories, specific to the method calling make_test_directories
+      
+      # Creates the method_root.directories.
       def make_test_directories
-        trs.directories.values.each do |dir| 
-          FileUtils.mkdir_p( File.join(trs.root, method_name_str, dir) )
+        method_root.directories.values.each do |dir| 
+          FileUtils.mkdir_p( method_root[dir] )
         end
       end
       
+      # Attempts to remove the method_root.directories, method_root.root,
+      # and ctr.root.  Any given directory will not be removed unless empty.
+      def cleanup_test_directories
+        method_root.directories.values.each do |dir| 
+          Utils.try_remove_dir(method_root[dir])
+        end
+        
+        Utils.try_remove_dir(method_root.root)
+        Utils.try_remove_dir(ctr.root)
+      end
+
+      # The test-method-specific Tap::Root which may be used to
+      # access test files.  method_root is a duplicate of ctr
+      # reconfigured so that method_root.root is ctr[ method_name.to_sym ]
+      attr_reader :method_root
+      
+      # An array of filepaths setup by method_tempfile; these files
+      # are removed by teardown, as they should all be in the output
+      # directory.
       attr_reader :method_tempfiles
       
-      # Setup deletes the the output directory if it exists, and tries to remove the
-      # method root directory so the directory structure is reset before running the
-      # test, even if outputs were left over from previous tests.
+      # Sets up method_root and attempts to cleanup any left overs from a 
+      # previous test (ie by deleting method_root[:output] and calling 
+      # cleanup_test_directories).  Be sure to call super when overriding 
+      # this method.
       def setup
         super
+        @method_root = ctr.dup.reconfigure(:root => ctr[method_name.to_sym])
         @method_tempfiles = []
-        clear_method_dir(:output)
-        Utils.try_remove_dir(method_root)
+        
+        Utils.clear_dir(method_root[:output])
+        cleanup_test_directories
       end
     
-      # Teardown deletes the the output directories unless flagged otherwise.  Note 
-      # that teardown also checks the environment variables for flags.  To keep all outputs 
-      # (or failures) for all tests, flag keep outputs from the command line like:
+      # Deletes the the method_root[:output] directory (unless flagged
+      # otherwise by an ENV variable) and calls cleanup_test_directories. 
+      # To keep all output directories, or to only keep output directories
+      # for failing tests, set the 'KEEP_OUTPUTS' or 'KEEP_FAILURES' ENV 
+      # variables:
       #
-      #   % tap run test KEEP_OUTPUTS=true
-      #   % tap run test KEEP_FAILURES=true
+      #   % rap test KEEP_OUTPUTS=true
+      #   % rap test KEEP_FAILURES=true
+      #
+      # Be sure to call super when overriding this method.
       def teardown     
         # clear out the output folder if it exists, unless flagged otherwise
         unless env("KEEP_OUTPUTS") || (!@test_passed && env("KEEP_FAILURES"))
           begin
-             clear_method_dir(:output) 
+             Utils.clear_dir(method_root[:output])
           rescue
             raise("teardown failure: could not remove output files")
           end
         end
         
-        Utils.try_remove_dir(method_root)
-        Utils.try_remove_dir(trs.root)
+        cleanup_test_directories
       end 
       
       # Returns method_name as a string (Ruby 1.9 symbolizes method_name)
       def method_name_str
         method_name.to_s
       end
-
-      # The method_root directory is defined as trs.filepath(method_name)
-      def method_root(method=method_name_str)
-        trs.filepath(method)
-      end
-
-      # The method directory is defined as 'dir/method', where method is the calling method
-      # by default.  method_dir returns the method directory if it exists, otherwise it returns
-      # trs[dir].
-      def method_dir(dir, method=method_name_str)
-        File.join(method_root(method), trs.directories[dir] || dir.to_s)
-      end
-    
-      # Returns a glob of files matching the input pattern, underneath the method directory
-      # if it exists, otherwise the <tt>trs[dir]</tt> directory.
-      def method_glob(dir, *patterns)
-        dir = trs.relative_filepath(:root, method_dir(dir))
-        trs.glob(dir, *patterns) 
-      end
-    
-      # Returns a filepath constructed from the method directory if it exists, 
-      # otherwise the filepath will be constructed from <tt>trs[dir]</tt>. 
-      def method_filepath(dir, *filenames)
-        File.join(method_dir(dir), *filenames)
-      end
-    
-      # Removes the method directory from the input filepath, returning the resuting filename.
-      # If the method directory does not exist, <tt>trs[dir]</tt> will be removed.
-      def method_relative_filepath(dir, filepath)
-        dir = trs.relative_filepath(:root, method_dir(dir))
-        trs.relative_filepath(dir, filepath)
-      end
     
-      # Returns an output file corresponding to the input file, translated from the
-      # input directory to the output directory.  
+      # Generates a temporary filepath formatted like "output_dir\filename.n.ext"
+      # where n is a counter that ensures the filepath is unique and non-existant
+      # (specificaly n is equal to the number of method_tempfiles generated 
+      # by the current test, incremented as necessary to achieve a non-existant
+      # filepath). 
       #
-      # If the input method directory exists, it will be removed from the filepath.  
-      # If the output method directory exists, it will be inserted in the filepath.  
-      def method_translate(filepath, input_dir, output_dir)
-        input_dir = trs.relative_filepath(:root, method_dir(input_dir))
-        output_dir = trs.relative_filepath(:root, method_dir(output_dir))
-        trs.translate(filepath, input_dir, output_dir)
-      end
-      
-      # Attempts to recursively remove the specified method directory and all 
-      # files within it.  Raises an error if the removal does not succeed.
-      def clear_method_dir(dir)
-        # clear out the folder if it exists
-        dir_path = method_dir(dir, method_name_str)
-        FileUtils.rm_r(dir_path) if File.exists?(dir_path)
-      end
-    
-      # Generates a temporary filepath formatted like "output_dir\filename.pid.n.ext" where n 
-      # is a counter that will be incremented from until a non-existant filepath is achieved.
+      # Unlike Tempfile, method_tempfile does not create the filepath unless a 
+      # block is given, in which case an open File will be passed to the block.
+      # In addition, method_tempfiles are only cleaned up indirectly when the
+      # output directory is removed by teardown; this is both convenient for
+      # testing (when you may want a the file to persist, so you can debug it)
+      # and less enforcing than Tempfile.
       #
       # Notes:
-      # - By default filename is the calling method
-      # - The extension is chomped off the end of the filename
-      # - If the directory for the filepath does not exist, the directory will be created
-      # - Like all files in the output directory, tempfiles will be deleted by the default 
-      #   +teardown+ method
+      # - by default filename is the calling method
+      # - the extension is chomped off the end of the filename
+      # - the directory for the file will be created if it does not exist
+      # - like all files in the output directory, tempfiles will be deleted by
+      #   the default +teardown+ method
       def method_tempfile(filename=method_name_str, &block)
         ext = File.extname(filename)
         basename = filename.chomp(ext)
-        filepath = method_filepath(:output, sprintf('%s%d.%d%s', basename, $$, method_tempfiles.length, ext))
-        method_tempfiles << filepath
-      
-        dirname = File.dirname(filepath)
+        path = next_indexed_path(method_root.filepath(:output, basename), method_tempfiles.length, ext)
+        dirname = File.dirname(path)
+        
+        method_tempfiles << path
         FileUtils.mkdir_p(dirname) unless File.exists?(dirname)
-        if block_given?
-          File.open(filepath, "w", &block)
-        end
-        filepath
+        File.open(path, "w", &block) if block_given?
+        path
       end
       
       # assert_files runs a file-based test that feeds all files from input_dir
@@ -225,33 +176,90 @@ module Tap
       # the block are used in the comparison; additional files in the output directory 
       # are effectively ignored.
       #
-      # A variety of options can be specified to adjust the behavior:
+      # === Example
+      # Lets define a test that transforms input files into output files in a trivial 
+      # way, simply by replacing 'input' with 'output' in the file.
+      #
+      #   class FileMethodsDocTest < Test::Unit::TestCase
+      #     acts_as_file_test
+      # 
+      #     def test_sub
+      #       assert_files do |input_files|
+      #         input_files.collect do |filepath|
+      #           input = File.read(filepath)
+      #           output_file = method_root.filepath(:output, File.basename(filepath))
+      #
+      #           File.open(output_file, "w") do |f|
+      #             f << input.gsub(/input/, "output")
+      #           end 
+      #
+      #           output_file
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # Now say you had some input and expected files for the 'test_sub' method:
+      #
+      #   file_methods_doc/test_sub
+      #   |- expected
+      #   |   |- one.txt
+      #   |   `- two.txt
+      #   `- input
+      #       |- one.txt
+      #       `- two.txt
+      # 
+      #   [input/one.txt]
+      #   test input 1
+      #
+      #   [input/two.txt]
+      #   test input 2
+      #
+      #   [expected/one.txt]
+      #   test output 1
+      #
+      #   [expected/two.txt]
+      #   test output 2
+      #
+      # When you run the test, the assert_files passes the input files to the 
+      # block.  When the block completes, assert_files compares the output files
+      # returned by the block with the files in the expected directory.  In this 
+      # case, the files are equal and the test passes.
+      #
+      # Say you changed the content of one of the expected files:
+      #
+      #   [expected/one.txt]
+      #   test flunk 1
+      #
+      # Now the test fails because the output files aren't equal to the expected
+      # files.  The test will also fail if there are missing or extra files. 
+      #
+      # === Options
+      # A variety of options can be specified to adjust the behavior of assert_files:
       # 
       #   :input_dir                      specify the directory to glob for input files
-      #                                     (default method_dir(:input))
+      #                                     (default method_root[:input])
       #   :output_dir                     specify the output directory
-      #                                     (default method_dir(:output))
+      #                                     (default method_root[:output])
       #   :expected_dir                   specify the directory to glob for expected files
-      #                                     (default method_dir(:expected))
-      #   :input_files                    directly specify the input files to pass to the block
-      #   :expected_files                 directly specify the expected files used for comparison
+      #                                     (default method_root[:expected])
+      #   :input_files                    directly specify the input files for the block
+      #   :expected_files                 directly specify the expected files for comparison
       #   :include_input_directories      specifies directories to be included in the 
       #                                     input_files array (by default dirs are excluded)
       #   :include_expected_directories   specifies directories to be included in the
-      #                                     expected-output file list comparison (by default 
-      #                                     dirs are excluded, note that naturally only files 
-      #                                     have their actual content compared)  
+      #                                     expected-output file list comparison 
+      #                                     (by default dirs are excluded)  
       #                  
-      # Option keys should be symbols.  assert_files will fail if :expected_files was 
-      # not specified in the options and no files were found in method_dir(:expected).  
-      # This tries to prevent silent false-positive results when you forget to put 
-      # expected files in their place.
+      # assert_files will fail if <tt>:expected_files</tt> was not specified in the
+      # options and no files were found in <tt>:expected_dir</tt>.  This check tries 
+      # to prevent silent false-positive results when you forget to put expected files 
+      # in their place.
       #
       # === File References
-      # Sometimes the same files will get used across multiple tests.  To prevent
-      # duplication, and allow separate management of test files, file references
-      # can be provided in place of test files.  For instance, with a test
-      # directory like:
+      # Sometimes the same files will get used across multiple tests.  To allow separate 
+      # management of test files and prevent duplication, file references can be provided 
+      # in place of test files.  For instance, with a test directory like:
       #
       #   method_root
       #   |- expected
@@ -267,20 +275,30 @@ module Tap
       # The input and expected files (all references in this case) can be dereferenced 
       # to the 'ref' filepaths like so:
       #
-      #   assert_files :reference_dir => method_dir(:ref) do |input_files|
+      #   assert_files :reference_dir => method_root[:ref] do |input_files|
       #     input_files # => ['method_root/ref/one.txt', 'method_root/ref/two.txt']
       #
       #     input_files.collect do |input_file|
-      #       output_file = method_filepath(:output, File.basename(input_file)
+      #       output_file = method_root.filepath(:output, File.basename(input_file)
       #       FileUtils.cp(input_file, output_file)
       #       output_file
       #     end
       #   end
       #
       # Dereferencing occurs relative to the input_dir/expected_dir configurations; a
-      # reference_dir must be specified for dereferencing to occur (see dereference
+      # reference_dir must be specified for dereferencing to occur (see Utils.dereference 
       # for more details).
       #
+      # === Keeping Outputs
+      # By default FileMethods sets teardown to cleans up the output directory. For 
+      # ease in debugging, ENV variable flags can be specified to keep all output 
+      # files (KEEP_OUTPUTS) or to keep the output files for just the tests that fail 
+      # (KEEP_FAILURES).  These flags can be specified from the command line if you're
+      # running the tests with rake or rap:
+      #
+      #   % rake test keep_outputs=true
+      #   % rap test keep_failures=true
+      #
       #--
       # TODO:
       # * add debugging information to indicate, for instance,  
@@ -294,9 +312,9 @@ module Tap
         expected_dir = options[:expected_dir]
         
         reference_dir = options[:reference_dir]
-        reference_extname = options[:reference_extname]
+        reference_pattern = options[:reference_pattern]
         
-        Utils.dereference([input_dir, expected_dir], reference_dir, reference_extname) do
+        Utils.dereference([input_dir, expected_dir], reference_dir, reference_pattern || '**/*.ref') do
 
           # Get the input and expected files in this manner:
           # - look for manually specified files
@@ -348,9 +366,9 @@ module Tap
       # The default assert_files options
       def default_assert_files_options
         {
-          :input_dir => method_dir(:input),
-          :output_dir => method_dir(:output),
-          :expected_dir => method_dir(:expected),
+          :input_dir => method_root[:input],
+          :output_dir => method_root[:output],
+          :expected_dir => method_root[:expected],
           
           :input_files => nil,
           :expected_files => nil,
@@ -362,6 +380,14 @@ module Tap
         }
       end
       
+      private
+      
+      # utility method for method_tempfile; increments index until the
+      # path base.indexext does not exist.
+      def next_indexed_path(base, index, ext) # :nodoc:
+        path = sprintf('%s.%d%s', base, index, ext)
+        File.exists?(path) ? next_indexed_path(base, index + 1, ext) : path
+      end
     end
   end
 end