wrong 0.3.3 → 0.4.0

data/README.markdown

@@ -6,23 +6,33 @@
 
 Wrong provides a general assert method that takes a predicate block. Assertion failure messages are rich in detail. The Wrong idea is to replace all those countless assert\_this, assert\_that, should\_something library methods which only exist to give a more useful failure message than "assertion failed". Wrong replaces all of them in one fell swoop, since if you can write it in Ruby, Wrong can make a sensible failure message out of it.
 
-Wrong is alpha-quality. We'd very much appreciate feedback and bug reports. There are plenty of things left to be done to make the results look uniformly clean and beautiful. We want your feedback, and especially to give us cases where either it blows up or the output is ugly or uninformative.
+We'd very much appreciate feedback and bug reports. There are plenty of things left to be done to make the results look uniformly clean and beautiful. We want your feedback, and especially to give us cases where either it blows up or the output is ugly or uninformative.
 
 It relies on [Predicated](http://github.com/sconover/predicated) for its main failure message.
 
 Inspired by [assert { 2.0 }](http://assert2.rubyforge.org/) but rewritten from scratch. Compatible with Ruby (MRI) 1.8, 1.9, and JRuby 1.5.
 
+## Installation
+
+    gem install wrong
+
+Under JRuby, the above may cause errors; if so, then try
+
+    gem install wrong-jruby
+
+which untangles some dependencies.
+
 ## Usage ##
 
 Wrong provides a simple assert method that takes a block:
 
 	require "wrong"
-	
-	include Wrong::Assert
-	
+
+	include Wrong
+
 	assert { 1 == 1 }
 	 ==> nil
-	
+
 	assert { 2 == 1 }
 	 ==> Expected (2 == 1), but 2 is not equal to 1
 
@@ -63,21 +73,55 @@ And one for capturing output streams:
 
     assert { capturing { puts "hi" } == "hi\n" }
     assert { capturing(:stderr) { $stderr.puts "hi" } == "hi\n" }
+
     out, err = capturing(:stdout, :stderr) { ... }
+    assert { out == "something standard\n" }
+    assert { err =~ /something erroneous/ }
 
 If you want to compare floats, try this:
 
-    require "wrong/close_to"
-
     assert { 5.0.close_to?(5.0001) }   # default tolerance = 0.001
     assert { 5.0.close_to?(5.1, 0.5) } # optional tolerance parameter
 
+(If you don't want `close_to?` cluttering up `Float` in your test runs then use `include Wrong::Assert` instead of `include Wrong`.)
+
+We also implement the most amazing debugging method ever, `d`, which gives you a sort of mini-wrong wherever you want it
+, even in production code at runtime:
+
+    require 'wrong'
+    x = 7
+    d { x } # => prints "x is 7" to the console
+    d { x * 2 } # => prints "(x * 2) is 14" to the console
+
+(`d` was originally implemented by Rob Sanheim in LogBuddy; as with Assert2 this is a rewrite and homage.) Remember, if you want `d` to work at runtime (e.g. in a webapp) then you must `include 'wrong/d'` inside your app, e.g. for in your `environment.rb` file.
+
 More examples are in the file `examples.rb` <http://github.com/alexch/wrong/blob/master/examples.rb>
 
 There's also a spreadsheet showing a translation from Test::Unit and RSpec to Wrong, with notes, at [this Google Doc](https://spreadsheets.google.com/pub?key=0AouPn6oLrimWdE0tZDVOWnFGMzVPZy0tWHZwdnhFYkE&hl=en&output=html). (Ask <alexch@gmail.com> if you want editing privileges.)
 
 And don't miss the [slideshare presentation](http://www.slideshare.net/alexchaffee/wrong-5069976).
 
+## Piecemeal Usage ##
+
+We know that sometimes you don't want all the little doodads from a library cluttering up your namespace. If you **don't** do
+
+    require 'wrong'
+    include Wrong
+
+then you can instead `require` and `include` just the bits you really want. For example:
+
+    require 'wrong/assert'
+    include Wrong::Assert
+
+will give you the `assert` and `deny` methods but not the formatters or `rescuing` or `d` or `close_to?`. And if all you want is `d` then do:
+
+    require 'wrong/d'
+    include Wrong::D
+
+To summarize: if you do `require 'wrong'` and `include Wrong` then you will get the whole ball of wax. Most people will probably want this since it's easier, but there is an alternative, whici is to `require` and `include` only what you want.
+
+And beware: if you don't `require 'wrong'`, then `include Wrong` will not do anything at all.
+
 ## Apology ##
 
 So does the world need another assertion framework? In fact, it does not! We actually believe the world needs **fewer** assert methods.
@@ -146,6 +190,26 @@ The failure message of the above would be something like "`Expected sky.blue? bu
 
 And if your assertion code isn't self-explanatory, then that's a hint that you might need to do some refactoring until it is. (Yes, even test code should be clean as a whistle. **Especially** test code.)
 
+## Details ##
+
+When a failure occurs, the exception message contains all the details you might need to make sense of it. Here's the breakdown:
+
+    Expected [CLAIM], but [SUMMARY]
+      [FORMATTER]
+      [SUBEXP] is [VALUE]
+      ...
+
+* CLAIM is the code inside your assert block, normalized
+* SUMMARY is a to-English translation of the claim, via the Predicated library. This tries to be very intelligible; e.g. translating "include?" into "does not include" and so on.
+* If there is a formatter registered for this type of predicate, its output will come next. (See below.)
+* SUBEXP is each of the subtrees of the claim, minus duplicates and truisms (e.g. literals).
+* The word "is" is a very nice separator since it doesn't look like code, but is short enough to be easily visually parsed.
+* VALUE is `eval(SUBEXP).inspect`
+
+We hope this structure lets your eyes focus on the meaningful values and differences in the message, rather than glossing over with stack-trace burnout. If you have any suggestions on how to improve it, please share them.
+
+(Why does VALUE use `inspect` and not `to_s`? Because `inspect` on standard objects like String and Array are sure to show all relevant details, such as white space, in a console-safe way, and we hope other libraries follow suit. Also, `to_s` often inserts line breaks and that messes up formatting and legibility.)
+
 ## Formatters ##
 
 Enhancements for error messages sit under wrong/message.
@@ -190,7 +254,7 @@ Apparently, no test framework is successful unless and until it supports console
 
     Wrong.config[:color] = true
 
-in your test helper or rakefile or wherever and get ready to be **bedazzled**.
+in your test helper or rakefile or wherever and get ready to be **bedazzled**. If you need custom colors, let us know.
 
 ## Aliases ##
 
@@ -217,7 +281,7 @@ Just don't use "`aver`" since we took that one for an internal method in `Wrong:
 
 ## Helper Assert Methods ##
 
-If you really want to, you can define your procs in one method, pass it in to another method, and have that method assert it. This is very bizarre and you probably shouldn't do it. Wrong will do its best to figure out where the actual assertion code is but it might not succeed.
+If you really want to, you can define your proc in one method, pass it in to another method, and have that method assert it. This is a challenge for Wrong and you probably shouldn't do it. Wrong will do its best to figure out where the actual assertion code is but it might not succeed.
 
 If you're in Ruby 1.8, you **really** shouldn't do it! But if you do, you can use the "depth" parameter to give Wrong a better hint about how far up the stack it should crawl to find the code. See `assert_test.rb` for more details, if you dare.
 
@@ -225,10 +289,12 @@ If you're in Ruby 1.8, you **really** shouldn't do it! But if you do, you can us
 
 * Steve Conover - <sconover@gmail.com>
 * Alex Chaffee - <alex@stinky.com> - <http://alexch.github.com>
+* John Firebaugh
+* Thierry Henrio
 
 ## Etc ##
 
 * Github projects: <http://github.com/alexch/wrong>, <http://github.com/sconover/wrong>
 * Tracker project: <http://www.pivotaltracker.com/projects/109993>
-* [Wrong way translation table (from RSpec and Test::Unit)](https://spreadsheets.google.com/pub?key=0AouPn6oLrimWdE0tZDVOWnFGMzVPZy0tWHZwdnhFYkE&hl=en&output=html). (Ask <alexch@gmail.com> if you want editing privileges.)
-* [the Wrong slides I presented at Carbon Five](http://www.slideshare.net/alexchaffee/wrong-5069976)
+* the [Wrong way translation table (from RSpec and Test::Unit)](https://spreadsheets.google.com/pub?key=0AouPn6oLrimWdE0tZDVOWnFGMzVPZy0tWHZwdnhFYkE&hl=en&output=html). (Ask <alexch@gmail.com> if you want editing privileges.)
+* the [Wrong slides](http://www.slideshare.net/alexchaffee/wrong-5069976) that Alex presented at Carbon Five and GoGaRuCo

data/lib/wrong.rb

@@ -1,7 +1,27 @@
+dir = File.expand_path(File.dirname(__FILE__))
+$: << dir unless $:.include?(dir) # should we really have to do this? It's necessary to run examples.rb
+
 require "predicated"
 require "wrong/assert"
+require "wrong/helpers"
 require "wrong/chunk"
 require "wrong/sexp_ext"
 require "wrong/version"
 require "wrong/config"
 require "wrong/irb"
+require "wrong/d"
+require "wrong/message/array_diff"
+require "wrong/message/string_comparison"
+
+module Wrong
+  include Wrong::Assert
+  extend Wrong::Assert
+  include Wrong::Helpers
+  extend Wrong::Helpers
+end
+
+# this does some magic; if you don't like it, `require 'wrong/assert'` et al. individually and don't `require 'wrong/close_to'` or `require 'wrong'`
+require "wrong/close_to"
+
+# this does some magic; if you don't like it, `require 'wrong/assert'` et al. individually, don't `require 'wrong'`, and `include Wrong::D` only in the modules you want to call `d` from
+Object.send :include, Wrong::D

data/lib/wrong/adapters/minitest.rb

@@ -1,26 +1,14 @@
-require "wrong/assert"
+require "wrong"
 
 class MiniTest::Unit::TestCase
-  include Wrong::Assert
+  include Wrong
+
   def failure_class
     MiniTest::Assertion
   end
 
-  def assert(*args)
-    if block_given? 
-      self._assertions += 1
-      super(explanation=args.first, depth=1)
-    else
-      super
-    end
-  end
-
-  def deny(*args)
-    if block_given? 
-      self._assertions += 1
-      super(explanation=args.first, depth=1)
-    else
-      super
-    end
+  def aver(valence, explanation = nil, depth = 0)
+    self._assertions += 1 # increment minitest's assert count
+    super(valence, explanation, depth + 1) # apparently this passes along the default block
   end
 end

data/lib/wrong/adapters/rspec.rb

@@ -1,10 +1,21 @@
-require "spec"
-require "wrong/assert"
+require "wrong"
 
-Spec::Runner.configure do |config|
-  include Wrong::Assert
-  
-  def failure_class
-    Spec::Expectations::ExpectationNotMetError
+if Object.const_defined? :Spec
+  Spec::Runner.configure do |config|
+    include Wrong
+
+    def failure_class
+      Spec::Expectations::ExpectationNotMetError
+    end
+  end
+elsif Object.const_defined? :RSpec
+  RSpec.configure do |config|
+    include Wrong
+
+    def failure_class
+      RSpec::Expectations::ExpectationNotMetError
+    end
   end
+else
+  raise "Wrong's RSpec adapter can't find RSpec. Please require 'spec' or 'rspec' first."
 end

data/lib/wrong/adapters/test_unit.rb

@@ -1,7 +1,7 @@
-require "wrong/assert"
+require "wrong"
 
 class Test::Unit::TestCase
-  include Wrong::Assert
+  include Wrong
 
   def failure_class
     Test::Unit::AssertionFailedError

data/lib/wrong/assert.rb

@@ -1,32 +1,31 @@
 require "predicated/predicate"
 require "predicated/from/ruby_code_string"
 require "predicated/to/sentence"
+
 require "wrong/chunk"
 require "wrong/config"
-
-#see http://yehudakatz.com/2009/01/18/other-ways-to-wrap-a-method/
-class Module
-  def overridable(&blk)
-    mod = Module.new(&blk)
-    include mod
-  end
-end
+require "wrong/failure_message"
+require "wrong/ruby2ruby_patch" # need to patch it after some other stuff loads
 
 module Wrong
   module Assert
 
-    class AssertionFailedError < RuntimeError;
+    class AssertionFailedError < RuntimeError
     end
 
     def failure_class
       AssertionFailedError
     end
 
-    # Actual signature: assert(explanation = nil, depth = 0, block)
+    # Actual signature: assert(explanation = nil, depth = 0, &block)
     def assert(*args, &block)
+      # to notice (and fail fast from) odd recursion problem
+      raise "Reentry bug while trying to assert(#{args.join(', ')})" if @_inside_wrong_assert
+      @_inside_wrong_assert = true
+
       if block.nil?
         begin
-          super
+          super(*args) # if there's a framework assert method (sans block), then call it
         rescue NoMethodError => e
           # note: we're not raising an AssertionFailedError because this is a programmer error, not a failed assertion
           raise "You must pass a block to Wrong's assert and deny methods"
@@ -34,9 +33,11 @@ module Wrong
       else
         aver(:assert, *args, &block)
       end
+    ensure
+      @_inside_wrong_assert = false
     end
 
-    # Actual signature: deny(explanation = nil, depth = 0, block)    
+    # Actual signature: deny(explanation = nil, depth = 0, &block)
     def deny(*args, &block)
       if block.nil?
         test = args.first
@@ -47,101 +48,55 @@ module Wrong
       end
     end
 
-    def rescuing
-      error = nil
-      begin
-        yield
-      rescue Exception, RuntimeError => e
-        error = e
-      end
-      error
+    def summary(method_sym, predicate)
+      method_sym == :deny ? predicate.to_sentence : predicate.to_negative_sentence
     end
 
-    # Usage:
-    # capturing { puts "hi" } => "hi\n"
-    # capturing(:stderr) { $stderr.puts "hi" } => "hi\n"
-    # out, err = capturing(:stdout, :stderr) { ... }
-    #
-    # see http://www.justskins.com/forums/closing-stderr-105096.html for more explanation
-    def capturing(*streams)
-      streams = [:stdout] if streams.empty?
-      original = {}
-      captured = {}
-
-      # reassign the $ variable (which is used by well-behaved code e.g. puts)
-      streams.each do |stream|
-        original[stream] = (stream == :stdout ? $stdout : $stderr)
-        captured[stream] = StringIO.new
-        case stream
-          when :stdout
-            $stdout = captured[stream]
-          when :stderr
-            $stderr = captured[stream]
-        end
-      end
+    protected
 
-      yield
+    # for debugging -- if we couldn't make a predicate out of the code block, then this was why
+    def self.last_predicated_error
+      @@last_predicated_error ||= nil
+    end
 
-      # return either one string, or an array of two strings
-      if streams.size == 1
-        captured[streams.first].string
-      else
-        [captured[streams[0]].string, captured[streams[1]].string]
-      end
+    # todo: move some/all of this into FailureMessage
+    def full_message(chunk, block, valence, explanation)
+      code = chunk.code
 
-    ensure
-
-      streams.each do |stream|
-        # bail if stream was reassigned inside the block
-        if (stream == :stdout ? $stdout : $stderr) != captured[stream]
-          raise "#{stream} was reassigned while being captured"
-        end
-        # support nested calls to capturing
-        original[stream] << captured[stream].string if original[stream].is_a? StringIO
-        case stream
-          when :stdout
-            $stdout = original[stream]
-          when :stderr
-            $stderr = original[stream]
-        end
+      predicate = begin
+        Predicated::Predicate.from_ruby_code_string(code, block.binding)
+      rescue Predicated::Predicate::DontKnowWhatToDoWithThisSexpError, Exception => e
+        # save it off for debugging
+        @@last_predicated_error = e
+        nil
       end
-    end
 
-    overridable do
-      def failure_message(method_sym, block, predicate)
-        method_sym == :deny ? predicate.to_sentence : predicate.to_negative_sentence
+      code = code.color(:blue) if Wrong.config[:color]
+      message = ""
+      message << "#{explanation}: " if explanation
+      message << "#{valence == :deny ? "Didn't expect" : "Expected"} #{code}, but "
+      if predicate && !(predicate.is_a? Predicated::Conjunction)
+        message << summary(valence, predicate)
+        if formatter = FailureMessage.formatter_for(predicate)
+          failure = formatter.describe
+          failure = failure.bold if Wrong.config[:color]
+          message << failure
+        end
       end
+      message << chunk.details
+      message
     end
 
-    private
-
     def aver(valence, explanation = nil, depth = 0, &block)
       require "wrong/rainbow" if Wrong.config[:color]
-      
+
       value = block.call
       value = !value if valence == :deny
       unless value
+
         chunk = Wrong::Chunk.from_block(block, depth + 2)
-        code = chunk.code
-
-        predicate = begin
-          Predicated::Predicate.from_ruby_code_string(code, block.binding)
-        rescue Predicated::Predicate::DontKnowWhatToDoWithThisSexpError
-          nil
-        rescue Exception
-          nil
-        end
 
-        code = code.color(:blue) if Wrong.config[:color]
-        message = ""
-        message << "#{explanation}: " if explanation
-        message << "#{valence == :deny ? "Didn't expect" : "Expected"} #{code}, but "
-        if predicate && !(predicate.is_a? Predicated::Conjunction) 
-          failure = failure_message(valence, block, predicate)
-          failure = failure.bold if Wrong.config[:color] 
-          message << failure
-        end
-        message << chunk.details
+        message = full_message(chunk, block, valence, explanation)
         raise failure_class.new(message)
       end
     end

data/lib/wrong/chunk.rb

@@ -1,18 +1,35 @@
 require 'ruby_parser'
 require 'ruby2ruby'
+
+begin
+  require "ParseTree"
+rescue LoadError => e
+  raise e unless e.message == "no such file to load -- ParseTree"
+end
+
+begin
+  require "sourcify"
+rescue LoadError => e
+  raise e unless e.message == "no such file to load -- sourcify"
+end
+
 require "wrong/config"
 require "wrong/sexp_ext"
 
 module Wrong
   class Chunk
     def self.from_block(block, depth = 0)
-      file, line = if block.to_proc.respond_to? :source_location
-                     # in Ruby 1.9, it reads the source location from the block
-                     block.to_proc.source_location
-                   else
-                     # in Ruby 1.8, it reads the source location from the call stack
-                     caller[depth].split(":")
-                   end
+
+      as_proc = block.to_proc
+      file, line =
+              if as_proc.respond_to? :source_location
+                # in Ruby 1.9, or with Sourcify, it reads the source location from the block
+                as_proc.source_location
+              else
+                # in Ruby 1.8, it reads the source location from the call stack
+                caller[depth].split(":")
+              end
+
       new(file, line, block)
     end
 
@@ -33,38 +50,68 @@ module Wrong
       "#{@file}:#{@line_number}"
     end
 
+    def sexp
+      @sexp ||= build_sexp
+    end
+
+    def build_sexp
+      sexp = begin
+        unless @block.nil? or @block.is_a?(String) or !Object.const_defined?(:Sourcify)
+          # first try sourcify
+          @block.to_sexp[3] # the [3] is to strip out the "proc {" sourcify adds to everything
+        end
+      rescue ::Sourcify::MultipleMatchingProcsPerLineError, Racc::ParseError, Errno::ENOENT => e
+        # fall through
+      end
+
+      # next try glomming
+      sexp ||= glom(if @file == "(irb)"
+                      IRB.CurrentContext.all_lines
+                    else
+                      read_source_file(@file)
+                    end)
+    end
+
+    def read_source_file(file, dir = ".")
+      File.read "#{dir}/#{file}"
+
+    rescue Errno::ENOENT, Errno::EACCES => e
+      # we may be in a chdir underneath where the file is, so move up one level and try again
+      parent = "#{dir}/..".gsub(/^(\.\/)*/, '')
+      if File.expand_path(dir) == File.expand_path(parent)
+        raise Errno::ENOENT, "couldn't find #{file}"
+      end
+      read_source_file(file, parent)
+
+    end
+
     # Algorithm:
-    # try to parse the starting line
-    # if it parses OK, then we're done!
-    # if not, then glom the next line and try again
-    # repeat until it parses or we're out of lines
-    def parse
-      source = if @file == "(irb)"
-               IRB.CurrentContext.all_lines
-             else
-               File.read(@file)
-             end
+    # * try to parse the starting line
+    # * if it parses OK, then we're done!
+    # * if not, then glom the next line and try again
+    # * repeat until it parses or we're out of lines
+    def glom(source)
       lines = source.split("\n")
       @parser ||= RubyParser.new
       @chunk = nil
       c = 0
-      @sexp = nil
-      while @sexp.nil? && line_index + c < lines.size
+      sexp = nil
+      while sexp.nil? && line_index + c < lines.size
         begin
           @chunk = lines[line_index..line_index+c].join("\n")
-          @sexp = @parser.parse(@chunk)
+          sexp = @parser.parse(@chunk)
         rescue Racc::ParseError => e
           # loop and try again
           c += 1
         end
       end
-      @sexp
+      sexp
     end
-    
+
     # The claim is the part of the assertion inside the curly braces.
     # E.g. for "assert { x == 5 }" the claim is "x == 5"
     def claim
-      parse()
+      sexp()
 
       if @sexp.nil?
         raise "Could not parse #{location}"
@@ -82,6 +129,10 @@ module Wrong
 
     def code
       self.claim.to_ruby
+    rescue => e
+      # note: this is untested; it's to recover from when we can't locate the code
+      message = "Failed assertion at #{caller[depth + 2]} [couldn't retrieve source code due to #{e.inspect}]"
+      raise failure_class.new(message)
     end
 
     def parts(sexp = nil)
@@ -99,11 +150,17 @@ module Wrong
           puts "#{e.class}: #{e.message}"
           puts e.backtrace.join("\n")
         end
+
+        if sexp.first == :iter
+          sexp.delete_at(1) # remove the method-call-sans-block subnode
+        end
+
         sexp.each do |sub|
           if sub.is_a?(Sexp)
             parts_list += parts(sub)
           end
         end
+
         parts_list
       end
     end
@@ -120,7 +177,7 @@ module Wrong
         parts.each do |part|
           begin
             value = eval(part, block.binding)
-            unless part == value.inspect  # this skips literals or tautologies
+            unless part == value.inspect # this skips literals or tautologies
               if part =~ /\n/m
                 part.gsub!(/\n/, newline(2))
                 part += newline(3)
@@ -138,7 +195,12 @@ module Wrong
               part = part.color(:blue)
               raises = raises.bold.color(:red)
             end
-            details << indent(2, part, " ", raises, ": ", indent_all(3, e.message))
+            formatted_exeption = if e.message and e.message != e.class.to_s
+              indent(2, part, " ", raises, ": ", indent_all(3, e.message))
+            else
+              indent(2, part, " ", raises)
+            end
+            details << formatted_exeption
           end
         end
       end
@@ -149,11 +211,11 @@ module Wrong
       else
         "\n" + details.join("\n") + "\n"
       end
-      
+
     end
 
     private
-    
+
     def indent(indent, *s)
       "#{"  " * indent}#{s.join('')}"
     end