tap 0.7.9 → 0.8.0

data/lib/tap/test.rb

@@ -1,5 +1,5 @@
 require 'test/unit'
-require 'tap/test/inference_methods'
+require 'tap/test/file_methods'
 require 'tap/test/subset_methods'
 
 module Test # :nodoc:
@@ -7,21 +7,21 @@ module Test # :nodoc:
     class TestCase
       class << self
         # Causes a unit test to act as a tap test -- resulting in the following:
-        # - setup of the test as an io_test (see documentation)
-        # - TapTest::InstanceMethods are included, providing methods to easily run
-        # tap tasks and test their outputs
+        # - setup using acts_as_file_test
+        # - inclusion of Tap::Test::SubsetMethods
+        # - inclusion of Tap::Test::InstanceMethods 
         #
         # Note:  Unless otherwise specified, +acts_as_tap_test+ infers a root directory
-        # based on the calling file.  Therefore, to keep your directory structure from 
-        # referencing an unexpected locations, be sure to specify the root directory
-        # explicitly if you call +acts_as_tap_test+ from a file that is NOT your test file.
+        # 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.
         def acts_as_tap_test(options={})
-          options = {:root => infer_root}.merge(options.symbolize_keys)
-          acts_as_inference_test(options)
+          options = {:root => file_test_root}.merge(options.symbolize_keys)
+          acts_as_file_test(options)
           
           include Tap::Test::SubsetMethods
           include Tap::Test::InstanceMethods
         end
+        
       end
     end
   end
@@ -29,13 +29,13 @@ end
 
 module Tap
   
-  #
+  # == UNDER CONSTRUCTION
   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.
-    class AuditStack
+    class AuditStack # :nodoc:
       attr_reader :test
     
       def initialize(test)
@@ -58,70 +58,21 @@ module Tap
       end
     end
 
-    module InstanceMethods
-      attr_accessor  :runlist
+    module InstanceMethods # :nodoc:
 
       # Setup clears the test using clear_tasks and assures that Tap::App.instance 
       # is the test-specific application.
       def setup
         super
         Tap::App.instance = app
-        clear_runlist
+        app.queue.clear
       end
   
       # Returns the test-specific application.
       def app 
-        @app ||= Tap::App.new(:root => ifs.root, :directories => ifs.directories)
-      end
-
-      # Clears all declared tasks, sets the application trace option to false, makes directories (if flagged
-      # and as needed), and clears the runlist.
-      def clear_runlist
-        # clear the attributes
-        @runlist = []
-      end
-  
-      # A tracing procedure.  echo adds input to runlist then returns input.
-      def echo
-        lambda do |task, input| 
-          @runlist << input
-          input
-        end
+        @app ||= Tap::App.new(:root => trs.root, :directories => trs.directories)
       end
     
-      # A tracing procedure for numeric inputs.  add_one adds the input to 
-      # runlist then returns input + 1.
-      def add_one
-        lambda do |task, input| 
-          @runlist << input
-          input += 1
-        end
-      end
-    
-      # A convenience testing method asserting that runlist array is equal to the inputs
-    #  def assert_runlist(*expected)
-    #    assert_equal expected, runlist
-    #  end    
-      
-      # A convenience testing method asserting that sorted runlist array is equal to the
-      # sorted inputs.  Sorting the runlist is unpreferred, because you lose information about
-      # the order of items added to the runlist.  
-      # 
-      # However, at times there is no good alternative because the order of execution
-      # may be determined by a hash.  
-    #  def assert_sorted_runlist(*expected)
-        # two-step in case the elements cannot be sorted (as in the case of hashes)
-    #    found_all = (expected.length == runlist.length)
-    #    expected.each do |e| 
-    #      break unless found_all
-          
-    #      next if runlist.include?(e)
-    #      found_all = false
-    #    end
-        
-    #    assert found_all, "Expected: #{PP.pp(expected, '')}Was: #{PP.pp(runlist, '')}"
-    #  end
-
       # Recieves a hash of task => expected pairs.  Asserts that the last inputs for
       # each task are equal to the expected inputs.
       def assert_inputs(hash)
