dfect 0.1.0 → 1.0.0

data/doc/intro.erb

@@ -1,6 +1,33 @@
+%#--
+%# Copyright 2009 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
+
 % api_url = './api/index.html'
 % src_url = 'http://github.com/sunaku/' + $program
 % git_url = 'http://git-scm.com'
+<%
+  competitors = {
+    'assert{ 2.0 }' => 'http://assert2.rubyforge.org',
+    'Verify'        => 'http://www.ruby-forum.com/topic/183354',
+    'Testy'         => 'http://github.com/ahoward/testy/tree/master',
+    'minitest'      => 'http://blog.zenspider.com/minitest',
+    'Context'       => 'http://github.com/jeremymcanally/context',
+    'Shoulda'       => 'http://thoughtbot.com/projects/shoulda',
+    'Bacon'         => 'http://chneukirchen.org/repos/bacon/README',
+    'test-spec'     => 'http://test-spec.rubyforge.org/test-spec',
+    'RSpec'         => 'http://rspec.info',
+    'Test::Unit'    => 'http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/index.html',
+  }
+
+  def competitors.link_for key
+    if val = self[key]
+      "[#{key}](#{val})"
+    else
+      raise key
+    end
+  end
+%>
 
 %|chapter "Introduction"
   %|project
@@ -14,16 +41,9 @@
     * It is implemented in a mere <%= `sloccount lib`[/^\d+/] %> lines of code.
 
   These features distinguish <%= $project %> from the competition:
