dfect 1.0.0 → 1.1.0

data/doc/usage.erb

@@ -1,142 +1,218 @@
 %#--
-%# Copyright 2009 Suraj N. Kurapati
-%# See the LICENSE file for details.
+%# Copyright protects this work.
+%# See LICENSE file for details.
 %#++
 
 % dfect_api = 'api/classes/Dfect.html'
 
+
 %|chapter "Usage"
+
   Begin by loading <%= $project %> into your program:
 
-  <code>
-  require 'rubygems'
-  require 'dfect'
-  </code>
+  %|code :ruby
+    require 'rubygems' # only necessary if you are using Ruby 1.8
+    require 'dfect'
+
+  You now have access to the [`Dfect` module](<%= dfect_api %>), which provides methods that can be mixed-in or called directly, according to your preference:
 
-  You now have access to the [`Dfect` module](<%= dfect_api %>), which provides mixin-able instance methods that are also directly-callable as class methods:
+  %|code :ruby
+    Dfect.D "hello" do  # D() is a class method
+      puts "world"
+    end
 
-  <code>
-  Dfect.D "hello" do  # D() is a not-mixed-in class method
-    puts "world"
-  end
+    # the above is same as:
 
-  # the above is same as:
+    include Dfect       # mix-in the Dfect API
 
-  include Dfect
+    D "hello" do        # D() is an instance method
+      puts "world"
+    end
 
-  D "hello" do        # D() is a mixed-in instance method
-    puts "world"
-  end
-  </code>
+  The following sections explain these provided methods in detail.  If you are impatient, you can skip to <%= xref "A sample unit test" %> for an illustrative example.
 
-  The following sections explain these provided methods in detail.
 
   %|section "Assertions"
-    The following methods take a block parameter and assert something about the result of executing that block.  See the [API documentation](<%= dfect_api %>) for examples.
 
-    | Method | Description                             |
-    | ------ | -----------                             |
-    | F      | assert not true (`nil` or `false`)      |
-    | E      | assert that an execption is raised      |
-    | C      | assert that a symbol is thrown          |
-    | T      | assert true (not `nil` and not `false`) |
+    The following methods accept a block parameter and assert something about the result of executing that block.  They also accept an optional message, which is shown in <%= xref "Failures", "failure reports" %> if they fail.
+
+    See the [API documentation](<%= api_url %>) for details and examples.
+
+    %|table
+      %|thead
+        %|tr
+          %|th
+            Method
+          %|th
+            Description
+      %|tbody
+        %|tr
+          %|td
+            T
+          %|td
+            assert true (not `nil` and not `false`)
+        %|tr
+          %|td
+            F
+          %|td
+            assert not true (`nil` or `false`)
+        %|tr
+          %|td
+            E
+          %|td
+            assert that an execption is raised
+        %|tr
+          %|td
+            C
+          %|td
+            assert that a symbol is thrown
+
 
     %|paragraph "Negation"
+
       These methods are the *opposite* of <%= xref "Assertions", "normal assertions" %>.
 
-      | Method | Description                              |
-      | ------ | -----------                              |
-      | F!     | same as T                                |
-      | E!     | assert that an execption is *not* raised |
-      | C!     | assert that a symbol is *not* thrown     |
-      | T!     | same as F                                |
+      %|table
+        %|thead
+          %|tr
+            %|th
+              Method
+            %|th
+              Description
+        %|tbody
+          %|tr
+            %|td
+              T!
+            %|td
+              same as F
+          %|tr
+            %|td
+              F!
+            %|td
+              same as T
+          %|tr
+            %|td
+              E!
+            %|td
+              assert that an exception is *not* raised
+          %|tr
+            %|td
+              C!
+            %|td
+              assert that a symbol is *not* thrown
+
 
     %|paragraph "Sampling"
-      These methods allow you to *check the outcome* of an <%= xref "Assertions", "assertion" %> without the penalty of pass or failure.
 
-      | Method | Description                                   |
-      | ------ | -----------                                   |
-      | F?     | returns `true` if F passes; `false` otherwise |
-      | E?     | returns `true` if E passes; `false` otherwise |
-      | C?     | returns `true` if C passes; `false` otherwise |
-      | T?     | returns `true` if T passes; `false` otherwise |
+      These methods allow you to *check the outcome* of an <%= xref "Assertions", "assertion" %> without including the assertion in the execution report.
+
+      %|table
+        %|thead
+          %|tr
+            %|th
+              Method
+            %|th
+              Description
+        %|tbody
+          %|tr
+            %|td
+              T?
+            %|td
+              returns `true` if T passes; `false` otherwise
+          %|tr
+            %|td
+              F?
+            %|td
+              returns `true` if F passes; `false` otherwise
+          %|tr
+            %|td
+              E?
+            %|td
+              returns `true` if E passes; `false` otherwise
+          %|tr
+            %|td
+              C?
+            %|td
+              returns `true` if C passes; `false` otherwise
+
 
     %|section "Failures"
