ae 1.7.4 → 1.8.0

data/lib/ae/adapters/minitest.rb

@@ -4,33 +4,43 @@ AE.assertion_error = ::MiniTest::Assertion
 
 module MiniTest #:nodoc:
   class Unit #:nodoc:
+
     # MiniTest tracks assertion counts internally in it's Unit class via the 
     # +assertion_count+ attribute. To work with AE we need add in AE's assertion
     # total by overriding the +assertion_count+ method.
+    #
+    # @return [Integer] Number of assertions made.
     def assertion_count
       @assertion_count + AE::Assertor.counts[:total]
     end
+
     # To teach MiniTest to recognize AE's expanded concept of assertions
-    # we add in an extra capture clause to the it's #puke method.
-    def puke c, m, x
-      case x
+    # we add in an extra capture clause to it's #puke method.
+    #
+    # @return [String] Status code is `S`, `F`, or `E`.
+    def puke k, m, e
+      case e
       when MiniTest::Skip
-        @skips = @skips + 1
-        x = "Skipped:\n#{m}(#{c}) [#{location x}]:\n#{x.message}\n"
+        @skips += 1
+        return "S" unless @verbose
+        e = "Skipped:\n#{m}(#{k}) [#{location e}]:\n#{e.message}\n"
       when MiniTest::Assertion
-        @failures = @failures + 1
-        x = "Failure:\n#{m}(#{c}) [#{location x}]:\n#{x.message}\n"
-      when x.respond_to?(:assertion?) && x.assertion?
-        @failures = @failures + 1
-        x = "Failure:\n#{m}(#{c}) [#{location x}]:\n#{x.message}\n"
+        @failures += 1
+        e = "Failure:\n#{m}(#{k}) [#{location e}]:\n#{e.message}\n"
       else
-        @errors = @errors + 1
-        b = MiniTest::filter_backtrace(x.backtrace).join("\n ")
-        x = "Error:\n#{m}(#{c}):\n#{x.class}: #{x.message}\n #{b}\n"
+        if e.respond_to?(:assertion?) && e.assertion?
+          @failures += 1
+          e = "Failure:\n#{m}(#{c}) [#{location e}]:\n#{e.message}\n"
+        else
+          @errors += 1
+          b = MiniTest::filter_backtrace(e.backtrace).join "\n    "
+          e = "Error:\n#{m}(#{k}):\n#{e.class}: #{e.message}\n    #{b}\n"
+        end
       end
-      @report << x
-      x[0, 1]
+      @report << e
+      e[0, 1]
     end
+
   end
 end
 

data/lib/ae/adapters/testunit.rb

@@ -10,7 +10,7 @@ AE.assertion_error = ::Test::Unit::AssertionFailedError
 # In addition we teach #run to recognize any Exception class that
 # responds to #assertion? in the affirmative as an assertion
 # rather than an error.
-
+#
 module Test #:nodoc:
   module Unit #:nodoc:
     class TestCase #:nodoc:

data/lib/ae/assert.rb

@@ -12,10 +12,10 @@ module AE
     #
     #   4.assert == 3
     #
-    # If only a single test argument is given then
-    # #assert simple validates that it evalutate to true.
-    # An optional message argument can be given in this
-    # case which will be used instead of the deafult message.
+    # If only a single test argument is given then #assert
+    # simply validates that it evalutate to true. An optional
+    # message argument can be given in this case which will
+    # be used instead of the deafult message.
     #
     #   assert(4==3, "not the same thing")
     #
@@ -24,11 +24,14 @@ module AE
     #
     #   assert{ 4==3 }
     #
+    # @return [Assertor] Assertion functor.
     def assert(*args, &block)
       Assertor.new(self, :backtrace=>caller).assert(*args, &block)
     end
 
     # Same as 'object.assert == other'.
+    #
+    # @return [Assertor] Assertion functor.
     def assert=(cmp)
       Assertor.new(self, :backtrace=>caller).assert == cmp
     end
