tap 0.8.0 → 0.9.0

data/lib/tap/test/subset_methods.rb

@@ -5,7 +5,6 @@ require 'tap/test/env_vars'
 
 module Test # :nodoc:
   module Unit # :nodoc:
-    # Methods extending TestCase.  See the TestTutorial for more information.
     class TestCase 
       class << self
         include Tap::Test::EnvVars
@@ -16,7 +15,9 @@ module Test # :nodoc:
           subclass_conditions = conditions.inject({}) do |memo, (key, value)|
             memo.update(key => (value.dup rescue value))
           end
-          subclass.instance_variable_set("@conditions", subclass_conditions)
+          subclass.instance_variable_set(:@conditions, subclass_conditions)
+          subclass.instance_variable_set(:@run_test_suite, nil)
+          subclass.instance_variable_set(:@skip_messages, [])
           
       #    subclass_inputs = prompt_inputs.inject({}) do |memo, (key, value)|
       #      memo.update(key => (value.dup rescue value))
@@ -107,8 +108,8 @@ module Test # :nodoc:
         # true if no platforms are specified.
         #
         # Some common platforms:
-        # - mswin:: Windows
-        # - darwin:: Mac
+        #   mswin    Windows
+        #   darwin   Mac
         def match_platform?(*platforms)
           platforms.each do |platform|
             platform.to_s =~ /^(non_)?(.*)/
@@ -139,11 +140,11 @@ module Test # :nodoc:
         # 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)
-          @run_test_suite = false
+          self.run_test_suite = false
           
           # experimental -- perhaps use this so that a test can be skipped
           # for multiple reasons?
-          (@skip_messages ||= []) << msg unless msg.nil?
+          @skip_messages << msg unless msg.nil?
         end
 
         alias :original_suite :suite
@@ -153,7 +154,6 @@ module Test # :nodoc:
           if run_test_suite?
             original_suite
           else
-            @skip_messages ||= []
             puts "Skipping #{name}: #{@skip_messages.join(', ')}" unless @skip_messages.empty?
             Test::Unit::TestSuite.new(name)
           end
@@ -169,7 +169,7 @@ module Tap
     # Ideally you always run all of your tests and they all run and pass everywhere. In 
     # practice it's useful to suppress the execution of some tests -- long running tests, 
     # tests specific for a given platform, or tests that depend on some condition, such 
-    # as the version of some third-party software your code interacts with.
+    # as the version of some optional third-party software your code interacts with.
     # 
     # SubsetMethods extends TestCase with methods for defining conditions that can be 
     # used to conditionally perform some action, or skip a test suite entirely.  When 
@@ -185,54 +185,64 @@ module Tap
     #     condition(:non_windows) { match_platform?('non_mswin') }
     #   end
     # 
-    #   class AfterHoursTest < Test::Unit::TestCase
-    #     # only true between 6pm and 6am
-    #     # (maybe you're not allowed to tie up a computer until after hours)
-    #     condition(:afterhours) { Time.now > 18 || Time.now < 6 }
-    # 
-    #     skip_test unless satisfied?(:windows, :afterhours)
+    #   class WindowsOnlyTest < Test::Unit::TestCase
+    #     skip_test unless satisfied?(:windows)
     #   end
     # 
-    # AfterHoursTest will only run between the hours of 6pm and 6am, on a Windows platform.  
-    # These conditions can be used in specific tests, when only some tests need to be skipped.
+    # WindowsOnlyTest will only run on a Windows platform. These conditions can be used 
+    # in specific tests, when only some tests need to be skipped.
     # 
     #   class RunOnlyAFewTest < Test::Unit::TestCase
     #     include SubsetMethods
-    #     include Benchmark
     # 
     #     def test_runs_all_the_time
     #       assert true
     #     end
     # 
-    #     def test_runs_only_if_afterhours_condition_is_true
-    #       condition_test(:afterhours) do
-    #         ... 
+    #     def test_runs_only_if_non_windows_condition_is_true
+    #       condition_test(:non_windows) { assert true }
     #       end
     #     end
     # 
-    #     def test_runs_only_when_EXTENDED_is_true
-    #       extended_test do
-    #         ... 
-    #       end
+    #     def test_runs_only_when_ENV_variable_EXTENDED_is_true
+    #       extended_test { assert true }
     #     end
     # 
-    #     def test_runs_only_when_BENCHMARK_is_true
+    #     def test_runs_only_when_ENV_variable_BENCHMARK_is_true
     #       benchmark_test do |x|
     #         x.report("init speed") { 10000.times { Object.new } }
     #       end
     #     end
+    #
+    #     def test_runs_only_when_ENV_variable_CUSTOM_is_true
+    #       subset_test('CUSTOM') { assert true }
+    #     end
     #   end
     # 