@@ -226,80 +177,87 @@ module Tap
         end
       end
 
-      # Executes the block having applied the specified options to app.
-      # Ensures that current options values are restored to app after 
-      # the block completes or raises an error.
-      def with_options(options, app=self.app, &block)
-        hold = {}
+      # Applies the input options to the specified app for the duration
+      # of the block.  Unless merge_with_existing is false, the input
+      # options will be merged with the existing options; otherwise
+      # the app options will be reconfigured to just the inputs.
+      #
+      #  app = Tap::App.new(:options => {:one => 1, :two => 2})
+      #
+      #  with_options({:one => 'one'}, app) do 
+      #    app.options.marshal_dump     # => {:one => 'one', :two => 2}
+      #  end
+      #  app.options.marshal_dump      # => {:one => 1, :two => 2}
+      #
+      def with_options(options, app=self.app, merge_with_existing=true, &block)
+        app_config = {:options => options}
+        with_config(app_config, app, merge_with_existing, &block)
+      end
+      
+      # Applies the input configurations to the specified app for the 
+      # duration of the block.  Unless merge_with_existing is false,
+      # the input configurations will be merged with the existing 
+      # configurations; otherwise the app will be reconfigured to 
+      # using the inputs as specified.
+      #
+      #  app = Tap::App.new(:directories => {:dir => 'dir', :alt => 'alt_dir'})
+      #  tmp_config = {
+      #    :directories => {:alt => 'another', :new => 'new_dir'},
+      #    :options => {:one => 1}}
+      #
+      #  with_config(tmp_config, app) do 
+      #    app.directories              # => {:dir => 'dir', :alt => 'another', :new => 'new_dir'}
+      #    app.options.marshal_dump     # => {:one => 1}
+      #  end
+      #  app.directories                # => {:dir => 'dir', :alt => 'alt_dir'}
+      #  app.options.marshal_dump       # => {}
+      #
+      def with_config(app_config, app=self.app, merge_with_existing=true, &block)
         begin
-          options.each_pair do |op, val|
-            hold[op] = app.options.send(op)
-            app.options.send("#{op}=", val)
+          hold = app.config
+          if merge_with_existing
+            hold.each_pair do |key, value|
+              next unless app_config.has_key?(key)
+              next unless value.kind_of?(Hash)
+                
+              app_config[key] = value.merge(app_config[key])
+            end
           end
-          
+          app.reconfigure(app_config)
+
           yield block if block_given?
         ensure
-          hold.each_pair { |op, val| app.options.send("#{op}=", val) }
+          app.reconfigure(hold)
         end
       end
-    
-      def file_task_test(task, options={})
-        make_directory_structure
-      
-        raise "Not a FileTask" unless task.kind_of?(Tap::FileTask)
-      
-        options = {
-          :input_files => nil,
-          :expected_files => nil,
-          :strict => true#,
-          #:set_dirname => true
-        }.merge(options)
-      
-        input_files = options.delete(:input_files)
-        input_files = [input_files] unless input_files.nil? || input_files.kind_of?(Array)
-      
-        expected_files = options.delete(:expected_files)
-        expected_files = [expected_files] unless expected_files.nil? || expected_files.kind_of?(Array)
       
-        strict = options.delete(:strict)
-       # set_dirname = options.delete(:set_dirname)
-       
-        # redirect to infer_dir(:output)
-     
-        current_block = task.inference_block
-        task.inference(true) do |root, dir, path|
-          if current_block
-            current_block.call(infer_dir(:output), dir, path)
-          else
-            infer_filepath(:output, path)
-          end
-        end
-
-        with_options(options, task.app) do  
-         # task.dirname = infer_dir(:output) if set_dirname
-         
-          input_files = infer_glob(:input) if input_files.nil?
-          flunk "No input files specified." if input_files.empty?
-
-          output_files = task.execute(*input_files).collect {|a| a._current}
-          expected_files = infer_glob(:expected) if expected_files.nil?
+      # assert_expected_result_files runs the input task using the
+      # input app config, submitting all method input files for 
+      # processing.  the assertions returns true only if all the 
+      # expected and output files are equal.  As such it is very
+      # convenient for file transform tasks.  
+      #
+      # The default application config sets the app root to 
+      # method_root, silences execution and directs app[:data] to
+      # the method output directory.
+      #
+      # assert_expected_result_files makes the input/expected
+      # directories if they do not exist.  By default all the
+      # output files will be cleaned up during teardown. See
+      # FileMethods for more information.
+      def assert_expected_result_files(task, app_config={})
+        make_test_directories
         