@@ -37,11 +40,14 @@ module AE
     #
     #   4.refute == 4  #=> Assertion Error
     #
+    # @return [Assertor] Assertion functor.
     def refute(*args, &block)
       Assertor.new(self, :backtrace=>caller).not.assert(*args, &block)
     end
 
     # Same as 'object.refute == other'.
+    #
+    # @return [Assertor] Assertion functor.
     def refute=(cmp)
       Assertor.new(self, :backtrace=>caller).not.assert == cmp
     end
@@ -57,6 +63,15 @@ module AE
     alias_method :assert!, :refute
 
     # Directly raise an Assertion failure.
+    #
+    # @param message [String]
+    #   Error message.
+    #
+    # @param backtrace [String]
+    #   Backtrace, used to pass up an error from lower in the stack. 
+    #
+    # @raise [Assertion]
+    #   Assertion error with given `message`.
     def flunk(message=nil, backtrace=nil)
       #Assertor.new(self, :backtrace=>caller).assert(false, message)
       Assertor.assert(false, message, backtrace || caller)
@@ -66,8 +81,4 @@ module AE
 
 end
 
-class ::Object #:nodoc:
-  include AE::Assert
-end
-
-# Copyright (c) 2008,2009 Thomas Sawyer
+# Copyright (c) 2008 Thomas Sawyer

data/lib/ae/assertion.rb

@@ -13,15 +13,16 @@ module AE
   #
   class Assertion < Exception
 
-    # DEPRECATE: This will be removed in favor of Assertor#counts.
+    # @deprecated
+    #   This will be removed in favor of `AE::Assertor.counts`.
     def self.counts
       AE::Assertor.counts
     end
 
     # New assertion (failure).
     #
-    # message - the failure message
-    # options - such as :backtrace
+    # @param message [String] the failure message
+    # @param options [Hash] options such as :backtrace
     #
     def initialize(message=nil, options={})
       super(message)
@@ -38,7 +39,9 @@ module AE
       true
     end
 
+    # Parents error message prefixed with "(assertion)".
     #
+    # @return [String] error message
     def to_s
       '(assertion) ' + super
     end
@@ -47,5 +50,5 @@ module AE
 
 end
 
-# Set top-level Assertion to AE::Assertion
-Assertion = AE::Assertion
+# Set top-level Assertion to AE::Assertion if not already present.
+Assertion = AE::Assertion unless defined?(Assertion)

data/lib/ae/assertor.rb

@@ -1,6 +1,6 @@
 require 'ae/assertion'
 require 'ae/basic_object'
-require 'ansi/diff'
+require 'ae/ansi'
 
 module AE
 
@@ -91,7 +91,6 @@ module AE
     #def self.assay?
     #  @_assay ||= defined?(::Assay)
     #end
-
     #
     #def self.message(sym, neg, *args, &blk)
     #  if method = Message.lookup(sym) 
@@ -116,11 +115,10 @@ module AE
       @negated   = !!opts[:negated]
     end
 
+    # TODO: Should #not return a new Assertor instead of in place negation?
+
     # Negate the meaning of the assertion.
     #
-    #--
-    # TODO: Should this return a new Assertor instead of in place negation?
-    #++
     def not(msg=nil)
       @negated = !@negated
       @message = msg if msg
@@ -141,19 +139,15 @@ module AE
     #   assert something, parameter
     #
     # Returns +true+ or +false+ based on assertions success.
-    #--
-    # The use of #to_proc and #matches? as sepcial cases is not
-    # a robust solution.
-    #++
+    #
     def assert(*args, &block)
-      return self if args.empty? && !block
+      return self if !block && args.empty?
 
-      target = block || args.shift
+      target = args.shift unless block
       error  = nil
 
-      # Lambda
-      if ::Proc === target || target.respond_to?(:to_proc)
-        block  = target.to_proc
+      # Block
+      if block
         match  = args.shift
         result = block.arity > 0 ? block.call(@delegate) : block.call
         if match
