tap 0.7.9 → 0.8.0

data/lib/tap/test/subset_methods.rb

@@ -5,25 +5,106 @@ require 'tap/test/env_vars'
 
 module Test # :nodoc:
   module Unit # :nodoc:
-    class TestCase
+    # Methods extending TestCase.  See the TestTutorial for more information.
+    class TestCase 
       class << self
+        include Tap::Test::EnvVars
+        
+        # Passes conditions to subclass
+        def inherited(subclass) # :nodoc:
+          super
+          subclass_conditions = conditions.inject({}) do |memo, (key, value)|
+            memo.update(key => (value.dup rescue value))
+          end
+          subclass.instance_variable_set("@conditions", subclass_conditions)
+          
+      #    subclass_inputs = prompt_inputs.inject({}) do |memo, (key, value)|
+      #      memo.update(key => (value.dup rescue value))
+      #    end
+      #    subclass.instance_variable_set("@prompt_inputs", subclass_inputs)
+        end
+        
+        # Experimental -- The idea is to provide a way to prompt once for inputs
+        # that get used multiple times in a test.  Perhaps create accessors
+        # automatically?
+        
+      #  def prompt_inputs
+      #    @prompt_inputs ||= {}
+      #  end
+        
+      #  def require_inputs(*keys, &block)
+      #    if run_subset?("PROMPT")
+      #      puts "\n#{name} requires inputs -- Enter values or 'skip'."
+            
+      #      argv = ARGV.dup
+      #      begin
+      #        ARGV.clear
+      #        keys.collect do |key|
+      #          print "#{key}: "
+      #          value = gets.strip
+      #          if value =~ /skip/i
+      #            skip_test "missing inputs"
+      #            break
+      #          end
+      #          prompt_inputs[key] = value
+      #        end
+      #      ensure
+      #        ARGV.clear
+      #        ARGV.concat(argv)
+      #      end
+      #    else
+      #      skip_test "prompt test"
+      #    end
+      #  end 
+        
+        #
+        # conditions
+        #
 
-        # Causes a whole test suite to require one of the listed platforms 
-        # in order to run.  See match_platform? for details.
+        # A hash of defined conditions
+        def conditions
+          @conditions ||= {}
+        end
+      
+        # Defines a condition block and associated message.  
+        # Raises an error if no condition block is given.
+        def condition(name, msg=nil, &block)
+          raise "no condition block given" unless block_given?
+          conditions[name.to_sym] = [msg, block]
+        end
+        
+        # Returns true if the all blocks for the named conditions return true.
         #
-        # Simply declare like:
+        #   condition(:is_true) { true }
+        #   condition(:is_false) { false }
+        #   satisfied?(:is_true)              # => true
+        #   satisfied?(:is_true, :is_false)   # => false
         #
-        #   class Test::Unit::TestCase
-        #     require_platform 'mswin'
-        #   end
-        def require_platform(*platforms, &block)
-          @platforms = platforms
-          yield if block_given? && match_platform?(*@platforms)
+        def satisfied?(*conditions)
+          unsatisfied_conditions(*conditions).empty?
         end
-
+          
+        # Returns an array of the unsatified conditions.  Raises 
+        # an error if the named condition has not been defined.
+        #
+        #   condition(:is_true) { true }
+        #   condition(:is_false) { false }
+        #   unsatisfied_conditions(:is_true, :is_false)   # => [:is_false]
+        #
+        def unsatisfied_conditions(*conditions)
+          conditions = self.conditions.keys if conditions.empty?
+          unsatified = []
+          conditions.each do |condition|
+            raise "Unknown condition: #{condition}" unless self.conditions.has_key?(condition)
+            unsatified << condition unless (self.conditions[condition.to_sym].last.call() ? true : false)
+          end
+          unsatified
+        end
+        
         # Returns true if RUBY_PLATFORM matches one of the specfied