-          if strict
-            # assure there are no missing or extra output files
-            assert_equal infer_glob(:output), output_files,  "Missing or extra output files" 
-
-            # check that the relative filepaths are the same
-            translated_files = output_files.collect {|file| infer_translate(file, :output, :expected)}
-            assert_equal expected_files, translated_files, "Missing or extra expected files"
-          else
-            assert_equal expected_files.length, output_files.length, "Missing or extra expected files"
-          end
+        app_config = {
+          :root => method_root,
+          :options => {:quiet => true}, 
+          :absolute_paths => {:data => method_filepath(:output)}
+        }.merge(app_config)
         
-          # check that the expected and output files are equal
-          0.upto(expected_files.length-1) do |i|
-            unless FileUtils.compare_file(expected_files[i], output_files[i])
-              flunk "File compare failed:\n<#{expected_files[i]}> not equal to\n<#{output_files[i]}>"
-            end
+        with_config(app_config, task.app) do
+          assert_output_files_equal do |input_files|
+            output_files = task.execute(*input_files).collect {|a| a._current}
+            block_given? ? yield(output_files) : output_files
           end
         end
       end

data/lib/tap/test/env_vars.rb

@@ -1,16 +1,27 @@
 module Tap
   module Test
+    
+    # Provides a method for case-insensitive access to the ENV variables
     module EnvVars
       
-      # Access to the case-insensitive ENV variables
+      # Access to the case-insensitive ENV variables.  Raises an error
+      # if multiple case-insensitive values are defined in ENV.
       def env(type)
         type = type.downcase
-        ENV.each_pair do |key, value|
-          return value if key.downcase == type
+        selected = ENV.select {|key, value| key.downcase == type}
+        
+        case selected.length
+        when 0 then nil
+        when 1 then selected[0][1]
+        else
+          raise "Multiple env values for '#{type}'" 
         end
-        nil
       end
-      
+      
+      # Returns true if the env_var(var) is set and matches /^true%/i
+      def env_true?(var)
+        env(var) && env(var) =~ /^true$/i
+      end
     end
   end
 end

data/lib/tap/test/file_methods.rb

