tap 0.7.9

data/lib/tap/test.rb

@@ -0,0 +1,320 @@
+require 'test/unit'
+require 'tap/test/inference_methods'
+require 'tap/test/subset_methods'
+
+module Test # :nodoc:
+  module Unit # :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
+        #
+        # 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.
+        def acts_as_tap_test(options={})
+          options = {:root => infer_root}.merge(options.symbolize_keys)
+          acts_as_inference_test(options)
+          
+          include Tap::Test::SubsetMethods
+          include Tap::Test::InstanceMethods
+        end
+      end
+    end
+  end
+end
+
+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.
+    class AuditStack
+      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
+
+    module InstanceMethods
+      attr_accessor  :runlist
+
+      # 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
+      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
+      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)
+        hash.each_pair do |task, expected|
+          inputs = task.results.collect { |r| r._input_last(task) }
+          assert_equal expected, inputs
+        end    
+      end
+
+      # Recieves a hash of results => [index, expected] pairs.  Asserts that the task result
+      # inputs at the specified index are equal to the expected inputs.
+      def assert_inputs_by_index(results, hash)
+        hash.each_pair do |index, expected|
+          assert_equal expected, results.collect {|r| r._input(index)}
+        end    
+      end
+    
+      # Recieves a hash of task => expected pairs.  Asserts that the last outputs for
+      # each task are equal to the expected outputs.
+      def assert_outputs(hash)
+        hash.each_pair do |task, expected|
+          outputs = task.results.collect { |r| r._output_last(task) }
+          assert_equal expected, outputs
+        end    
+      end
+    
+      # Recieves a hash of results => [index, expected] pairs.  Asserts that the result
+      # outputs at the specified index are equal to the expected outputs.
+      def assert_outputs_by_index(results, hash)
+        hash.each_pair do |index, expected|
+          assert_equal expected, results.collect {|r| r._output(index)}
+        end    
+      end
+
+      # Recieves an array of audits and a hash of [index, expected_audit] pairs.  Asserts that 
+      # the collection of all [source, value] pairs in the indexed audit matches the corresponding
+      # pairs provided in expected_audit.
+      #
+      # Example:
+      #   a0 = Audit.new('')
+      #   a1 = Audit.new('')
+      #   a1.record(:a, 'a')
+      #   a1.record(:b, 'b')
+      #
+      #   assert_audits([a0, a1], 1 => [[nil, ''], [:a, 'a'], [:b, 'b']]) # => true
+      #
+      # Note that since task results are an array of audits:
+      #    t.results # if => [a0, a1]
+      #    assert_audits(t1.results, 1 => [[nil, ''], [:a, 'a'], [:b, 'b']]) # then => true
+      #
+      def assert_audits(audits, hash)
+        hash.each_pair do |i, expected|
+          audit = audits[i]
+          raise ArgumentError.new("No audit provided at index: #{i}") if audit.nil?
+        
+          actual = [collect_object_ids(audit._source_trail), audit._values].transpose
+          expected = expected.transpose
+          expected[0] = collect_object_ids(expected[0])
+          expected = expected.transpose
+          assert_equal expected, actual, "Unexpected audit for result #{i}.\nAudits displayed as: [[source.object_id, value]]"
+        end
+      end
+    
+      def check_audit(audit, &block)
+        raise "Cannot check audit.  Public method ':_from' already defined for Object." if Object.public_method_defined?(:_from)
+
+        begin
+          audit_stack = AuditStack.new(self)
+          audit_stack.load_audit(audit)
+        
+          # Define the :from testing method.  Defining this method on Object is good for syntax, 
+          # but generally a bad practice.  Hence, the method is undefined immediately after the
+          # test block completes.  
+          #
+          # The from method assumes the object itself is the expected value, and that the expected 
+          # source is given as an argument.  If a block is given to from, that indicates that the value
+          # is the result of a merge -- the block must contain the checks to assert the origins of the
+          # merge value.
+          Object.class_eval %Q{
+            def _from(expected_source=nil, &block)
+              audit_stack = ObjectSpace._id2ref(#{audit_stack.object_id})
+              source, value = audit_stack.next
+
+              if block_given?
+                audit_stack.test.assert_equal Array, source.class, "Expected source from merge."
+                [source, value].transpose.reverse_each do |source, value| 
+                  source.kind_of?(Tap::Support::Audit) ?
+                    audit_stack.load_audit(source) :
+                    audit_stack.load(source, value)
+                end
+                yield
+                source, value = audit_stack.next
+              end  
+        
+              audit_stack.test.assert_equal self, value, "Wrong audit value (be sure your checks are in the correct order)"
+              audit_stack.test.assert_equal expected_source.object_id, source.object_id, PP.singleline_pp(value, "Wrong source id for value: ")
+            end}
+      
+          yield
+        ensure
+          Object.class_eval %Q{remove_method(:_from)} if Object.public_method_defined?(:_from)
+        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 = {}
+        begin
+          options.each_pair do |op, val|
+            hold[op] = app.options.send(op)
+            app.options.send("#{op}=", val)
+          end
+          
+          yield block if block_given?
+        ensure
+          hold.each_pair { |op, val| app.options.send("#{op}=", val) }
+        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?
+        
+          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
+        
+          # 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
+          end
+        end
+      end
+    
+      private    
+    
+      def collect_object_ids(array)
+        array.collect do |s|
+          s.kind_of?(Array) ? collect_object_ids(s) : s.object_id
+        end
+      end
+    end
+  end
+end
+
+
+
+

data/lib/tap/test/env_vars.rb

@@ -0,0 +1,16 @@
+module Tap
+  module Test
+    module EnvVars
+      
+      # Access to the case-insensitive ENV variables
+      def env(type)
+        type = type.downcase
+        ENV.each_pair do |key, value|
+          return value if key.downcase == type
+        end
+        nil
+      end
+      
+    end
+  end
+end

data/lib/tap/test/inference_methods.rb

@@ -0,0 +1,298 @@
+require 'tap/root'
+require 'test/unit'
+require 'active_support'
+require 'tap/test/env_vars'
+
+module Test # :nodoc:
+  module Unit # :nodoc:
+    class TestCase
+      class << self
+        
+        # Causes a unit test to act as an io test -- resulting in the following:
+        # - Definition of an Tap::Root object
+        # - Tap::Test::InferenceMethods are included, providing methods to easily access 
+        # files according to a standard file structure.
+        #
+        # Note:  Unless otherwise specified, +acts_as_io_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_io_test+ from a file that is NOT your test file.
+        def acts_as_inference_test(options={})
+          options = {
+            :root => infer_root,
+            :directories => {}, 
+            :keep_outputs => false,
+            :keep_failures => false}.merge(options.symbolize_keys)
+
+          # declare the testing directory structure
+          directories = default_directories.merge(options[:directories])
+          ifs = Tap::Root.new(options[:root], directories)
+    
+          write_inheritable_attribute(:ifs,  ifs)
+          class_inheritable_reader :ifs
+      
+          write_inheritable_attribute(:options,  options)
+          class_inheritable_reader :options
+      
+          include Tap::Test::InferenceMethods
+        end
+
+        # The default directories for an io test:
+        #
+        #  :input => 'input'
+        #  :output => 'output'
+        #  :expected => 'expected'
+        #  :fail => 'fail'
+        def default_directories
+          {:input => 'input', :output => 'output', :expected => 'expected', :fail => 'fail'}
+        end
+    
+        # Infers the root directory from the calling file by chomping the extension and '_test'.  Ex:
+        #   'some_class.rb' => 'some_class'
+        #   'some_class_test.rb' => 'some_class'
+        def infer_root
+          # the calling file is not the direct caller of +infer_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  
+    module InferenceMethods
+      include Tap::Test::EnvVars
+      
+      def method_name
+        @method_name
+      end
+  
+      # Convenience accessor for the inference structure
+      def ifs
+        self.class.ifs
+      end
+    
+      # Convenience accessor for the class options
+      def options
+        self.class.options
+      end
+  
+      def make_directory_structure
+        ifs.directories.values.each do |dir| 
+          FileUtils.mkdir_p(File.join(ifs.root, method_name, dir))
+        end
+      end
+    
+      # Teardown deletes the output and fail 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:
+      #
+      #   %rake test KEEP_OUTPUTS=true
+      #   %rake test KEEP_FAILURES=true
+      def teardown
+        # clear out the output folder if it exists, unless flagged otherwise
+        output_dir = infer_dir(:output, method_name)
+        unless !File.exists?(output_dir) || options[:keep_outputs] || env("KEEP_OUTPUTS")
+          begin
+            FileUtils.rm_r output_dir
+          rescue
+            raise("teardown failure: could not remove output files")
+          end
+        end
+      
+        # clear out the fail folder if it exists, unless flagged otherwise
+        fail_dir = infer_dir(:fail, method_name)
+        unless !File.exists?(fail_dir) || options[:keep_failures] || env("KEEP_FAILURES")
+          begin
+            FileUtils.rm_r fail_dir
+          rescue
+            raise("teardown failure: could not remove fail files")
+          end
+        end
+      
+        # Remove the directory if possible
+        begin
+          dir = ifs.filepath(method_name)
+          if File.exists?(dir) && Dir.glob(File.join(dir, "*")).empty?
+            FileUtils.rmdir dir 
+          end
+        rescue
+          # rescue cases where there is a hidden file, for example .svn
+        end
+      end 
+
+      def infer_root(method=method_name)
+        ifs.filepath(method)
+      end
+
+      # The method directory is defined as 'dir/method', where method is the calling method
+      # by default.  infer_dir returns the method directory if it exists, otherwise it returns
+      # ifs[dir].
+      def infer_dir(dir, method=method_name)
+        File.join(infer_root(method), ifs.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>ifs[dir]</tt> directory.
+      def infer_glob(dir, *patterns)
+        dir = ifs.relative_filepath(:root, infer_dir(dir))
+        ifs.glob(dir, *patterns) 
+      end
+    
+      # Returns a filepath constructed from the method directory if it exists, 
+      #  otherwise the filepath will be constructed from <tt>ifs[dir]</tt>. 
+      def infer_filepath(dir, *filenames)
+        File.join(infer_dir(dir), *filenames)
+      end
+    
+      # Removes the method directory from the input filepath, returning the resuting filename.
+      # If the method directory does not exist, <tt>ifs[dir]</tt> will be removed.
+      def infer_relative_filepath(dir, filepath)
+        dir = ifs.relative_filepath(:root, infer_dir(dir))
+        ifs.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 infer_translate(filepath, input_dir, output_dir)
+        input_dir = ifs.relative_filepath(:root, infer_dir(input_dir))
+        output_dir = ifs.relative_filepath(:root, infer_dir(output_dir))
+        ifs.translate(filepath, input_dir, output_dir)
+      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
+    
+      # Copies the output file to the :fail directory if no block is given, or if the
+      # given block returns true or raises an error.  Segregate file assumes the output 
+      # file is in the :output directory and determines the final filepath by using 
+      # the +translate+ method.
+      #
+      # If the block raises an error, then the error will be re-raised after the
+      # segregation.
+      def segregate_file(output_file, &block)
+        begin
+          segregate = block_given? ? yield(output_file) : true
+        rescue
+          segregate = true
+          error = $!
+        ensure
+          if segregate
+            target = infer_translate(output_file, :output, :fail)
+          
+            dirname = File.dirname(target)
+            FileUtils.mkdir_p(dirname) unless File.exists?(dirname)
+            FileUtils.cp(output_file, target)
+          
+            # re-raise the error for further handling
+            raise $! if error
+          end
+        end
+      end
+    
+      #
+      def assert_expected(*expected_files, &block)
+        errors = []
+      
+        check_all_files = expected_files.empty?
+        if check_all_files
+          expected_files = infer_glob(:expected) 
+          begin
+            output_files = infer_glob(:output)
+          
+            efl = expected_files.collect { |file| infer_relative_filepath(:expected, file) }
+            ofl = output_files.collect { |file| infer_relative_filepath(:output, file) }
+          
+            unless efl == ofl 
+              raise "Inconsistent globs.\nexpected: #{PP.singleline_pp(efl, '')}\nbut was:  #{PP.singleline_pp(ofl, '')}\n"  
+            end
+          rescue
+            errors << $!.message
+          end
+        end
+      
+        expected_files.each do |expected_file|
+          begin
+            output_file = infer_translate(expected_file, :expected, :output)
+        
+            raise "Expected output file does not exist: #{output_file}" unless File.exists?(output_file)
+          
+            segregate_file(output_file) do |output_file|
+              pass = block_given? ? yield(expected_file, output_file) : files_equal?(expected_file, output_file)
+              !pass
+            end unless File.directory?(output_file)
+          rescue
+            errors << $!.message
+          end
+        end
+      
+        unless errors.empty?
+          flunk errors.join("\n")
+        end
+      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
+
+      private
+    
+      def make_tmpname(basename, n, ext="")
+        infer_filepath(:output, sprintf('%s%d.%d%s', basename, $$, n, ext))
+      end
+    end
+  end
+end