dfect 0.0.0

data/doc/intro.erb

@@ -0,0 +1,78 @@
+%|chapter "Introduction"
+  %|project_summary
+    **<%= $project %>** is an assertion testing library for Ruby that emphasizes a simple assertion vocabulary, instant debuggability of failures, and flexibility in composing tests.
+
+  **<%= $project %>** is exciting because:
+  * It has only 5 methods to remember: D F E C T.
+  * It lets you debug assertion failures interactively.
+  * It keeps a detailed report of assertion failures.
+  * It lets you nest tests and execution hooks.
+  * 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)
+
+  %|paragraph "Etymology"
+    **<%= $project %>** is named after the 5 methods it provides: D F E C T.
+
+    The name is also play on the word "defect", whereby the intentional misspelling of "defect" as "dfect" is a defect in itself!  <tt>;-)</tt>
+
+    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 "Logistics"
+    * <%= xref "History", "Release notes" %> --- history of project releases.
+    * [Source code](http://github.com/sunaku/<%= $program %>) --- obtain via [Git](http://git.or.cz) or browse online.
+    * [API reference](api/index.html) --- documentation for source code.
+
+    To get help or provide feedback, simply
+    <%= xref "License", "contact the author(s)" %>.
+
+    %|paragraph "Version numbers"
+      **<%= $project %>** releases are numbered in *major.minor.patch*
+      form according to the [RubyGems rational versioning
+      policy](http://www.rubygems.org/read/chapter/7), which
+      can be summarized thus:
+
+      <table markdown="1">
+        <thead>
+          <tr>
+            <td rowspan="2">What increased in the version number?</td>
+            <td colspan="3">The increase indicates that the release:</td>
+          </tr>
+          <tr>
+            <th>Is backward compatible?</th>
+            <th>Has new features?</th>
+            <th>Has bug fixes?</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <th>major</th>
+            <td style="background-color: #FFE4E1;">No</td>
+            <td>Yes</td>
+            <td>Yes</td>
+          </tr>
+          <tr>
+            <th>minor</th>
+            <td>Yes</td>
+            <td>Yes</td>
+            <td>Yes</td>
+          </tr>
+          <tr>
+            <th>patch</th>
+            <td>Yes</td>
+            <td style="background-color: #FFE4E1;">No</td>
+            <td>Yes</td>
+          </tr>
+        </tbody>
+      </table>
+
+  %|section "License"
+    %< "../LICENSE"
+
+  %|section "Credits"
+    **<%= $project %>** is made possible by
+    <%= xref "History", "contributions" %>
+    from users like you.

data/doc/setup.erb

@@ -0,0 +1,34 @@
+%|chapter "Setup"
+  %|section "Requirements"
+    Your system needs the following software to run **<%= $project %>**.
+
+    | Software                                          | Description               | Notes                                                                                  |
+    | --------                                          | -----------               | -----                                                                                  |
+    | [Ruby](http://ruby-lang.org)                      | Ruby language interpreter | Version 1.8.6, 1.8.7, and 1.9.1 have been tested successfully.                         |
+    | [RubyGems](http://rubygems.org)                   | Ruby packaging system     | Version 1.3.1 is required.                                                             |
+    | [ruby-debug](http://www.datanoise.com/ruby-debug) | Interactive debugger      | This is an _optional_ requirement;  IRB will be used if this library is not available. |
+
+  %|section "Installation"
+    You can install **<%= $project %>** by running this command:
+
+        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.
+
+    * <tt>LICENSE</tt> --- copyright notice and legal conditions.

data/doc/usage.erb

@@ -0,0 +1,186 @@
+% dfect_api = 'api/classes/Dfect.html'
+
+%|chapter "Usage"
+  Begin by loading **<%= $project %>** into your program:
+
+  <code>
+  require 'rubygems'
+  require 'dfect'
+  </code>
+
+  Now you have access to the [`Dfect` module](<%= dfect_api %>), which provides mixin-able instance methods which are also directly-callable as module functions (class methods):
+
+  <code>
+  Dfect.D "hello" do
+    puts "world"
+  end
+
+  # the above is same as:
+
+  include Dfect
+
+  D "hello" do
+    puts "world"
+  end
+  </code>
+
+  The following sections explain these methods in detail.
+
+  %|section "Assertions"
+    The following methods take a block parameter and assert something about the result of executing that block.  Follow the links into the API documentation for examples.
+
+    * [`T()`](<%= dfect_api %>) --- assert true (not nil and not false)
+    * [`F()`](<%= dfect_api %>) --- assert not true (nil or false)
+    * [`E()`](<%= dfect_api %>) --- assert that an execption is raised
+    * [`C()`](<%= dfect_api %>) --- assert that a symbol is caught
+
+    %|section "Failures"
+      When an assertion fails, the details about the failure will be shown like this:
+
+      <pre>
+      - a complex test:
+        - with more nested tests:
+          - 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 } # fails
+                 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>
+
+      If the `:debug` option is enabled in [`Dfect.options`](<%= dfect_api %>), you will then be placed into a debugger to investigate the failure.
+
+      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
+
+      D "inner test" do
+        # more assertions and logic here
+      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" }
+
+        D "inner test" do
+          # assertions and logic here
+        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>
+
+  %|section "Execution"
+    You can configure test execution using:
+
+    <code>
+    Dfect.options = your_options
+    </code>
+
+    You can execute all tests defined thus far using:
+
+    <code>
+    Dfect.run
+    </code>
+
+    You can stop this execution at any time using:
+
+    <code>
+    Dfect.stop
+    </code>
+
+    You can view the results of execution using:
+
+    <code>
+    puts Dfect.report.to_yaml
+    </code>
+
+    See the [API documentation](<%= dfect_api %>) for details and examples.
+
+    %|section "Automatic test execution"
+      <code>
+      require 'rubygems'
+      require 'dfect/auto'   # <== notice the "auto"
+      </code>
+
+      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
+
+      D "another nested test" do
+      end
+
+      D "a complex test" do
+        y = 83
+
+        D "with more nested tests" do
+          x = 5
+
+          T { x > 2 }   # passes
+          F { x > 2 }   # fails
+          E { x.hello } # fails
+        end
+      end
+
+      # equivalent of before(:each) or setup()
+      D.< do
+        puts "this is executed before every test in this scope"
+      end
+
+      # equivalent of after(:each) or teardown()
+      D.> do
+        puts "this is executed after every test in this scope"
+      end
+
+      # equivalent of before(:all)
+      D.<< do
+        puts "this is executed once, before all tests in this scope"
+      end
+
+      # equivalent of after(:all)
+      D.>> do
+        puts "this is executed once, after all tests in this scope"
+      end
+    end
+    </code>

data/lib/dfect/auto.rb

@@ -0,0 +1,24 @@
+#--
+# 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.
+
+require 'dfect'
+
+class Object
+  include Dfect
+end
+
+at_exit do
+  Dfect.run
+
+  # reflect number of failures in exit status
+  stats = Dfect.report[:statistics]
+  fails = stats[:failed_assertions] + stats[:uncaught_exceptions]
+
+  exit [fails, 255].min
+end