+
       When an assertion fails, details about the failure will be shown:
 
-      <pre>
-      - fail: block must yield true (!nil && !false)
-        code: |-
-          [12..22] in test/simple.rb
-             12
-             13     D "with more nested tests" do
-             14       x = 5
-             15
-             16       T { x > 2 }   # passes
-          => 17       F { x > 2 }   # fails
-             18       E { x.hello } # passes
-             19     end
-             20   end
-             21
-             22   # equivalent of before(:each) or setup()
-        vars:
-          x: 5
-          y: 83
-        call:
-        - test/simple.rb:17
-        - test/simple.rb:3
-      </pre>
+          - fail: block must yield true (!nil && !false)
+            code: |-
+              [12..22] in test/simple.rb
+                 12
+                 13     D "with more nested tests" do
+                 14       x = 5
+                 15
+                 16       T { x > 2 }   # passes
+              => 17       F { x > 2 }   # fails
+                 18       E { x.hello } # passes
+                 19     end
+                 20   end
+                 21
+                 22   # equivalent of before(:each) or setup()
+            vars:
+              x: 5
+              y: 83
+            call:
+            - test/simple.rb:17
+            - test/simple.rb:3
 
       You will then be placed into a debugger to investigate the failure if the `:debug` option is enabled in [`Dfect.options`](<%= dfect_api %>).
 
       Details about all assertion failures and a trace of all tests executed are stored by <%= $project %> and provided by the [`Dfect.report`](<%= dfect_api %>) method.
 
+
   %|section "Tests"
+
     The [`D()` method](<%= dfect_api %>) defines a new **test**, which is analagous to the `describe()` environment provided by BDD frameworks like RSpec.
 
     A test may also contain nested tests.
 
-    <code>
-    D "outer test" do
-      # assertions and logic here
+    %|code :ruby
+      D "outer test" do
+        # assertions and logic here
 
-      D "inner test" do
-        # more assertions and logic here
+        D "inner test" do
+          # more assertions and logic here
+        end
       end
-    end
-    </code>
+
 
     %|section "Hooks"
+
       The [`D()` method](<%= dfect_api %>) provides several entry points (hooks) into the test execution process:
 
-      <code>
-      D "outer test" do
-        D .<  { puts "before each nested test" }
-        D .>  { puts "after  each nested test" }
-        D .<< { puts "before all nested tests" }
-        D .>> { puts "after  all nested tests" }
+      %|code :ruby
+        D "outer test" do
+          D .<  { puts "before each nested test" }
+          D .>  { puts "after  each nested test" }
+          D .<< { puts "before all nested tests" }
+          D .>> { puts "after  all nested tests" }
 
-        D "inner test" do
-          # assertions and logic here
+          D "inner test" do
+            # assertions and logic here
+          end
         end
-      end
-      </code>
 
       A hook method may be called multiple times.  Each call registers additional logic to execute during the hook:
 
-      <code>
-      D .< { puts "do something" }
-      D .< { puts "do something more!" }
-      </code>
+      %|code :ruby
+        D .< { puts "do something" }
+        D .< { puts "do something more!" }
+
 
     %|section "Insulation"
+
       Use the singleton class of a temporary object to shield your test logic from Ruby's global environment, the code being tested, and from other tests:
 
-      <code>
-      class << Object.new
-        # your test logic here
-      end
-      </code>
+      %|code :ruby
+        class << Object.new
+          # your test logic here
+        end
 
       Inside this insulated environment, you are free to:
       * mix-in any modules your test logic needs
@@ -144,107 +220,91 @@
 
       For example:
 
-      <code>
-      class << Object.new
-        include SomeModule
-        extend AnotherModule
+      %|code :ruby
+        class << Object.new
+          include SomeModule
+          extend AnotherModule
 
-        YOUR_CONSTANT = 123
+          YOUR_CONSTANT = 123
 
-        D "your tests here" do
-          # your test logic here
+          D "your tests here" do
+            # your test logic here
 