-    # In the example, EXTENDED and BENCHMARK refer to environment (ENV) variables.
-    # ENV variables can be set from the command line like so:
+    # In the example, the ENV variables EXTENDED, BENCHMARK, and CUSTOM act as flags
+    # to run specific tests.  If you're running your test using Rake, ENV variables 
+    # can be set from the command line like so:
     # 
-    #   % tap run test extended=true
-    #   % tap run test BENCHMARK=true
+    #   % rake test EXTENDED=true
+    #   % rake test BENCHMARK=true
     # 
-    # In so far as SubsetMethods is concerned, the environment variables are case-insensitive.  
-    # To run all tests that get switched using an environment variable, set ALL=true.  
+    # Since tap can run rake tasks as well, these are equivalent:
     #
-    # == Class Methods
+    #   % tap run test EXTENDED=true
+    #   % tap run test BENCHMARK=true
+    #
+    # In so far as SubsetMethods is concerned, the environment variables are 
+    # case-insensitive.  As in the example, additional ENV-variable-dependent 
+    # tests can be defined using the subset_test method. To run all tests that  
+    # get switched using an environment variable, set ALL=true.  
+    #
+    #   # also runs benchmark tests
+    #   % tap run test BenchMark=true
+    #
+    #   # runs all tests
+    #   % tap run test all=true
+    #
+    # === Class Methods
     # 
     # See Test::Unit::TestCase for documentation of the class methods added by SubsetMethods
     module SubsetMethods
@@ -247,13 +257,14 @@ module Tap
         self.class.run_subset?(type)
       end
 
-      # Returns true if the pretty-print string for obj matches the regexp specified in env_var(type).
-      # Returns the default value if 'ALL' is specified in ENV or type is not specified in ENV.  
-      def match_regexp?(type, obj, default=true)
+      # Returns true if the input string matches the regexp specified in 
+      # env_var(type). Returns the default value if 'ALL' is specified in
+      # ENV or type is not specified in ENV.  
+      def match_regexp?(type, str, default=true)
         return true if env_true?("ALL")
         return default unless env(type)
     
-        PP.singleline_pp(obj, '') =~ Regexp.new(env(type)) ? true : false
+        str =~ Regexp.new(env(type)) ? true : false
       end
 
       # Platform-specific test.  Useful for specifying test that should only 
@@ -298,16 +309,47 @@ module Tap
       end
       
       # Basic method for a subset test.  The provided block will run if:
-      #   - The subset type or 'ALL' is specified in ENV
-      #   - The calling method matches the regexp provided in the "TYPE_TEST" ENV variable
+      # - The subset type is specified in ENV
+      # - The subset 'ALL' is specified in ENV
+      # - The test method name matches the regexp provided in the <TYPE>_TEST ENV variable
       #  
-      # Otherwise the block will be skipped and +skip+ will be printed.  By default skip
-      # is the first letter of +type+.
+      # Otherwise the block will be skipped and +skip+ will be printed in the test output.  
+      # By default skip is the first letter of +type+.
+      #
+      # For example, with these methods:
+      #
+      #   def test_one
+      #     subset_test('CUSTOM') { assert true }
+      #   end
+      #
+      #   def test_two
+      #     subset_test('CUSTOM') { assert true }
+      #   end
+      #
+      #   Condition                    Tests that get run
+      #   ENV['ALL']=true              test_one, test_two
+      #   ENV['CUSTOM']=true           test_one, test_two
+      #   ENV['CUSTOM_TEST']=test_     test_one, test_two
+      #   ENV['CUSTOM_TEST']=test_one  test_one
+      #   ENV['CUSTOM']=nil            no tests get run
+      # 
+      # If you're running your tests with Rake, ENV variables can be set from the 
+      # command line, so you might use these command line statements:
+      #
+      #   # all tests
+      #   % rake test all=true
+      #
+      #   # custom subset tests
+      #   % rake test custom=true
+      #
+      #   # just test_one
+      #   % rake test custom_test=test_one
+      #
       def subset_test(type, skip=type[0..0].downcase)
         type = type.upcase
         type_test = "#{type}_TEST"
         if run_subset?(type) || env(type_test)
-          if match_regexp?(type_test,  method_name)
+          if match_regexp?(type_test, method_name.to_s)
             yield
           else
             print skip
@@ -328,9 +370,8 @@ module Tap
       end
   
       # Declares a subset_test for the ENV variable 'BENCHMARK'. If run, 
-      # benchmark_test sets up benchmarking using the bm method using the 
-      # input length and block.  As a result you MUST 'include Benchmark'
-      # in the test class.  Prints 'b' if the test is not run.
+      # benchmark_test sets up benchmarking using the Benchmark.bm method 
+      # using the input length and block.  Prints 'b' if the test is not run.
       #
       #   include Benchmark
       #   def test_speed