-        # platforms.  Use the prefix 'non_' to specify any plaform but the 
-        # specified platform (ex: 'non_mswin')
+        # platforms.  Use the prefix 'non_' to specify any plaform 
+        # except the specified platform (ex: 'non_mswin').  Returns
+        # true if no platforms are specified.
         #
         # Some common platforms:
         # - mswin:: Windows
@@ -39,8 +120,44 @@ module Test # :nodoc:
 
           true
         end
+        
+        # Returns true if the subset type or 'ALL' is specified in ENV
+        def run_subset?(type)
+          env_true?(type) || env_true?("ALL") ? true : false
+        end
+
+        #
+        # Methods for skipping a test suite
+        #
+        attr_accessor :run_test_suite
+        
+        # Returns run_test_suite, or true if run_test_suite is not set.
+        def run_test_suite?
+          run_test_suite.nil? ? true : run_test_suite
+        end
+        
+        # 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
+          
+          # experimental -- perhaps use this so that a test can be skipped
+          # for multiple reasons?
+          (@skip_messages ||= []) << msg unless msg.nil?
+        end
 
         alias :original_suite :suite
+        
+        # Modifies the default suite method to include/exclude tests based on platform.
+        def suite # :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
+        end
       end      
     end
   end
@@ -48,196 +165,149 @@ end
 
 module Tap
   module Test
+    
+    # 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.
+    # 
+    # SubsetMethods extends TestCase with methods for defining conditions that can be 
+    # used to conditionally perform some action, or skip a test suite entirely.  When 
+    # you include SubsetMethods within a specific TestCase, additional methods are 
+    # made available for filtering tests.
+    # 
+    #   require 'tap/test/subset_methods'
+    #   class Test::Unit::TestCase
+    #     # only true if running on windows
+    #     condition(:windows) { match_platform?('mswin') }
+    # 
+    #     # only true if running on anything but windows
+    #     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)
+    #   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.
+    # 
+    #   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
+    #         ... 
+    #       end
+    #     end
+    # 
+    #     def test_runs_only_when_EXTENDED_is_true
+    #       extended_test do
+    #         ... 
+    #       end
+    #     end
+    # 
+    #     def test_runs_only_when_BENCHMARK_is_true
+    #       benchmark_test do |x|
+    #         x.report("init speed") { 10000.times { Object.new } }
+    #       end
+    #     end
+    #   end
+    # 
+    # In the example, EXTENDED and BENCHMARK refer to environment (ENV) variables.
+    # ENV variables can be set from the command line like so:
+    # 
+    #   % tap run test extended=true
+    #   % tap run 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.  
+    #
+    # == Class Methods
+    # 
+    # See Test::Unit::TestCase for documentation of the class methods added by SubsetMethods
     module SubsetMethods
       include Tap::Test::EnvVars
+  
+      def satisfied?(*conditions)
+        self.class.satisfied?(*conditions)
+      end
       
-      def self.suite
-        if match_platform?(*@platforms)
-          original_suite
-        else
-          # if platforms are specfied for the tests and the platform does NOT
-          # match, remake the suite to skip all tests.
-          method_names = public_instance_methods(true)
-          suite = Test::Unit::TestSuite.new(name)
-          method_names.each do |method_name| 
-            catch(:invalid_test) do
-              suite << new('on_test_skipped') if method_name =~ /^test/
-            end
-          end
-          suite
-        end
+      # Returns true if the subset type or 'ALL' is specified in ENV
+      def run_subset?(type)
+        self.class.run_subset?(type)
       end
 
-      # Platform-specific test.  Useful for specifying test that should only be run on,
-      # for instance, windows.  See match_platform? for details.
-      def platform_test(*platforms, &block)
-        if self.class.match_platform?(*platforms)
-          yield
-        else
-          print ' '
-        end
-      end
-  
-      # Subset test declaration for extended tests -- type: EXTENDED
-      # Prints 'x' unless run.
-        def extended_test(&block) 
-        subset_test("EXTENDED", "x", &block)
-      end
-  
-      # Subset test declaration for benchmark tests -- type: BENCHMARK
-      # Prints 'b' unless run.
-      def benchmark_test(length=10, &block) 
-        subset_test("BENCHMARK") do
-          puts
-          puts calling_method
-          bm(length) do |x|
-            yield(x)
-          end
-        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)
+        return true if env_true?("ALL")
+        return default unless env(type)
+    
+        PP.singleline_pp(obj, '') =~ Regexp.new(env(type)) ? true : false
       end
 