-  * [assert{ 2.0 }](http://assert2.rubyforge.org)
-  * [Verify](http://www.ruby-forum.com/topic/183354)
-  * [Testy](http://www.ruby-forum.com/topic/182798)
-  * [minitest](http://blog.zenspider.com/minitest)
-  * [Context](http://github.com/jeremymcanally/context)
-  * [Shoulda](http://thoughtbot.com/projects/shoulda)
-  * [Bacon](http://chneukirchen.org/repos/bacon/README)
-  * [test-spec](http://test-spec.rubyforge.org/test-spec)
-  * [RSpec](http://rspec.info)
-  * [Test::Unit](http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/index.html)
+
+  %|competitors.keys.sort_by {|name| name.downcase }.each do |name|
+    * <%= competitors.link_for name %>
 
   %|paragraph "Etymology"
     <%= $project %> is named after the D F E C T methods it provides.
@@ -32,10 +52,26 @@
 
     This wordplay is similar to [Mnesia](http://www.erlang.org/doc/apps/mnesia/index.html)'s play on the word "amnesia", whereby the intentional omission of the letter "A" indicates forgetfulness---the key characteristic of having amnesia.  Clever!
 
+  %|section "Motivation"
+    The basic premise of <%= $project %> is that, when a failure occurs, I want to be put inside an interactive debugger where I have the freedom to properly scrutinize the state of my program and determine the root cause of the failure.
+
+    Other testing libraries do not fulfill this need.  Instead, they simply report each failed assertion along with a stack trace (if I am lucky) and abruptly terminate my program.
+
+    This deliberate separation of *fault* (my program being in an erroneous state) and *cause* (the source code of my program which caused the fault) reduces me to a primitive and laborious investigative technique known as "[printf debugging](http://oopweb.com/CPP/Documents/DebugCPP/Volume/techniques.html#PRINTF)".
+
+    If you are not the least bit *unsettled* by those two words, then recall your first encounter with [IRB, the interactive Ruby shell](http://tryruby.hobix.com/):  remember how you would enter code expressions and IRB would *instantly* evaluate them and show you the result?
+
+    What an immense productivity boost!  A *stark contrast* to the endless toil of wrapping every such experiment in standard boilerplate (`public static void`...), saving the result to a correctly named file, invoking the C/C++/Java compiler, and finally executing the binary---only to be greeted by a [segfault](http://en.wikipedia.org/wiki/Segmentation_fault). ;-)
+
+    I exaggerate, for the sake of entertainment, of course.  But my point is that the Ruby testing libraries of today have (thus far) limited our productivity by orphaning us from the nurturing environment of IRB and shooing us off to a barren desert of antiquated techniques.  How cruel!
+
+    And that, I say, is why <%= $project %> is essential to Ruby developers today.  It reunites us with our playful, interactive, *real-time* IRB roots and, with unwavering tenacity, enables us to investigate failures *productively*!
+
   %|section "Logistics"
     * <%= xref "History", "Release notes" %> --- history of project releases.
     * [Source code](<%= src_url %>) --- obtain via [Git](<%= git_url %>) or browse online.
     * [API reference](<%= api_url %>) --- documentation for source code.
+    * [Project home](<%= $website %>) --- the <%= $project %> project home page.
 
     To get help or provide feedback, simply
     <%= xref "License", "contact the author(s)" %>.
@@ -80,8 +116,8 @@
         </tbody>
       </table>
 
-  %|section "License"
-    %< "../LICENSE"
+    %|paragraph "License"
+      %< "../LICENSE"
 
   %|section "Credits"
     <%= $project %> is made possible by

data/doc/setup.erb

@@ -1,3 +1,8 @@
+%#--
+%# Copyright 2009 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
+
 %|chapter "Setup"
   %|section "Requirements"
     Your system needs the following software to run <%= $project %>.
@@ -13,22 +18,6 @@
 
         gem install <%= $program %>
 
-  %|section "Manifest"
-    You will see the following items inside <%= $project %>'s installation
-    directory:
-
-    * <tt>lib/</tt>
-
-      * <tt><%= $program %>.rb</tt> --- the main <%= $project %> library.
-
-      * <tt><%= $program %>/</tt>
-
-        * <tt>auto.rb</tt> --- automates test execution.
-
-    * <tt>doc/</tt>
-
-      * <tt>api/</tt> --- API reference documentation.
-
-      * <tt>index.erb</tt> --- source of this user manual.
+    If you want to develop <%= $project %>, run this command:
 
-    * <tt>LICENSE</tt> --- copyright notice and legal conditions.
+        gem install <%= $program %> --development

data/doc/usage.erb

@@ -1,3 +1,8 @@
+%#--
+%# Copyright 2009 Suraj N. Kurapati
+%# See the LICENSE file for details.
+%#++
+
 % dfect_api = 'api/classes/Dfect.html'
 
 %|chapter "Usage"

data/lib/dfect.rb

@@ -12,8 +12,16 @@ require 'yaml'
 # Work around this by representing a class by its name.
 #
 class Class #:nodoc: all
+  alias __to_yaml__ to_yaml
+  undef to_yaml
+
   def to_yaml opts = {}
-    name.to_yaml opts
+    begin
+      __to_yaml__
+    rescue TypeError => e
+      warn e
+      self.name.to_yaml opts
+    end
   end
 end
 
@@ -77,7 +85,7 @@ module Dfect
     #   during assertion failures so
     #   the user can investigate them.
     #
-    #   The default value is $DEBUG.
+    #   The default value is true.
     #
     # [:quiet]
     #   Do not print the report
@@ -219,7 +227,7 @@ module Dfect
     #   T( "computers do not doublethink" ) { 2 + 2 != 5 } # passes
     #
     def T message = nil, &block
-      assert_block :assert, message, &block
+      assert_yield :assert, message, &block
     end
 
     ##
@@ -245,7 +253,7 @@ module Dfect
     #   T!( "computers do not doublethink" ) { 2 + 2 == 5 } # passes
     #
     def T! message = nil, &block
-      assert_block :negate, message, &block
+      assert_yield :negate, message, &block
     end
 
     ##
@@ -270,7 +278,7 @@ module Dfect
     #   T?( "computers do not doublethink" ) { 2 + 2 != 5 } # => true
     #
     def T? message = nil, &block
-      assert_block :sample, message, &block
+      assert_yield :sample, message, &block
     end
 
     alias F T!
@@ -519,16 +527,21 @@ module Dfect
     ##
     # Executes all tests defined thus far and stores the results in #report.
     #
-    def run
+    # ==== Parameters
+    #
+    # [continue]
+    #   If true, results from previous executions will not be cleared.
+    #
+    def run continue = true
       # clear previous results
-      @exec_stats.clear
-      @exec_trace.clear
-      @test_stack.clear
+      unless continue
+        @exec_stats.clear
+        @exec_trace.clear
+        @test_stack.clear
+      end
 
       # make new results
-      catch :stop_dfect_execution do
-        execute
-      end
+      catch(:stop_dfect_execution) { execute }
 
       # print new results
       puts @report.to_yaml unless @options[:quiet]
@@ -544,7 +557,7 @@ module Dfect
 
     private
 
-    def assert_block mode, message = nil, &block
+    def assert_yield mode, message = nil, &block
       raise ArgumentError, 'block must be given' unless block
 
       message ||=
@@ -886,7 +899,7 @@ module Dfect
     #:startdoc:
   end
 
-  @options    = {:debug => $DEBUG, :quiet => false}
+  @options    = {:debug => true, :quiet => false}
 
   @exec_stats = Hash.new {|h,k| h[k] = 0 }
   @exec_trace = []

data/lib/dfect/mini.rb

@@ -0,0 +1,91 @@
+# MiniTest emulation layer.
+#--
+# Copyright 2009 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
+require 'dfect'
+require 'dfect/unit'
+require 'dfect/spec'
+
+module Kernel
+  instance_methods(false).each do |meth|
+    if meth =~ /^assert_not/
+      alias_method 'refute' + $', meth
+    end
+  end
+end
+
+{
+  :must => :assert,
+  :wont => :refute,
+}.
+each do |outer, inner|
+  file, line = __FILE__, __LINE__ ; eval %{
+    class Object
+      def #{outer}_be_close_to other, message = nil
+        #{inner}_in_delta self, other, nil, message
+      end
+
+      def #{outer}_be_empty message = nil
+        #{inner}_empty self, message
+      end
+
+      def #{outer}_be_instance_of _class, message = nil
+        #{inner}_instance_of _class, self, message
+      end
+
+      def #{outer}_be_kind_of _class, message = nil
+        #{inner}_kind_of _class, self, message
+      end
+
+      def #{outer}_be_nil message = nil
+        #{inner}_nil self, message
+      end
+
+      def #{outer}_be_same_as other, message = nil
+        #{inner}_same self, other, message
+      end
+
+      def #{outer}_be_within_delta other, delta = nil, message = nil
+        #{inner}_in_delta self, other, delta, message
+      end
+
+      alias #{outer}_be_within_epsilon #{outer}_be_within_delta
+
+      def #{outer}_equal expected, message = nil
+        #{inner}_equal expected, self, message
+      end
+
+      def #{outer}_include item, message = nil
+        #{inner}_include item, self, message
+      end
+
+      def #{outer}_match pattern, message = nil
+        #{inner}_match pattern, self, message
+      end
+
+      def #{outer}_raise *args, &block
+        #{inner}_raise(*args, &block)
+      end
+
+      def #{outer}_respond_to query, message = nil
+        #{inner}_respond_to self, query, message
+      end
+
+      def #{outer}_send query, *args
+        #{inner}_send self, query, *args
+      end
+    end
+
+    class Proc
+      def #{outer}_raise *args
+        #{inner}_raise(*args, &self)
+      end
+
+      def #{outer}_throw symbol, message = nil
+        #{inner}_throw symbol, message, &self
+      end
+    end
+  }, binding, file, line
+end

data/lib/dfect/spec.rb

@@ -0,0 +1,39 @@
+# RSpec emulation layer.
+#--
+# Copyright 2009 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
+require 'dfect'
+require 'delegate'
+
+module Kernel
+  def describe *args, &block
+    Dfect.D args.join(' '), &block
+  end
+
+  alias context describe
+  alias it      describe
+
+  def before what, &block
+    meth =
+      case what
+      when :each then :<
+      when :all  then :<<
+      else raise ArgumentError, what
+      end
+
+    Dfect.send meth, &block
+  end
+
+  def after what, &block
+    meth =
+      case what
+      when :each then :>
+      when :all  then :>>
+      else raise ArgumentError, what
+      end
+
+    Dfect.send meth, &block
+  end
+end

data/lib/dfect/unit.rb

@@ -0,0 +1,105 @@
+# Test::Unit emulation layer.
+#--
+# Copyright 2009 Suraj N. Kurapati
+# See the LICENSE file for details.
+#++
+
+require 'dfect'
+
+module Kernel
+  def setup &block
+    Dfect.<(&block)
+  end
+
+  def teardown &block
+    Dfect.>(&block)
+  end
+
+  [
+    [:assert,     nil,  nil   ],
+    [:assert_not, '!',  'not '],
+  ].
+  each do |prefix, polarity, action|
+    file, line = __FILE__, __LINE__ ; eval %{
+      def #{prefix} boolean, message = nil
+        Dfect.T#{polarity}(message) { boolean }
+      end
+
+      def #{prefix}_block message = nil, &block
+        Dfect.T#{polarity}(&block)
+      end
+
+      def #{prefix}_empty collection, message = nil
+        message ||= 'collection must #{action}be empty'
+        Dfect.T#{polarity}(message) { collection.empty? }
+      end
+
+      def #{prefix}_equal actual, expected, message = nil
+        message ||= 'actual must #{action}equal expected'
+        Dfect.T#{polarity}(message) { actual == expected }
+      end
+
+      def #{prefix}_in_delta expected, actual, delta = nil, message = nil
+        message ||= 'actual must #{action}be within delta of expected'
+        delta   ||= 0.001
+
+        Dfect.T#{polarity}(message) { Math.abs(expected - actual) <= Math.abs(delta) }
+      end
+
+      alias #{prefix}_in_epsilon #{prefix}_in_delta
+
+      def #{prefix}_include item, collection, message = nil
+        message ||= 'collection must #{action}include item'
+        Dfect.T#{polarity}(messsage) { collection.include? item }
+      end
+
+      def #{prefix}_instance_of _class, object, message = nil
+        message ||= 'object must #{action}be an instance of class'
+        Dfect.T#{polarity}(message) { object.instance_of? _class }
+      end
+
+      def #{prefix}_kind_of _class, object, message = nil
+        message ||= 'object must #{action}be a kind of class'
+        Dfect.T#{polarity}(message) { object.kind_of? _class }
+      end
+
+      def #{prefix}_nil object, message = nil
+        message ||= 'object must #{action}be nil'
+        Dfect.T#{polarity}(message) { object == nil }
+      end
+
+      def #{prefix}_match pattern, string, message = nil
+        message ||= 'string must #{action}match pattern'
+        Dfect.T#{polarity}(message) { string =~ pattern }
+      end
+
+      def #{prefix}_same expected, actual, message = nil
+        message ||= 'actual must #{action}be same as expected'
+        Dfect.T#{polarity}(message) { actual.equal? expected }
+      end
+
+      def #{prefix}_operator object, operator, operand, message = nil
+        message ||= 'object must #{action}support operator with operand'
+        Dfect.T#{polarity} { object.__send__ operator, operand }
+      end
+
+      def #{prefix}_raise *args, &block
+        Dfect.E#{polarity}(args.pop, *args, &block)
+      end
+
+      def #{prefix}_respond_to object, query, message = nil
+        message ||= 'object must #{action}respond to query'
+        Dfect.T#{polarity}(message) { object.respond_to? query }
+      end
+
+      def #{prefix}_throw symbol, message = nil, &block
+        Dfect.C#{polarity}(message, symbol, &block)
+      end
+
+      def #{prefix}_send object, query, *args
+        response = object.__send__(query, *args)
+        Dfect.T#{polarity} { response }
+      end
+    }, binding, file, line
+  end
+end