-          your_helper_method
-        end
+            your_helper_method
+          end
 
-        def self.your_helper_method
-          # your helper logic here
+          def self.your_helper_method
+            # your helper logic here
 
-          helper = YourHelperClass.new
-          helper.do_something_helpful
+            helper = YourHelperClass.new
+            helper.do_something_helpful
 
-          T { 2 + 2 != 5 }
-        end
+            T { 2 + 2 != 5 }
+          end
 
-        class YourHelperClass
-          # your helper logic here
+          class YourHelperClass
+            # your helper logic here
+          end
         end
-      end
-      </code>
+
 
   %|section "Execution"
+
     You can configure test execution using:
 
-    <code>
-    Dfect.options = your_options_hash
-    </code>
+    %|code :ruby
+      Dfect.options = your_options_hash
 
     You can execute all tests defined thus far using:
 
-    <code>
-    Dfect.run
-    </code>
+    %|code :ruby
+      Dfect.run
 
     You can stop this execution at any time using:
 
-    <code>
-    Dfect.stop
-    </code>
+    %|code :ruby
+      Dfect.stop
 
     You can view the results of execution using:
 
-    <code>
-    puts Dfect.report.to_yaml
-    </code>
+    %|code :ruby
+      puts Dfect.report.to_yaml
+
+    See the [API documentation](<%= api_url %>) for details and examples.
 
-    See the [API documentation](<%= dfect_api %>) for details and examples.
 
     %|section "Automatic test execution"
-      <code>
-      require 'rubygems'
-      require 'dfect/auto'   # <== notice the "auto"
-      </code>
+
+      %|code :ruby
+        require 'rubygems'     # only necessary if you are using Ruby 1.8
+        require 'dfect/auto'   # <== notice the "auto"
 
       The above code will mix-in the `Dfect` module into your program and will execute all tests defined by your program before it terminates.
 
-  %|example "A sample unit test"
-    <code>
-    require 'rubygems'
-    require 'dfect/auto'
 
-    D "a test" do
-      D "a nested test" do
-      end
+  %|section "Reporting"
 
-      D "another nested test" do
-      end
+    You can insert status messages, which can be arbitrary Ruby objects, into the execution report using the `Dfect::S()` method.
 
-      D "a complex test" do
-        y = 83
+    See the [API documentation](<%= api_url %>) for details and examples.
 
-        D "with more nested tests" do
-          x = 5
 
-          T { x > 2 }   # passes
-          F { x > 2 }   # fails
-          E { x.hello } # passes
-        end
-      end
+  %|section "Emulation"
 
-      D .< do
-        puts "this is executed before every test in this scope"
-      end
+    Dfect provides emulation layers for several popular testing libraries:
 
-      D .> do
-        puts "this is executed after every test in this scope"
-      end
+    * <tt>dfect/unit</tt> --- Test::Unit
+    * <tt>dfect/mini</tt> --- Minitest
+    * <tt>dfect/spec</tt> --- RSpec
 
-      D .<< do
-        puts "this is executed once, before all tests in this scope"
-      end
+    Simply `require()` one of these emulation layers into your test suite and you can write your tests using the familiar syntax of that testing library.
 
-      D .>> do
-        puts "this is executed once, after all tests in this scope"
-      end
-    end
-    </code>
+    See the [API documentation](<%= api_url %>) for details and examples.
+
+
+  %|example! "A sample unit test"
+
+    The following code is from Dfect's very own test suite.
+
+    %|code :ruby
+      %< "../test/dfect.rb"

data/lib/dfect/auto.rb

@@ -1,11 +1,11 @@
-#--
-# Copyright 2009 Suraj N. Kurapati
-# See the LICENSE file for details.
-#++
 # Provides painless, automatic configuration of Dfect.
 #
 # Simply require() this file and Dfect will be available for use anywhere
 # in your program and will execute all tests before your program exits.
+#--
+# Copyright protects this work.
+# See LICENSE file for details.
+#++
 
 require 'dfect'
 

data/lib/dfect/mini.rb

@@ -1,7 +1,7 @@
 # MiniTest emulation layer.
 #--
-# Copyright 2009 Suraj N. Kurapati
-# See the LICENSE file for details.
+# Copyright protects this work.
+# See LICENSE file for details.
 #++
 
 require 'dfect'
@@ -21,6 +21,11 @@ end
   :wont => :refute,
 }.
 each do |outer, inner|