-      # Case tests take a hash of testcases and expected values.  Each pair in the hash will 
-      # be passed to the block if type CASE_TEST is specified.  Individual cases tests can be 
-      # specified by providing a regexp in CASE; the testcase will run if the pretty-print of
-      # the testcase matches the provided regexp.  Example:
+      # Platform-specific test.  Useful for specifying test that should only 
+      # be run on a subset of platforms.  Prints ' ' if the test is not run.
       #
-      #   case_test(
-      #     [1,2,3] => 'an array testcase',
-      #     '[1, 2, 3]' => 'the pretty print of the array',
-      #     'another testcase' => 'some third testcase'
-      #   ).do |testcase, expected|
-      #      ...your test code...
+      #   def test_only_on_windows
+      #     platform_test('mswin') { ... }
       #   end
       #
-      #   ENV['CASE_TEST']=true  => all tests run
-      #   ENV['CASE']='1, 2, 3' => first two tests run
-      #   ENV['CASE']='another' => only last test runs
-      def case_test(hash, &block)
-        if match_regexp?("CASE_TEST", calling_method)
-          hash.each_pair do |testcase, expected|
-            yield(testcase, expected) if match_regexp?("CASE", testcase)
-          end
+      # See TestCase#match_platform? for matching details.
+      def platform_test(*platforms)
+        if self.class.match_platform?(*platforms)
+          yield
+        else
+          print ' '
         end
       end
-  
-      # Acase tests take an array of testcases.  Each testcase in the array will 
-      # be passed to the block if type CASE_TEST is specified.  Individual cases tests can be 
-      # specified by providing a regexp in CASE; the testcase will run if the pretty-print of
-      # the testcase matches the provided regexp.  Example:
+      
+      # Conditonal test.  Only runs if the named conditions are satisfied.
+      # If no conditons are explicitly set, only runs if all conditions 
+      # are satisfied.
+      # 
+      #   condition(:is_true) { true }
+      #   condition(:is_false) { false }
       #
-      #   case_test(
-      #     [1,2,3] ,
-      #     '[1, 2, 3]',
-      #     'another testcase'
-      #   ).do |testcase|
-      #      ...your test code...
+      #   def test_only_if_true_is_satisfied
+      #     condition_test(:is_true) { # runs }
       #   end
       #
-      #   ENV['CASE_TEST']=true  => all tests run
-      #   ENV['CASE']='1, 2, 3' => first two tests run
-      #   ENV['CASE']='another' => only last test runs
-      def acase_test(*array)
-        if match_regexp?("CASE_TEST", calling_method)
-          array.each do |testcase|
-            yield(testcase) if match_regexp?("CASE", testcase)
-          end
-        end  
-      end
-
-  
-      # Subset test declaration for prompt tests -- type: PROMPT
-      # Prints 'p' unless run.
-      #
-      # Useful for tests that require user input.  If run, then this test will
-      # prompt the user for an input for each item in the array.  The results
-      # are collected in a hash and passed to the block.
-      #
-      # Example:
-      # 
-      #   def test_something_important
-      #     prompt_test(:a, :b, :c).do |config|
-      #        ...your test code...
-      #     end
+      #   def test_only_if_all_conditions_are_satisfied
+      #     condition_test {  # does not run }
       #   end
       #
