bahuvrihi-tap 0.11.2 → 0.12.0

data/lib/tap/tasks/dump.rb

@@ -41,8 +41,8 @@ module Tap
         app.aggregator.to_hash.each_pair do |src, _results|
           next if filter && src.to_s !~ filter
           
-          results["#{src} (#{src.object_id})"] = _results.collect {|_audit| _audit._current }
-          _results.each {|_audit| trails << _audit._to_s }
+          results["#{src} (#{src.object_id})"] = _results.collect {|_audit| _audit.value }
+          _results.each {|_audit| trails << _audit.dump }
         end
       
         if audit

data/lib/tap/test/extensions.rb

@@ -16,8 +16,8 @@ module Tap
       end
     
       # Causes a TestCase to act as a file test, by including FileTest and
-      # instantiating class_test_root (a Tap::Root).  The root and directories 
-      # used by class_test_root may be specified as options.  
+      # instantiating class_test_root (a Tap::Root).  The root, relative_paths,
+      # and absolute_paths used by class_test_root may be specified as options.  
       #
       # Note: by default acts_as_file_test determines a root directory 
       # <em>based on the calling file</em>.  Be sure to specify the root 
@@ -26,15 +26,10 @@ module Tap
       def acts_as_file_test(options={})
         include Tap::Test::FileTest
       
-        options = {
-          :root => test_root_dir,
-          :directories => {
-            :input => 'input',
-            :output => 'output',
-            :expected => 'expected'}
-        }.merge(options)
-      
-        self.class_test_root = Tap::Root.new(options[:root], options[:directories])
+        self.class_test_root = Tap::Root.new(
+          options[:root] || test_root_dir, 
+          options[:relative_paths] || {}, 
+          options[:absolute_paths] || {})
       end
 
       # Causes a unit test to act as a tap test -- resulting in the following:
@@ -47,14 +42,17 @@ module Tap
       # directory manually if you call acts_as_file_test from a file that 
       # isn't the test file.
       def acts_as_tap_test(options={})
+        options[:root] ||= test_root_dir
+        
         acts_as_subset_test
-        acts_as_file_test({:root => test_root_dir}.merge(options))
+        acts_as_file_test(options)
       
         include Tap::Test::TapTest
       end
 
       def acts_as_script_test(options={})
-        acts_as_file_test({:root => test_root_dir}.merge(options))
+        options[:root] ||= test_root_dir
+        acts_as_file_test(options)
       
         include Tap::Test::ScriptTest
       end

data/lib/tap/test/file_test.rb

@@ -7,7 +7,7 @@ module Tap
   module Test  
     
     # FileTest facilitates access and utilization of test-specific files and
-    # directories. FileTest provides each test method is setup with a Tap::Root 
+    # directories. FileTest provides each test method 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.
@@ -25,32 +25,25 @@ module Tap
     #       method_root.root                # => File.join(ctr.root, "/test_something")
     #       method_root[:input]             # => File.join(ctr.root, "/test_something/input")
     #
-    #       # files in the output directory are cleared before
-    #       # and after each test; this passes each time the
+    #       # files in the :output and :tmp directories are cleared
+    #       # before and after each test; this passes each time the
     #       # test is run with no additional cleanup:
     #
-    #       output_file = method_root.filepath(:output, 'sample.txt')
-    #       assert !File.exists?(output_file)
+    #       assert !File.exists?(method_root[:tmp])
     #
-    #       make_test_directories           # makes the input, output, expected directories
-    #       FileUtils.touch(output_file)
-    #
-    #       assert File.exists?(output_file)
+    #       tmp_file = method_root.prepare(:tmp, 'sample.txt') {|file| file << "content" }
+    #       assert_equal "content", File.read(tmp_file)
     #
     #       # 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' }
+    #       expected_file = method_root.prepare(:expected, 'output.txt') {|file| file << 'expected output' }
     #
     #       # passes
     #       assert_files do 
-    #         output_file = method_root.filepath(:output, 'output.txt')
-    #         File.open(output_file, 'w') {|file| file << 'expected output' }
-    #
-    #         output_file
+    #         method_root.prepare(:output, 'output.txt') {|file| file << 'expected output' }
     #       end 
     #     end
     #   end
@@ -61,67 +54,51 @@ module Tap
       include Tap::Test::EnvVars
       include Tap::Test::Assertions
       
-      def self.included(base)
+      def self.included(base) # :nodoc:
         super
         base.extend FileTestClass
+        base.cleanup_dirs = [:output, :tmp]
       end
       
       # Convenience method to access the class_test_root.
       def ctr
         self.class.class_test_root
       end