@@ -164,14 +158,17 @@ module AE
           error = @message || block.inspect  # "#{result.inspect}"
         end
 
-      # Matcher
-      elsif target.respond_to?(:matches?) # Matchers
-        pass  = target.matches?(@delegate)
-        error = @message || matcher_message(target) #|| target.inspect
-        if target.respond_to?(:exception)
-          #error_class = target.failure_class
-          error = target.exception #(:backtrace=>@backtrace, :negated=>@negated)
-        end
+      # Proc-style
+      elsif proc_assertion?(target)
+        pass, error = proc_apply(target)
+
+      # Assay-style assertions
+      #elsif assay_assertion?(target)
+      #  pass, error = assay_assertion_apply(target)
+
+      # RSpec-style matchers
+      elsif rspec_matcher?(target)
+        pass, error = rspec_matcher_apply(target)
 
       # Truthiness
       else
@@ -182,23 +179,20 @@ module AE
       __assert__(pass, error)
     end
 
+    # TODO: Should we deprecate the receiver matches in favor of #expected ?
+    # In other words, should <code>|| @delegate</code> be dropped?
+
     # Internal expect, provides all functionality associated
     # with external #expect method. (See Expect#expect)
     #
-    #--
-    # TODO: Should we deprecate the receiver matches in favor of #expected ?
-    # In other words, should the <code>|| @delegate</code> be dropped?
-    #++
     def expect(*args, &block)
-      return self if args.empty? && !block  # same as #assert
+      return self if !block && args.empty?  # same as #assert
 
-      target = block || args.shift
-      error  = nil
+      pass  = false
+      error = nil
 
-      # Lambda
-      if ::Proc === target #|| target.respond_to?(:to_proc)
-        #block = target.to_proc
-        match = args.shift || @delegate
+      if block
+        match = args.shift || @delegate  # TODO: see above
         if exception?(match)
           $DEBUG, debug = false, $DEBUG  # b/c it always spits-out a NameError
           begin
@@ -220,19 +214,20 @@ module AE
           error  = @message || "#{match.inspect} === #{result.inspect}"
         end
 
-      # Matcher
-      elsif target.respond_to?(:matches?)
-        pass  = target.matches?(@delegate)
-        error = @message || matcher_message(target) #|| target.inspect
-        if target.respond_to?(:exception)
-          #error_class = target.failure_class
-          error = target.exception #failure(:backtrace=>@backtrace, :negated=>@negated)
-        end
+      ## Matcher
+      #elsif target.respond_to?(:matches?)
+      #  pass  = target.matches?(@delegate)
+      #  error = @message || matcher_message(target) #|| target.inspect
+      #  if target.respond_to?(:exception)
+      #    #error_class = target.failure_class
+      #    error = target.exception #failure(:backtrace=>@backtrace, :negated=>@negated)
+      #  end
 
-      # Case Equals
+      # Case Equality
       else
-        pass  = (target === @delegate)
-        error = @message || "#{target.inspect} === #{@delegate.inspect}"
+        target = args.shift
+        pass   = (target === @delegate)
+        error  = @message || "#{target.inspect} === #{@delegate.inspect}"
       end
 
       __assert__(pass, error)
@@ -260,20 +255,94 @@ module AE
       @delegate.inspect
     end
 