@@ -340,7 +381,7 @@ module Tap
         subset_test("BENCHMARK") do
           puts
           puts method_name
-          bm(length, &block)
+          Benchmark.bm(length, &block)
         end
       end
 

data/lib/tap/test/tap_methods.rb

@@ -0,0 +1,271 @@
+require 'test/unit'
+require 'tap/test/file_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 using acts_as_file_test
+        # - inclusion of Tap::Test::SubsetMethods
+        # - inclusion of Tap::Test::InstanceMethods 
+        #
+        # Note:  Unless otherwise specified, <tt>acts_as_tap_test</tt> infers a root directory
+        # based on the calling file. Be sure to specify the root directory explicitly 
+        # if you call acts_as_file_test from a file that is NOT meant to be test file.
+        def acts_as_tap_test(options={})
+          options = {:root => file_test_root}.merge(options.symbolize_keys)
+          acts_as_file_test(options)
+          
+          include Tap::Test::SubsetMethods
+          include Tap::Test::TapMethods
+        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.  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.
+    module TapMethods
+      
+      # Returns the test-method-specific application.
+      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
+      # trs (the test root structure, see Tap::Test::FileMethods). 
+      #
+      # Also makes sure Tap::App.instance returns the test method app.
+      def setup
+        super
+        @app = Tap::App.new(
+          :root => method_root, 
+          :directories => trs.directories,
+          :absolute_paths => trs.absolute_paths)
+        Tap::App.instance = @app
+      end
+      
+      #
+      # audit test methods
+      #
+      
+      # Used to define expected audits in Tap::Test::TapMethods#assert_audit_equal
+      class ExpAudit < Array
+      end
+      
+      # Used to define merged audit trails in Tap::Test::TapMethods#assert_audit_equal
+      class ExpMerge < Array
+      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)
+        each_pair_with_index(expected, audits) do |exp, audit, index|
+          assert_audit_equal(exp, audit, [index])
+        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.
+      #
+      # 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')
+      # 
+      #   e = ExpAudit[
+      #        lambda {|source, value| source == :a && value == 'a'},
+      #       [:b, 'b']]
+      #   assert_audit_equal(e, a)
+      #
+      # Assertion with merge:
+      #
+      #   a = Tap::Support::Audit.new
+      #   a._record(:a, 'a')
+      #   a._record(:b, 'b')
+      # 
+      #   b = Tap::Support::Audit.new
+      #   b._record(:c, 'c')
+      #   b._record(:d, 'd')
+      # 
+      #   c = Tap::Support::Audit.merge(a,b)
+      #   c._record(:e, 'e')
+      #   c._record(:f, 'f')
+      # 
+      #   ea = ExpAudit[[:a, "a"], [:b, "b"]]
+      #   eb = ExpAudit[[:c, "c"], [:d, "d"]]
+      #   e = ExpAudit[ExpMerge[ea, eb], [: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)
+      end
+      
+      private
+      
+      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
+            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
+      
+      public
+      
+      #
+      # application methods
+      #
+
+      # 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.
+      #
+      # For convenience, with_options is setup such that options 
+      # {:debug => true, :quiet => true} are implicitly specified.  
+      # Overrides are respected.
+      #
+      #   app = Tap::App.new(:options => {:one => 1, :two => 2})
+      #
+      #   with_options({:one => 'one', :quiet => false}, app) do 
+      #     app.options.marshal_dump     # => {:one => 'one', :two => 2, :debug => true, :quiet => false}
+      #   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.
+      #
+      # For convenience, with_config is setup such that options 
+      # {:debug => true, :quiet => true} are implicitly specified.  
+      # Overrides are respected.
+      #
+      #   app = Tap::App.new(:directories => {:dir => 'dir', :alt => 'alt_dir'})
+      #   tmp_config = {
+      #     :directories => {:alt => 'another', :new => 'new_dir'},
+      #     :options => {:one => 1, :quiet => false}}
+      #
+      #   with_config(tmp_config, app) do 
+      #     app.directories              # => {:dir => 'dir', :alt => 'another', :new => 'new_dir'}
+      #     app.options.marshal_dump     # => {:one => 1, :debug => true, :quiet => false}
+      #   end
+      #
+      #   app.directories                # => {:dir => 'dir', :alt => 'alt_dir'}
+      #   app.options.marshal_dump       # => {}
+      #
+      def with_config(app_config={}, app=self.app, merge_with_existing=true, default_options={:debug => true, :quiet => true}, &block)
+        begin
+          hold = app.config
+          
+          app_config[:options] = default_options.merge(app_config[:options] || {})
+          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
+          app.reconfigure(hold)
+        end
+      end
+      
+    end
+  end
+end
+
+
+
+