+  #
+  # XXX: using eval() because Ruby 1.8 does
+  #      not support default values and
+  #      block parameters in define_method()
+  #
   file, line = __FILE__, __LINE__ ; eval %{
     class Object
       def #{outer}_be_close_to other, message = nil

data/lib/dfect/spec.rb

@@ -1,11 +1,10 @@
 # RSpec emulation layer.
 #--
-# Copyright 2009 Suraj N. Kurapati
-# See the LICENSE file for details.
+# Copyright protects this work.
+# See LICENSE file for details.
 #++
 
 require 'dfect'
-require 'delegate'
 
 module Kernel
   def describe *args, &block

data/lib/dfect/unit.rb

@@ -1,7 +1,7 @@
 # Test::Unit emulation layer.
 #--
-# Copyright 2009 Suraj N. Kurapati
-# See the LICENSE file for details.
+# Copyright protects this work.
+# See LICENSE file for details.
 #++
 
 require 'dfect'
@@ -20,6 +20,11 @@ module Kernel
     [:assert_not, '!',  'not '],
   ].
   each do |prefix, polarity, action|
+    #
+    # XXX: using eval() because Ruby 1.8 does
+    #      not support default values and
+    #      block parameters in define_method()
+    #
     file, line = __FILE__, __LINE__ ; eval %{
       def #{prefix} boolean, message = nil
         Dfect.T#{polarity}(message) { boolean }
@@ -34,7 +39,7 @@ module Kernel
         Dfect.T#{polarity}(message) { collection.empty? }
       end
 
-      def #{prefix}_equal actual, expected, message = nil
+      def #{prefix}_equal expected, actual, message = nil
         message ||= 'actual must #{action}equal expected'
         Dfect.T#{polarity}(message) { actual == expected }
       end
@@ -43,7 +48,9 @@ module Kernel
         message ||= 'actual must #{action}be within delta of expected'
         delta   ||= 0.001
 
-        Dfect.T#{polarity}(message) { Math.abs(expected - actual) <= Math.abs(delta) }
+        Dfect.T#{polarity}(message) do
+          Math.abs(expected - actual) <= Math.abs(delta)
+        end
       end
 
       alias #{prefix}_in_epsilon #{prefix}_in_delta

data/lib/dfect.rb

@@ -1,6 +1,6 @@
 #--
-# Copyright 2009 Suraj N. Kurapati
-# See the LICENSE file for details.
+# Copyright protects this work.
+# See LICENSE file for details.
 #++
 
 require 'yaml'
@@ -524,6 +524,27 @@ module Dfect
       assert_catch :sample, message, symbol, &block
     end
 
+    ##
+    # Adds the given message to the report inside
+    # the section of the currently running test.
+    #
+    # You can think of "S" as "say" or "status".
+    #
+    # ==== Parameters
+    #
+    # [message]
+    #   Objects to be added to the report.
+    #
+    # ==== Examples
+    #
+    #   S "establishing connection..."
+    #
+    #   S "beginning calculation...", Math::PI, [1, 2, 3, ['a', 'b', 'c']]
+    #
+    def S *message
+      @exec_trace.concat message
+    end
+
     ##
     # Executes all tests defined thus far and stores the results in #report.
     #
@@ -914,9 +935,9 @@ module Dfect
   # Allows before and after hooks to be specified via
   # the D() method syntax when this module is mixed-in:
   #
+  #   D .<< { puts "before all nested tests" }
   #   D .<  { puts "before each nested test" }
   #   D .>  { puts "after  each nested test" }
-  #   D .<< { puts "before all nested tests" }
   #   D .>> { puts "after  all nested tests" }
   #
   D = self

data/rakefile

@@ -1,6 +1,6 @@
 #--
-# Copyright 2009 Suraj N. Kurapati
-# See the LICENSE file for details.
+# Copyright protects this work.
+# See LICENSE file for details.
 #++
 
 require 'rubygems'
@@ -8,8 +8,8 @@ gem 'inochi', '~> 1'
 require 'inochi'
 
 Inochi.init :Dfect,
-  :version => '1.0.0',
-  :release => '2009-05-03',
+  :version => '1.1.0',
+  :release => '2009-10-27',
   :website => 'http://snk.tuxfamily.org/lib/dfect/',
   :tagline => 'Assertion testing library for Ruby'
 

data/test/dfect.rb

@@ -1,6 +1,6 @@
 #--
-# Copyright 2009 Suraj N. Kurapati
-# See the LICENSE file for details.
+# Copyright protects this work.
+# See LICENSE file for details.
 #++
 
 require 'dfect/auto'