-    private
+   private
+
+    # AE-STYLE ASSERTIONS
+
+    #
+    def proc_assertion?(target) 
+      ::Proc === target || target.respond_to?(:call) || target.respond_to?(:to_proc)
+    end
+
+    #
+    def proc_apply(target)
+      call  = target.method(:call) rescue target.to_proc
+      pass  = call.arity != 0 ? call.call(@delegate) : call.call
+      error = @message || (
+        to_s = target.method(:to_s)
+        to_s.arity == 0 ? to_s.call : to_s.call(@negated)
+      )
+      return pass, error
+    end
+
+    # ASSAY-STYLE ASSERTIONS
+    # (not yet supported b/c api is not 100%)
+
+    # Is the `assertion` object an assay-style assertion?
+    def assay_assertion?(assertion)
+      assertion.respond_to?(:exception) && assertion.respond_to?(:pass?)
+    end
+
+    #
+    def assay_assertion_apply(assay)
+      if @negated
+        pass  = assay.fail?(@delegate)
+        error = assay #.exception(@message || )
+      else
+        pass  = assay.pass?(@delegate)
+        error = assay #.exception(@message || )
+      end
+      return pass, error
+    end
+
+    # RSPEC-STYLE MATCHERS
+
+    # Is `target` an Rspec-style Matcher?
+    def rspec_matcher?(target)
+      target.respond_to?(:matches?)
+    end
+
+    #
+    def rspec_matcher_apply(matcher)
+      pass  = matcher.matches?(@delegate)
+      error = @message || rspec_matcher_message(matcher)
+      return pass, error
+    end
+
+    # TODO: Is there anything to be done with matcher.description?
+
+    #
+    def rspec_matcher_message(matcher)
+      if @negated
+        if matcher.respond_to?(:failure_message_for_should_not)
+          return matcher.failure_message_for_should_not
+        end
+        if matcher.respond_to?(:negative_failure_message)
+          return matcher.negative_failure_message
+        end
+      end
+
+      if matcher.respond_to?(:failure_message_for_should)
+        return matcher.failure_message_for_should
+      end
+      if matcher.respond_to?(:failure_message)
+        return matcher.failure_message
+      end
+
+      return matcher.to_s  # TODO: or just `nil` ?
+    end
 
-    # Is the +object+ an Exception or an instance of one?
-    #--
     # TODO: Should we use a more libreral determination of exception.
     # e.g. <code>respond_to?(:exception)</code>.
-    #++
+
+    # Is the +object+ an Exception or an instance of one?
     def exception?(object)
       ::Exception === object or ::Class === object and object.ancestors.include?(::Exception)
     end
 
-    # Converts a missing method into an Assertion.
-    #
     # TODO: In future should probably be `@delegate.public_send(sym, *a, &b)`.
+
+    # Converts a missing method into an Assertion.
     def method_missing(sym, *args, &block)
       error = @message || compare_message(sym, *args, &block) || generic_message(sym, *args, &block)
 
@@ -282,29 +351,14 @@ module AE
       __assert__(pass, error)
     end
 
+    # TODO: Can the handling of the message be simplified/improved?
 
     # Simple assert.
-    #--
-    # TODO: Can the handling of the message be simplified/improved?
-    #++
     def __assert__(pass, error=nil)
       Assertor.assert(pass, error, @negated, @backtrace)
     end
 
     #
-    def matcher_message(matcher)
-      if @negated
-        if matcher.respond_to?(:negative_failure_message)
-          return matcher.failure_message
-        end
-      else
-        if matcher.respond_to?(:failure_message)
-          return matcher.failure_message
-        end
-      end
-      return nil
-    end
-
     COMPARISON_OPERATORS = { :"==" => :"!=" }
 
     # Message to use when making a comparion assertion.
@@ -314,7 +368,9 @@ module AE
     # terminals) you can either set `AE.ansi = false` or use the
     # ANSI library's master switch to deactive all ANSI codes,
     # which can be set in your test helper.
-    # 
+    #
+    # @param operator [Symbol] operator/method
+    #
     # @see http://rubyworks.github.com/ansi
     def compare_message(operator, *args, &blk)
       return nil unless COMPARISON_OPERATORS.key?(operator)
@@ -342,6 +398,9 @@ module AE
 
     # Puts together a suitable error message.
     #
+    # @param op [Symbol] operator/method
+    #
+    # @return [String] message
     def generic_message(op, *a, &b)
       inspection = @delegate.send(:inspect)
       if @negated
@@ -366,4 +425,4 @@ end
 #  end
 #end
 
-# Copyright (c) 2008,2009 Thomas Sawyer
+# Copyright (c) 2008 Thomas Sawyer