-      #   (if run, prompts print to $stdout the following:)
-      #   test_something_important: Enter values or 'skip'
-      #   a: # => enter 'avalue'
-      #   b: # => enter 'bvalue'
-      #   c: # => enter 'cvalue'
-      #
-      #   # config => {:a => 'avalue', :b => 'bvalue', :c => 'cvalue'}
-      def prompt_test(*array, &block)
-        subset_test("PROMPT", "p") do
-          puts "\n#{calling_method} -- Enter values or 'skip'."
-    
-          config = {}
-          array.each do |key|
-            print "#{key}: "
-            value = gets.strip
-            flunk "skipped test" if value =~ /skip/i
-        
-            config[key] = value
-          end
-        
-          yield(config)
+      # See TestCase#condition for more details.
+      def condition_test(*conditions)
+        unsatisfied_conditions = self.class.unsatisfied_conditions(*conditions)
+        if unsatisfied_conditions.empty?
+          yield
+        else
+          print ' '
         end
       end
-  
-      protected
-  
-      # Formats the input by using singleline_pp
-      def spp(input, str='')
-        PP.singleline_pp(input, str)
-      end
-  
-      # Required for platform tests
-      def on_test_skipped
-        print ' '
-      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
-  
-      # Returns true if the subset type or 'ALL' is specified in ENV
-      def run_subset?(type)
-        env_true?(type) || env_true?("ALL") ? true : false
-      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)
-        return true if env_true?("ALL")
-        return default unless env(type)
-    
-        spp(obj) =~ Regexp.new(env(type)) ? true : false
-      end
-  
-      # Calling method iterates over the call stack, and returns the first calling
-      # method name that matches the input pattern (by default /^test/)
-      def calling_method(pattern=/^test/)
-        0.upto(caller.length) do |i|
-          caller[i] =~ /:in `(.*)'$/
-          method_name = $1
-          return method_name if method_name =~ pattern
-        end
       
-        ''
-      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
       #  
       # Otherwise the block will be skipped and +skip+ will be printed.  By default skip
       # is the first letter of +type+.
-      def subset_test(type, skip=type[0..0].downcase, &block)
+      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,  calling_method)
+          if match_regexp?(type_test,  method_name)
             yield
           else
             print skip
@@ -247,12 +317,61 @@ module Tap
         end
       end
   
-      # Runs only if the first argument causes an 'if' statement to return true.
-      def switch_test(run_test, skip="!", &block)
-        if run_test
-          yield
-        else
-          print skip
+      # Declares a subset_test for the ENV variable 'EXTENDED'.
+      # Prints 'x' if the test is not run.
+      #
+      #   def test_some_long_process
+      #     extended_test { ... }
+      #   end
+      def extended_test(&block) 
+        subset_test("EXTENDED", "x", &block)
+      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.
+      #
+      #   include Benchmark
+      #   def test_speed
+      #     benchmark_test(10) {|x| ... }
+      #   end
+      def benchmark_test(length=10, &block) 
+        subset_test("BENCHMARK") do
+          puts
+          puts method_name
+          bm(length, &block)
+        end
+      end
+
+      # Declares a subset_test for the ENV variable 'PROMPT'. When run, prompts
+      # the user for each input specified in array.  Inputs will then be passed
+      # as a hash to the block.  Prints 'p' unless run.
+      # 
+      #   def test_requiring_inputs
+      #     prompt_test(:a, :b, :c) {|a, b, c| ... }
+      #   end
+      #
+      # If run, the command line prompt will be like the following:
+      #
+      #   test_requiring_inputs: Enter values or 'skip'
+      #   a: avalue
+      #   b: bvalue      
+      #   c: cvalue
+      #
+      # The block recieves ['avalue', 'bvalue', 'cvalue'].  
+      def prompt_test(*keys, &block)
+        subset_test("PROMPT", "p") do
+          puts "\n#{method_name} -- Enter values or 'skip'."
+  
+          values = keys.collect do |key|
+            print "#{key}: "
+            value = gets.strip
+            flunk "skipped test" if value =~ /skip/i
+            value
+          end
+        
+          yield(*values)
         end
       end
     end