-      
-      # Creates the method_root.directories.
-      def make_test_directories
-        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 ]
+      # 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
-      
-      # 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.
+      # Sets up method_root and calls cleanup.  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 = []
-        
-        Utils.clear_dir(method_root[:output])
-        cleanup_test_directories
+        cleanup
+      end
+      
+      # Cleans up the method_root.root directory by removing the class
+      # cleanup_dirs (by default :tmp and :output). The root directory
+      # will also be removed if it is empty.
+      # 
+      # Override as necessary in subclasses.
+      def cleanup
+        self.class.cleanup_dirs.each do |dir|
+          Utils.clear_dir(method_root[dir])
+        end
+        Utils.try_remove_dir(method_root.root)
       end
     
-      # 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:
+      # Calls cleanup unless flagged otherwise by an ENV variable. To prevent
+      # cleanup (when debugging for example), set the 'KEEP_OUTPUTS' or 
+      # 'KEEP_FAILURES' ENV variables:
       #
       #   % rap test KEEP_OUTPUTS=true
       #   % rap test KEEP_FAILURES=true
       #
-      # Be sure to call super when overriding this method.
+      # Cleanup is only suppressed for failing tests when KEEP_FAILURES is
+      # specified.  Be sure to call super when overriding this method.
       def teardown
         # check that method_root still exists (nil may
         # indicate setup was overridden without super)
@@ -132,65 +109,34 @@ module Tap
         # clear out the output folder if it exists, unless flagged otherwise
         unless env("KEEP_OUTPUTS") || (!passed? && env("KEEP_FAILURES"))
           begin
-             Utils.clear_dir(method_root[:output])
+            cleanup
           rescue
-            raise("teardown failure: could not remove output files (#{$!.message})")
+            raise("cleanup failure: #{$!.message}")
           end
         end
         
-        cleanup_test_directories
+        Utils.try_remove_dir(ctr.root)
       end 
       
       # Returns method_name as a string (Ruby 1.9 symbolizes method_name)
       def method_name_str
         method_name.to_s
       end
-    
-      # 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). 
-      #
-      # 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
-      # - 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)
-        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)
-        File.open(path, "w", &block) if block_given?
-        path
-      end
       
-      # assert_files runs a file-based test that feeds all files from input_dir
-      # to the block, then compares the resulting files (which should be relative to 
-      # output_dir) with all the files in expected_dir.  Only the files returned by 
-      # the block are used in the comparison; additional files in the output directory 
-      # are effectively ignored.
+      # Runs a file-based test that compares files created by the block with
+      # files in an expected directory.  The block receives files from the
+      # input directory, and should return a list of files relative to the 
+      # output directory.  Only the files returned by the block are compared;
+      # additional files in the output directory are effectively ignored.
       #
       # === 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.
+      # 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 FileTestDocTest < Test::Unit::TestCase
       #     acts_as_file_test
       # 
-      #     def test_sub
+      #     def test_assert_files
       #       assert_files do |input_files|
       #         input_files.collect do |filepath|
       #           input = File.read(filepath)
@@ -206,9 +152,9 @@ module Tap
       #     end
       #   end
       #
-      # Now say you had some input and expected files for the 'test_sub' method:
+      # Now say you had some input and expected files for test_assert_files:
       #
-      #   file_test_doc/test_sub
+      #   file_test_doc/test_assert_files
       #   |- expected
       #   |   |- one.txt
       #   |   `- two.txt
@@ -229,20 +175,21 @@ module Tap
       #   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.
+      # 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. 
+      # Now the test fails because the output files aren't equal to the
+      # expected files.  The test also fails if there are missing or extra
+      # files. 
       #
       # === Options
-      # A variety of options can be specified to adjust the behavior of assert_files:
+      # A variety of options adjust the behavior of assert_files:
       # 
       #   :input_dir                      specify the directory to glob for input files
       #                                     (default method_root[:input])
@@ -258,15 +205,17 @@ module Tap
       #                                     expected-output file list comparison 
       #                                     (by default dirs are excluded)  
       #                  
-      # 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.
+      # 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 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:
+      #
+      # 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
@@ -279,8 +228,8 @@ module Tap
       #       |- one.txt
       #       `- two.txt
       #   
-      # The input and expected files (all references in this case) can be dereferenced 
-      # to the 'ref' filepaths like so:
+      # The input and expected files (all references in this case) can be
+      # dereferenced to the 'ref' filepaths like so:
       #
       #   assert_files :reference_dir => method_root[:ref] do |input_files|
       #     input_files # => ['method_root/ref/one.txt', 'method_root/ref/two.txt']
@@ -292,16 +241,17 @@ module Tap
       #     end
       #   end
       #
-      # Dereferencing occurs relative to the input_dir/expected_dir configurations; a
-      # reference_dir must be specified for dereferencing to occur (see Utils.dereference 
-      # for more details).
+      # Dereferencing occurs relative to the input_dir/expected_dir
+      # configurations; a reference_dir must be specified for dereferencing to
+      # occur (see Utils.dereference for more details).
       #
       # === Keeping Outputs
