tap 0.11.1 → 0.12.0

data/lib/tap/tasks/dump.rb

@@ -11,9 +11,9 @@ module Tap
     #  
     #   % tap run -- [tasks] --+ dump FILEPATH
     #
-    # See Tap::Load for more details.
+    # See 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
@@ -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/tasks/load.rb

@@ -1,27 +1,27 @@
-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]
+module Tap
+  module Tasks
+    # :startdoc::manifest the default load task
     #
-    # Load can select items from Hash or Array objects using one or
-    # more keys when only a subset is desired.  By default items are
-    # selected using [].  For more flexible selection, use match.
+    # Load YAML-formatted data, as may be produced using 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]
+    #
+    # Load can select items from Hash or Array objects using one or more keys
+    # when only a subset is desired.  By default items are selected using [].
+    # For more flexible selection, use match.
     # 
-    # Match converts each of the keys to a Regexp.  For hashes, all
-    # values with a matching key will be selected.  For arrays, any
-    # item matching a regexp will be selected.
+    # Match converts each of the keys to a Regexp.  For hashes, all values
+    # with a matching key will be selected.  For arrays, any item matching
+    # a regexp will be selected.
     #
-    # Use the flags to flatten, compact, sort (etc) results before
-    # passing them on to the next task.
+    # Use the flags to flatten, compact, sort (etc) results before passing
+    # them on to the next task.
     class Load < Tap::Task
       
       config :match, false, :short => :m, &c.switch      # match keys
-      config :flatten, false, :short => :f, &c.switch    # flatten results
+      config :flatten, false, :short => :f, &c.switch    # flatten results
       config :compact, false, :short => :c, &c.switch    # compact results
       config :unique, false, :short => :u, &c.switch     # uniq results
       config :sort, false, :short => :s, &c.switch       # sort results
@@ -54,13 +54,13 @@ module Tap
       # 
       def process(input, *keys)
         
-        # load the input
-        obj = case input
+        # load the input
+        obj = case input
         when StringIO, IO
-          YAML.load(input.read)
-        else
-          log :load, input
-          YAML.load_file(input)
+          YAML.load(input.read)
+        else
+          log :load, input
+          YAML.load_file(input)
         end
         
         # select results by key
@@ -87,7 +87,7 @@ module Tap
           #puts results.inspect
         #end
         
-        results
+        results
       end
       
       protected
@@ -106,7 +106,7 @@ module Tap
         else
           raise ArgumentError, "cannot match keys from a #{obj.class}"
         end
-      end
-    end 
-  end
-end
+      end
+    end 
+  end
+end

data/lib/tap/test.rb

@@ -1,64 +1,77 @@
-require 'test/unit'
 $:.unshift File.expand_path("#{File.dirname(__FILE__)}/..")
 require 'tap/test/extensions'
+require 'test/unit'
 
-module Test # :nodoc:
-  module Unit # :nodoc:
-    
-    # Methods extending TestCase. For more information see:
-    # - Tap::Test::SubsetTest
-    # - Tap::Test::FileTest
-    # - Tap::Test::TapTest
-    #   
-    #--
-    #See the TestTutorial for more information.
-    class TestCase
-      extend Tap::Test::Extensions
-      
-      class << self
-        alias tap_original_test_case_inherited inherited
-        
-        def inherited(child)
-          super
-          tap_original_test_case_inherited(child)
-          child.instance_variable_set(:@skip_messages, [])
-          child.instance_variable_set(:@run_test_suite, true)
-        end
-        
-        # 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
+# :stopdoc:
+# Methods extending TestCase. For more information see:
+# - Tap::Test::SubsetTest
+# - Tap::Test::FileTest
+# - Tap::Test::TapTest
+#   
+#--
+#See the TestTutorial for more information.
+class Test::Unit::TestCase
+  extend Tap::Test::Extensions
 
-        # 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.
-        def skip_test(msg=nil)
-          self.run_test_suite = false
+  class << self
+    # 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.
+    def skip_test(msg=nil)
+      @@test_suites.delete(self)
+      puts "Skipping #{self}#{msg.empty? ? '' : ': ' + msg}"
+    end
+  end
+end
 
-          # experimental -- perhaps use this so that a test can be skipped
-          # for multiple reasons?
-          skip_messages << msg
-        end
+class Test::Unit::TestCase
+  class << self
+    alias tap_original_test_case_inherited inherited
+    
+    def inherited(child)
+      super
+      tap_original_test_case_inherited(child)
+      child.instance_variable_set(:@skip_messages, [])
+      child.instance_variable_set(:@run_test_suite, true)
+    end
+    
+    # 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
+    
+    undef_method :skip_test
+    
+    def skip_test(msg=nil)
+      self.run_test_suite = false
+      skip_messages << msg
+    end
+    
+    alias :original_suite :suite
 
-        alias :original_suite :suite
+    # 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(', ')
+        puts "Skipping #{name}#{skip_message.empty? ? '' : ': ' + skip_message}"
 
-        # 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(', ')
-            puts "Skipping #{name}#{skip_message.empty? ? '' : ': ' + skip_message}"
-            
-            # return an empty test suite of the appropriate name
-            Test::Unit::TestSuite.new(name)
-          end
-        end
+        # return an empty test suite of the appropriate name
+        Test::Unit::TestSuite.new(name)
       end
     end
   end
+end unless Object.const_defined?(:MiniTest)
+
+if Object.const_defined?(:MiniTest)
+  # MiniTest renames method_name name, so it has to be added back here.
+  class MiniTest::Unit::TestCase
+    undef_method :method_name if method_defined?(:method_name)
+    alias method_name name
+  end
 end
+# :startdoc:

data/lib/tap/test/env_vars.rb

@@ -6,10 +6,10 @@ module Tap
       
       # Access to the case-insensitive ENV variables.  Raises an error
       # if multiple case-insensitive values are defined in ENV.
-      def env(type)
+      def env_var(type)
         type = type.downcase
         
-        # ruby 1.9 returns a hash instead of an array
+        # ENV.select in ruby 1.9 returns a hash instead of an array
         selected = ENV.select {|key, value| key.downcase == type}.to_a
         
         case selected.length
@@ -22,7 +22,7 @@ module Tap
       
       # Returns true if the env_var(var) is set and matches /^true$/i
       def env_true?(var)
-        (env(var) && env(var) =~ /^true$/i) ? true : false
+        (env_var(var) && env_var(var) =~ /^true$/i) ? true : false
       end
     end
   end

data/lib/tap/test/extensions.rb

@@ -1,8 +1,4 @@
 module Tap
-  
-  # Modules facilitating testing.  TapTest are specific to
-  # Tap, but SubsetTest and FileTest are more general in 
-  # their utility.
   module Test
     autoload(:SubsetTest, 'tap/test/subset_test')
     autoload(:FileTest, 'tap/test/file_test')
@@ -16,8 +12,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 +22,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 +38,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,136 +54,89 @@ 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)
+        self.class.class_test_root or raise "setup failure: no class_test_root has been set for #{self.class}"
       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)
         unless method_root
-          raise "teardown failure: method_root is nil"
+          raise "teardown failure: method_root is nil (check a class_test_root has been set and ensure setup calls super)"
         end
         
         # clear out the output folder if it exists, unless flagged otherwise
-        unless env("KEEP_OUTPUTS") || (!@test_passed && env("KEEP_FAILURES"))
+        unless env_var("KEEP_OUTPUTS") || (!passed? && env_var("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