@@ -0,0 +1,373 @@
+require 'tap/root'
+require 'tap/test/env_vars'
+require 'test/unit'
+require 'fileutils'
+
+module Test # :nodoc:
+  module Unit # :nodoc:
+    # Methods extending TestCase.  See the TestTutorial for more information.
+    class TestCase
+      class << self
+        
+        # Causes a TestCase to act as a file test, by instantiating a class Tap::Root 
+        # (trs), and including the FileMethods.  The root and directories used to 
+        # instantiate trs can be specified as options.  By default file_test_root
+        # and default_directories will be used.
+        #
+        #   class FileDependentTest < Test::Unit::TestCase
+        #     acts_as_file_test(:root => file_test_root, :directories => default_directories)
+        #   end
+        #
+        # Note: file_test_root determines 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.
+        def acts_as_file_test(options={})
+          options = {
+            :root => file_test_root,
+            :directories => {}
+          }.merge(options.symbolize_keys)
+
+          directories = default_directories.merge(options[:directories])
+          trs = Tap::Root.new(options[:root], directories)
+    
+          write_inheritable_attribute(:trs, trs)
+          class_inheritable_reader :trs
+      
+          include Tap::Test::FileMethods
+        end
+
+        # The default directories for a file test:
+        #
+        #  :input => 'input'
+        #  :output => 'output'
+        #  :expected => 'expected'
+        def default_directories
+          {:input => 'input', :output => 'output', :expected => 'expected'}
+        end
+    
+        # Infers the test root directory from the calling file.  Ex:
+        #   'some_class.rb' => 'some_class'
+        #   'some_class_test.rb' => 'some_class'
+        def file_test_root
+          # the calling file is not the direct caller of +method_root+... this method is 
+          # only accessed from within another method call, hence the target caller is caller[1] 
+          # rather than caller[0].
+      
+          # 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)}") 
+          calling_file.chomp("_test") 
+        end
+      end
+    end
+  end
+end
+
+module Tap
+  module Test  
+    
+    # == Under Construction
+    #
+    # FileMethods sets up a TestCase with methods for accessing and utilizing
+    # test-specific files and directories.  Each class including FileMethods
+    # is set up with a Tap::Root structure (trs) that mediates the creation of 
+    # test method filepaths.  FileMethods extends TestCase with the 
+    # acts_as_file_test to include the FileMethods and initialize the trs. 
+    #
+    #   class FileDependentTest < Test::Unit::TestCase
+    #     acts_as_file_test
+    #
+    #     def test_file_transform
+    #       trs.root                # => "."
+    #       method_root             # => "./file_dependent_test/test_file_transform"
+    #       method_dir(:input)      # => "./file_dependent_test/test_file_transform/input"
+    #     end
+    #   end
+    #
+    # == File Transform Tests
+    #
+    # 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_output_files_equal 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.
+    #
+    #   class FileTest < Test::Unit::TestCase
+    #     acts_as_file_test
+    #
+    #     def test_transform
+    #       assert_output_files_equal do |input_files|
+    #         input_files.collect do |filepath|
+    #           input = File.read(filepath)
+    #           output_file = method_filepath(:ouput_files, File.basename(filepath))
+    #
+    #           File.open(output_file, "w") do |f|
+    #             f << input.gsub(/input/, "output")
+    #           end 
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # Now make some input and expected files for the 'test_transform' method:
+    #
+    #   FileUtils.mkdir_p("file_test/test_transform/input_files")
+    #   FileUtils.mkdir_p("file_test/test_transform/expected_files")
+    #   
+    #   [file_one.txt", file_two.txt"].each_with_index do |basename, i|
+    #     input = "file_test/test_transform/input_files/" + basename
+    #     File.open(input, "w") {|f| f << "test input #{i}"}
+    #
+    #     expected = "file_test/test_transform/expected_files/" + basename
+    #     File.open(expected, "w") {|f| f << "test output #{i}"}
+    #   end
+    #
+    # When you run the FileTest tests, the test_transform test will pass
+    # the existing input_files to the assert_output_files_equal block.  The
+    # block makes output files in "file_test/test_transform/output_files",
+    # and then assert_output_files_equal compares the files and finds they
+    # are equal.  As a result the test passes.
+    #
+    # The test fails if you alter the expected file contents, add/remove
+    # expected files, or in some other way make these files unequal.  
+    #
+    # When the test completes, the default teardown method will clean up the
+    # output_files 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 easily be specified from the command line when running a rake task:
+    #
+    #   % tap run test keep_failures=true
+    #
+    module FileMethods
+      include Tap::Test::EnvVars
+  
+      # Convenience accessor for the test root structure
+      def trs
+        self.class.trs
+      end
+    
+      # Creates the trs.directories, specific to the method calling make_test_directories
+      def make_test_directories
+        trs.directories.values.each do |dir| 
+          FileUtils.mkdir_p( File.join(trs.root, method_name, dir) )
+        end
+      end
+      
+      # 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.
+      def setup
+        super
+        clear_method_dir(:output)
+        try_remove_dir(method_root)
+      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:
+      #
+      #   % tap run test KEEP_OUTPUTS=true
+      #   % tap run test KEEP_FAILURES=true
+      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) 
+          rescue
+            raise("teardown failure: could not remove output files")
+          end
+        end
+        
+        try_remove_dir(method_root)
+        try_remove_dir(trs.root)
+      end 
+
+      # The method_root directory is defined as trs.filepath(method_name)
+      def method_root(method=method_name)
+        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)
+        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.  
+      #
+      # 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)
+        FileUtils.rm_r(dir_path) if File.exists?(dir_path)
+      end
+      
+      # Attempts to remove the specified directory.  The root 
+      # will not be removed if the directory does not exist, or
+      # is not empty.  
+      def try_remove_dir(dir)
+        # Remove the directory if possible
+        begin
+          FileUtils.rmdir(dir) if File.exists?(dir) && Dir.glob(File.join(dir, "*")).empty?
+        rescue
+          # rescue cases where there is a hidden file, for example .svn
+        end
+      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.
+      #
+      # 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
+      def tempfile(filename=method_name)
+        n = 0
+        ext = File.extname(filename)
+        basename = filename.chomp(ext)
+        filepath = make_tmpname(basename, n, ext)
+        while File.exists?(filepath)
+          n += 1
+          filepath = make_tmpname(basename, n, ext)
+        end
+      
+        dirname = File.dirname(filepath)
+        FileUtils.mkdir_p(dirname) unless File.exists?(dirname)
+        filepath
+      end
+    
+      # Asserts that each pair of input files are equal, using FileUtils.cmp.
+      def files_equal?(a, b)
+        FileUtils.cmp(a, b)
+      end
+    
+      # Asserts that each pair of input files produce an equivalent object when
+      # loaded as a yaml file. 
+      def yml_equal?(a, b)
+        YAML.load_file(a) == YAML.load_file(b)
+      end
+
+      # Yields to the input block for each pair of input files.  An error is raised
+      # if the input arrays do not have equal numbers of entries.
+      def each_pair(a, b, &block)
+        a = [a] unless a.kind_of?(Array)
+        b = [b] unless b.kind_of?(Array)
+      
+        raise ArgumentError, "The input arrays must have an equal number of entries." unless a.length == b.length
+        a.each_index do |index|
+          yield(a[index], b[index])
+        end
+      end
+      
+      def assert_output_files_equal(options={}) # :yields: input_files
+        make_test_directories
+        
+        options = {
+          :input_files => nil,
+          :expected_files => nil,
+          :require_expected_files => true,
+          :check_for_missing_outputs => true,
+          :iterate_inputs => false,
+          :include_directories => false
+        }.merge(options)
+        
+        # set or search for input and expected files, and arrayify
+        input_files, expected_files = [:input, :expected].collect do |key|
+          options_key = "#{key}_files".to_sym
+          
+          files = options.delete(options_key)
+          files = method_glob(key) if files.nil?
+          files = (files.kind_of?(Array) ? files : [files])
+          files.collect! {|file| File.expand_path(file) }
+          unless options[:include_directories]
+            files.delete_if {|file| File.directory?(file)} 
+          end
+          files
+        end
+  
+        flunk "No expected files were specfied." if options[:require_expected_files] && expected_files.empty?
+        
+        # create output files
+        output_files = if options[:iterate_inputs]
+          input_files.collect do |input_file|
+            yield(input_file)
+          end
+        else
+          yield(input_files)
+        end
+        output_files = output_files.flatten.collect {|file| File.expand_path(file) }
+        
+        if options[:check_for_missing_outputs]
+          expected_output_files = method_glob(:output)
+          unless options[:include_directories]
+            expected_output_files.delete_if {|file| File.directory?(file)} 
+          end
+          expected_output_files.collect! {|file| File.expand_path(file) }
+          
+          # assure there are no missing or extra output files
+          assert_equal expected_output_files, output_files,  "Missing or extra output files" 
+        end
+        
+        # check that the expected and output filepaths are the same
+        translated_files = output_files.collect {|file| method_translate(file, :output, :expected)}
+        translated_files.collect! {|file| File.expand_path(file) }
+        assert_equal expected_files, translated_files, "Missing or extra expected files"
+
+        # check that the expected and output file contents are equal
+        errors = []
+        each_pair(expected_files, output_files) do |expected_file, output_file|
+          unless files_equal?(expected_file, output_file)
+            errors << "<#{expected_file}> not equal to\n<#{output_file}>"
+          end
+        end
+        flunk "File compare failed:\n" + errors.join("\n") unless errors.empty?
+      end
+
+      private
+    
+      def make_tmpname(basename, n, ext="")
+        method_filepath(:output, sprintf('%s%d.%d%s', basename, $$, n, ext))
+      end
+    end
+  end
+end