-      # By default FileTest 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:
+      #
+      # By default FileTest cleans up everything under method_root except the
+      # input and expected directories. For ease in debugging, ENV variable
+      # flags can be specified to prevent cleanup for all tests (KEEP_OUTPUTS)
+      # or just 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
@@ -346,8 +296,6 @@ module Tap
       private
       
       def transform_test(block, options={}) # :yields: expected_files, output_files
-        make_test_directories
-        
         options = default_assert_files_options.merge(options)
         input_dir = options[:input_dir]
         output_dir = options[:output_dir] 
@@ -409,12 +357,6 @@ module Tap
         end
       end
       
-      # 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

data/lib/tap/test/file_test_class.rb

@@ -4,9 +4,12 @@ module Tap
     # Class methods extending tests which include FileTest.
     module FileTestClass
       
-      # The class-level test root (a Tap::Root).
+      # The class-level test root (a Tap::Root)
       attr_accessor :class_test_root
       
+      # An array of directories to be cleaned up by cleanup
+      attr_accessor :cleanup_dirs
+
     end
   end
 end

data/lib/tap/test/tap_test.rb

@@ -1,32 +1,6 @@
 module Tap
   module Test
 
-    # Used during check_audit to hold the sources and values of an audit
-    # in the correct order.  Oriented so that the next value to be checked
-    # is at the top of the stack.  Used internally.
-    class AuditStack # :nodoc:
-      attr_reader :test
-    
-      def initialize(test)
-        @test = test
-        @stack = []
-      end
-    
-      def load_audit(values)
-        [values._sources, values._values].transpose.reverse_each do |sv|
-          load(*sv)
-        end
-      end
-    
-      def load(source, value)
-        @stack.unshift [source, value]
-      end
-    
-      def next
-        @stack.shift
-      end
-    end
-
     # Tap-specific testing methods to help with testing Tasks, such as the
     # checking of audits and test-specific modification of application 
     # configuration.
@@ -40,7 +14,7 @@ module Tap
       attr_reader :app
       
       # Setup creates a test-method-specific application that is initialized
-      # to the method_root, and uses the directories and absolute paths from
+      # to the method_root, and uses the relative and absolute paths from
       # trs (the test root structure, see Tap::Test::FileTest). 
       #
       # Also makes sure Tap::App.instance returns the test method app.
@@ -50,153 +24,51 @@ module Tap
         Tap::App.instance = @app
       end
       
-      #
-      # audit test methods
-      #
-      
-      # Used to define expected audits in Tap::Test::TapTest#assert_audit_equal
-      class ExpAudit < Array
-      end
-      
-      # Used to define merged audit trails in Tap::Test::TapTest#assert_audit_equal
-      class ExpMerge < Array
-      end
-      
-      class Tracer
-        include Tap::Support::Executable
-
-        class << self
-          def intern(n, app, runlist)
-            Array.new(n) { |index| new(index, app, runlist) }
-          end
-        end
-
-        def initialize(index, app, runlist)
-          @index = index
-          @runlist = runlist
-
-          @app = app
-          @_method_name = :trace
-          @on_complete_block =nil
-          @dependencies = []
-          @batch = [self]
-        end
-
-        def concat(str, id)
-          "#{str} #{id}".strip
-        end
-
-        def trace(trace)
-          id = "#{@index}.#{batch_index}"
-          @runlist << id
-
-          case trace
-          when Array then trace.collect {|str| concat(str, id) }
-          when String then concat(trace, id)
-          else raise "cannot utilize trace: #{trace}"
-          end
-        end
-      end
-      
       # Asserts that an array of audits are all equal, basically feeding
       # each pair of audits to assert_audit_equal.
-      def assert_audits_equal(expected, audits)
-        error_msg = "expected <#{audits.length}> audits, but was <#{expected.length}>"
-        Utils.each_pair_with_index(expected, audits, error_msg) do |exp, audit, index|
-          assert_audit_equal(exp, audit, [index])
+      def assert_audits_equal(expected, audits, msg=nil, &block)
+        assert_equal expected.length, audits.length, "expected <#{expected.length}> audits, but was <#{audits.length}>"
+        Utils.each_pair_with_index(expected, audits) do |exp, audit, index|
+          assert_audit_equal(exp, audit, &block)
         end
       end
       
-      # Asserts that an audit is as expected.  The expected audit should
-      # be an ExpAudit (just a subclass of Array) that records the sources
-      # and the values at each step in the audit trail.  Proc objects can
-      # be provided in place of expected records that are hard or impossible 
-      # to provide directly; the Proc will be used to validate the actual
-      # record.  Merges must be marked in the ExpAudit using ExpMerge.
+      # Asserts that an audit trail matches the expected trail.  By default
+      # the expected trail should be composed of [key, value] arrays 
+      # representing each audit, but a block may be provided to collect other
+      # attributes.
       #
       # Simple assertion:
       #
-      #   a = Tap::Support::Audit.new
-      #   a._record(:a, 'a')
-      #   a._record(:b, 'b')
-      # 
-      #   e = ExpAudit[[:a, 'a'], [:b, 'b']]
-      #   assert_audit_equal(e, a)
-      # 
-      # Assertion validating a record with a Proc (any number of
-      # records can be validated with a Proc):
-      #
-      #   a = Tap::Support::Audit.new
-      #   a._record(:a, 'a')
-      #   a._record(:b, 'b')
+      #   a = Audit.new(:a, 'a')
+      #   b = Audit.new(:b, 'b', a)
       # 
-      #   e = ExpAudit[
-      #        lambda {|source, value| source == :a && value == 'a'},
-      #       [:b, 'b']]
-      #   assert_audit_equal(e, a)
+      #   e = [[:a, 'a'], [:b, 'b']]
+      #   assert_audit_equal(e, b)
       #
       # Assertion with merge:
       #
-      #   a = Tap::Support::Audit.new
-      #   a._record(:a, 'a')
-      #   a._record(:b, 'b')
+      #   a = Audit.new(:a, 'a')
+      #   b = Audit.new(:b, 'b', a)
       # 
-      #   b = Tap::Support::Audit.new
-      #   b._record(:c, 'c')
-      #   b._record(:d, 'd')
+      #   c = Audit.new(:c, 'c')
+      #   d = Audit.new(:d, 'd', c)
       # 
-      #   c = Tap::Support::Audit.merge(a,b)
-      #   c._record(:e, 'e')
-      #   c._record(:f, 'f')
+      #   e = Audit.new(:e, 'e')
+      #   f = Audit.new(:f, 'f', [b,d])
       # 
-      #   ea = ExpAudit[[:a, "a"], [:b, "b"]]
-      #   eb = ExpAudit[[:c, "c"], [:d, "d"]]
-      #   e = ExpAudit[ExpMerge[ea, eb], [:e, "e"], [:f, "f"]]
+      #   eb = [[:a, "a"], [:b, "b"]]
+      #   ed = [[:c, "c"], [:d, "d"]]
+      #   e =  [[eb, ed], [:e, "e"], [:f, "f"]]
       # 
       #   assert_audit_equal(e, c)
       #
-      # When assert_audit_equal fails, a string of indicies is provided
-      # to help locate which record was unequal.  For instance in the last
-      # example, say we used:
-      #
-      #   ea = ExpAudit[[:a, "a"], [:b, "FLUNK"]]
-      #   eb = ExpAudit[[:c, "c"], [:d, "d"]]
-      #   e = ExpAudit[ExpMerge[ea, eb], [:e, "e"], [:f, "f"]]
-      #
-      # The failure message will read something like 'unequal record 0:0:1' 
-      # indicating it was e[0][0][1] that failed.  Working through it, 
-      # remembering that ExpAudit and ExpMerge are just subclasses of 
-      # Array:
-      #
-      #   e              # => ExpAudit[ExpMerge[ea, eb], [:e, "e"], [:f, "f"]]
-      #   e[0]           # => ExpMerge[ea, eb]
-      #   e[0][0]        # => ExpAudit[[:a, "a"], [:b, "FLUNK"]]
-      #   e[0][0][1]     # => [:b, "FLUNK"]
-      #
-      def assert_audit_equal(expected, audit, nesting=[])
-        actual = audit._collect_records {|source, value| [source, value]}
-        assert_audit_records_equal(expected, actual, nesting)
+      def assert_audit_equal(expected, audit, msg=nil, &block)
+        block = lambda {|audit| [audit.key, audit.value] } unless block
+        actual = audit.trail(&block)
+        assert_equal(expected, actual, msg)
       end
       
-      def assert_audit_records_equal(expected, actual, nesting=[])
-        assert_equal ExpAudit, expected.class
-        assert_equal expected.length, actual.length, "unequal number of records"
-        
-        expected.each_with_index do |exp_record, i|
-          case exp_record
-          when ExpMerge
-            flunk "empty merge #{(nesting + [i]).join(':')}" if exp_record.empty?
-            exp_record.each_with_index do |exp_audit, j|
-              assert_audit_records_equal(exp_audit, actual[i][j], nesting + [i,j]) 
-            end
-          when Proc
-            assert exp_record.call(*actual[i]), "unconfirmed record #{(nesting + [i]).join(':')}"
-          else
-            assert_equal exp_record, actual[i], "unequal record #{(nesting + [i]).join(':')}"
-          end
-        end
-      end
-
       # The configurations used to initialize self.app
       def app_config
         method_root.config.to_hash.merge(:quiet => true, :debug => true)