dfect 2.1.0 → 2.2.0

data/CREDITS

@@ -1,2 +1,20 @@
-- François Beausoleil <http://github.com/francois>
-- Iñaki Baz Castillo <http://github.com/ibc>
+%#----------------------------------------------------------------------------
+## AUTHORS
+%#----------------------------------------------------------------------------
+
+Suraj N. Kurapati
+
+%#----------------------------------------------------------------------------
+## CREDITS
+%#----------------------------------------------------------------------------
+
+François Beausoleil,
+Iñaki Baz Castillo,
+Sean O'Halpin
+
+%#----------------------------------------------------------------------------
+## LICENSE
+%#----------------------------------------------------------------------------
+
+%# See the file named "LICENSE".
+%< "LICENSE"

data/bin/dfect

@@ -1,57 +1,26 @@
 #!/usr/bin/env ruby
-#
-# Usage:
-#
-#   dfect [Options] FILE_OR_GLOB...
-#
-#   FILE_OR_GLOB  : A file or file globbing pattern that
-#                   describes a set of files to evaluate.
-#
-#
-# Options:
-#
-#   -d, --debug   : Launch interactive debugger
-#                   during assertion failures.
-#
-#   -q, --quiet   : Do not show execution report.
-#
-#   -h, --help    : Show this message and exit.
-#
-#   -v, --version : Show version number and exit.
-#
 
-$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
 require 'dfect'
 
-# parse command line
 if ARGV.delete('-h') or ARGV.delete('--help')
-  puts
-  puts Dfect.inspect
-  puts Dfect::TAGLINE
-  puts
-  puts
-  puts File.read(__FILE__)[/^#(\r?\n)(.*?)\1\1/m, 2].gsub(/^# ?/, '')
-  puts
-  puts
-  puts 'Read the user manual for more information:'
-  puts
-  puts "  #{Dfect::INSTDIR}/doc/index.html"
-  puts
-  puts "  #{Dfect::WEBSITE}"
-  puts
+  # try to display UNIX version of help manual
+  man_path = File.join(Dfect::INSTDIR, 'man')
+  unless system 'man', '-M', man_path, '-a', 'dfect'
+    # try to display HTML version of help manual
+    man_html = man_path + '.html'
+    unless %w[$BROWSER open start].any? {|b| system "#{b} #{man_html}" }
+      # no luck; direct user to project website
+      puts "See #{Dfect::WEBSITE}"
+    end
+  end
   exit
 elsif ARGV.delete('-v') or ARGV.delete('--version')
   puts Dfect::VERSION
   exit
 end
 
-if ARGV.delete('-d') or ARGV.delete('--debug')
-  Dfect.options[:debug] = true
-end
-
-if ARGV.delete('-q') or ARGV.delete('--quiet')
-  Dfect.options[:quiet] = true
-end
+Dfect.options[:debug] = ARGV.delete('-d') || ARGV.delete('--debug')
+Dfect.options[:quiet] = ARGV.delete('-q') || ARGV.delete('--quiet')
 
 require 'dfect/auto'
 ARGV.each {|glob| Dir[glob].each {|test| load test } }

data/lib/dfect/full.rb

@@ -0,0 +1,24 @@
+# Provides full name aliases for Dfect's default abbreviated vocabulary.
+
+require 'dfect'
+
+module Dfect
+  full_names = {
+    'D' => 'Describe',
+    'T' => 'True',
+    'F' => 'False',
+    'E' => 'Error',
+    'C' => 'Catch',
+    'S' => 'Share',
+    'L' => 'Log',
+  }
+
+  instance_methods(false).each do |meth_name|
+    if full_name = meth_name.to_s.sub!(/^[A-Z]/) {|abbr| full_names[abbr] }
+      alias_method full_name, meth_name
+    end
+  end
+
+  # for hooks
+  Describe = D
+end

data/lib/dfect/inochi.rb

@@ -18,12 +18,12 @@ module Dfect
   ##
   # Number of this release of this project.
   #
-  VERSION = "2.1.0"
+  VERSION = "2.2.0"
 
   ##
   # Date of this release of this project.
   #
-  RELDATE = "2010-03-31"
+  RELDATE = "2010-04-28"
 
   ##
   # Description of this release of this project.
@@ -74,29 +74,20 @@ module Dfect
   #   }
   #
   DEVTIME = {
-    "inochi" => [ "~> 2" ], # for managing this project
+    "inochi" => [ ">= 3.0.0", "< 4" ],
   }
 
-  ##
-  # Loads the correct version (as defined by the {RUNTIME} or {DEVTIME}
-  # constant in this module) of the given gem or the gem that contains
-  # the given library.
-  #
-  def self.require gem_name_or_library
-    # prepare the correct version of the gem for loading
-    if respond_to? :gem
-      gem_name = gem_name_or_library.to_s.sub(%r{/.*$}, '')
-      if gem_version = RUNTIME[gem_name] || DEVTIME[gem_name]
+  # establish gem version dependencies
+  if respond_to? :gem
+    [RUNTIME, DEVTIME].each do |deps|
+      deps.each do |gem_name, gem_version|
         begin
-          gem gem_name, *gem_version
+          gem gem_name, *Array(gem_version)
         rescue LoadError => error
           warn "#{self.inspect}: #{error}"
         end
       end
     end
-
-    # do the loading
-    super
   end
 
 end

data/man.html

@@ -0,0 +1,947 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv='content-type' value='text/html;charset=utf8'>
+  <meta name='generator' value='Ronn/v0.5'>
+  <title>dfect(1) - Assertion testing library for Ruby</title>
+  <style type='text/css'>
+    body {margin:0}
+    #man, #man code, #man pre, #man tt, #man kbd, #man samp {
+      font-family:consolas,monospace;
+      font-size:16px;
+      line-height:1.3;
+      color:#343331;
+      background:#fff; }
+    #man { max-width:87ex; margin:0 3ex 1ex 1ex; text-align:justify; }
+    #man div.man-navigation {
+      position:fixed;
+      top:0;
+      left:91ex;
+      height:100%;
+      width:100%;
+      padding:1ex 0 0 2ex;
+      border-left:0.5ex solid #DCDCDC;
+      background-color: #F5F5F5;
+    }
+    #man div.man-navigation a { display:block; margin-bottom:1.5ex }
+    #man h1, #man h2, #man h3 { color:#232221;clear:left }
+    #man h1 { font-size:28px; margin:15px 0 30px 0; text-align:center }
+    #man h2 { font-size:18px; margin-bottom:0; margin-top:10px; line-height:1.3; }
+    #man h3 { font-size:16px; margin:0 0 0 4ex; }
+    #man p, #man ul, #man ol, #man dl, #man pre { margin:0 0 18px 0; }
+    #man pre {
+      color:#333231;
+      background:#edeceb;
+      padding:5px 7px;
+      margin:0px 0 20px 0;
+      border-left:2ex solid #ddd}
+    #man pre + h2, #man pre + h3 {
+      margin-top:22px;
+    }
+    #man h2 + pre, #man h3 + pre {
+      margin-top:5px;
+    }
+    #man > p, #man > ul, #man > ol, #man > dl, #man > pre { margin-left:8ex; }
+    #man dt { margin:0; clear:left }
+    #man dt.flush { float:left; width:8ex }
+    #man dd { margin:0 0 0 9ex }
+    #man code, #man strong, #man b { font-weight:bold; color:#131211; }
+    #man pre code { font-weight:normal; color:#232221; background:inherit }
+    #man em, var, u {
+      font-style:normal; color:#333231; border-bottom:1px solid #999; }
+    #man h1.man-title { display:none; }
+    #man ol.man, #man ol.man li { margin:2px 0 10px 0; padding:0;
+      float:left; width:33%; list-style-type:none;
+      text-transform:uppercase; font-size:18px; color:#999;
+      letter-spacing:1px;}
+    #man ol.man { width:100%; }
+    #man ol.man li.tl { text-align:left }
+    #man ol.man li.tc { text-align:center;letter-spacing:4px }
+    #man ol.man li.tr { text-align:right; float: right }
+    #man ol.man a { color:#999 }
+    #man ol.man a:hover { color:#333231 }
+    #man img { display:block; margin:auto }
+  </style>
+  <style type='text/css' media='print'>
+    #man { max-width:none }
+    #man div.man-navigation { display:none }
+    #man a[href]:not([href^="#"]):not([data-bare-link]):after {
+      content:" " attr(href);
+    }
+  </style>
+</head>
+<body>
+<div id='man'>
+
+<div class='man-navigation'><a href='#NAME'>NAME</a> <a href='#SYNOPSIS'>SYNOPSIS</a> <a href='#DESCRIPTION'>DESCRIPTION</a> <a href='#OPTIONS'>OPTIONS</a> <a href='#TESTS'>TESTS</a> <a href='#ASSERTIONS'>ASSERTIONS</a> <a href='#EMULATION'>EMULATION</a> <a href='#EXAMPLES'>EXAMPLES</a> <a href='#HACKING'>HACKING</a> <a href='#VERSIONS'>VERSIONS</a> <a href='#AUTHORS'>AUTHORS</a> <a href='#CREDITS'>CREDITS</a> <a href='#LICENSE'>LICENSE</a> <a href='#SEE-ALSO'>SEE ALSO</a></div>
+
+<h1 class='man-title'>dfect(1)</h1>
+
+<ol class='head man'>
+  <li class='tl'>dfect(1)</li>
+  <li class='tc'>Version 2.2.0</li>
+  <li class='tr'>dfect(1)</li>
+</ol>
+
+<h2 id='NAME'>NAME</h2>
+<p><code>dfect</code> - Assertion testing library for Ruby</p>
+
+<p>Dfect is an assertion testing library for Ruby that emphasizes a simple
+assertion vocabulary, instant debuggability of failures, and flexibility in
+composing tests.</p>
+
+<h3 id="Features">Features</h3>
+
+<ul>
+<li><p>Adds only 7 mnemonic method names to your memory:</p>
+
+<p><code>D</code>escribe, <code>T</code>rue, <code>F</code>alse, <code>E</code>rror, <code>C</code>atch, <code>S</code>hare, and <code>L</code>og.</p></li>
+<li><p>Lets you debug assertion failures interactively.</p></li>
+<li><p>Lets you nest tests, assertions, and execution hooks.</p></li>
+<li><p>Maintains a detailed report of assertion failures.</p></li>
+<li><p>Implemented in 375 lines of code.</p></li>
+</ul>
+
+
+<h3 id="Resources">Resources</h3>
+
+<dl>
+<dt>Issue tracker (report bugs, request features, get help)</dt><dd><p><a href="http://github.com/sunaku/dfect/issues" data-bare-link="true">http://github.com/sunaku/dfect/issues</a></p></dd>
+<dt>Source code (browse online or obtain with <a href="http://git-scm.com">Git</a>)</dt><dd><p><a href="http://github.com/sunaku/dfect" data-bare-link="true">http://github.com/sunaku/dfect</a></p></dd>
+<dt>API documentation</dt><dd><p><a href="http://snk.tuxfamily.org/lib/dfect/api/" data-bare-link="true">http://snk.tuxfamily.org/lib/dfect/api/</a></p></dd>
+<dt>Announcements feed</dt><dd><p><a href="http://snk.tuxfamily.org/lib/dfect/ann.xml" data-bare-link="true">http://snk.tuxfamily.org/lib/dfect/ann.xml</a></p></dd>
+<dt>Official website</dt><dd><p><a href="http://snk.tuxfamily.org/lib/ember/" data-bare-link="true">http://snk.tuxfamily.org/lib/ember/</a></p></dd>
+</dl>
+
+
+<h3 id="Setup">Setup</h3>
+
+<p>Prerequisites:</p>
+
+<ul>
+<li><p><a href="http://ruby-lang.org">Ruby</a> 1.8.6 or newer.</p></li>
+<li><p><a href="http://rubygems.org">RubyGems</a> 1.3.6 or newer.</p></li>
+<li><p><a href="http://github.com/mark-moseley/ruby-debug">ruby-debug</a> will be used to help you debug assertion
+failures interactively if it is installed.  Otherwise, the
+standard interactive Ruby shell (IRB) will be used instead.</p></li>
+</ul>
+
+
+<p>Installing:</p>
+
+<pre><code>gem install dfect
+</code></pre>
+
+<p>Upgrading:</p>
+
+<pre><code>gem update dfect
+</code></pre>
+
+<p>Removing:</p>
+
+<pre><code>gem uninstall dfect
+</code></pre>
+
+<h2 id="SYNOPSIS">SYNOPSIS</h2>
+
+<p><code>dfect</code> [<var>OPTIONS</var>] (<var>FILE</var>|<var>GLOB</var>) ...</p>
+
+<h2 id="DESCRIPTION">DESCRIPTION</h2>
+
+<p>Evaluates the given <var>FILE</var>s and also files matching the given <var>GLOB</var> patterns.</p>
+
+<p>The exit status of this command reflects the number of errors and assertion
+failures up to a maximum of 255 (to avoid 8-bit unsigned integer overflow).</p>
+
+<h2 id="OPTIONS">OPTIONS</h2>
+
+<dl>
+<dt><code>-d</code>, <code>--debug</code></dt><dd><p>Launch interactive debugger upon assertion failures.</p></dd>
+<dt><code>-q</code>, <code>--quiet</code></dt><dd><p>Do not print execution report.</p></dd>
+<dt><code>-h</code>, <code>--help</code></dt><dd><p>Display this manual and exit.</p></dd>
+<dt><code>-v</code>, <code>--version</code></dt><dd><p>Print version number and exit.</p></dd>
+</dl>
+
+
+<h2 id="TESTS">TESTS</h2>
+
+<p>The <code>D()</code> method defines a new Dfect <strong>test</strong>, which is analagous to the
+concept of <strong>test case</strong> in <a href="http://en.wikipedia.org/wiki/XUnit">xUnit</a> or <strong>describe</strong> in <a href="http://rspec.info">RSpec</a>.  A test may
+contain nested tests.</p>
+
+<pre><code>D "outer test" do
+  # assertions and logic here
+
+  D "inner test" do
+    # more assertions and logic here
+  end
+end
+</code></pre>
+
+<h3 id="Execution">Execution</h3>
+
+<p>Tests are executed in depth-first order.</p>
+
+<p>You can configure the test execution process using:</p>
+
+<pre><code>Dfect.options = your_options_hash
+</code></pre>
+
+<p>You can execute all tests defined thus far using:</p>
+
+<pre><code>Dfect.run
+</code></pre>
+
+<p>You can stop the execution at any time using:</p>
+
+<pre><code>Dfect.stop
+</code></pre>
+
+<p>You can view the results of execution using:</p>
+
+<pre><code>puts Dfect.report.to_yaml
+</code></pre>
+
+<p>You can mix-in the <code>Dfect</code> module into your program and execute all tests
+defined by your program before it terminates by simply adding the following
+line at the top of your program:</p>
+
+<pre><code>require 'dfect/auto'
+</code></pre>
+
+<p>See the API documentation for more information and examples.</p>
+
+<h3 id="Hooks">Hooks</h3>
+
+<p>The <code>D()</code> method provides several entry points (hooks) into the test
+execution process:</p>
+
+<pre><code>D "outer test" do
+  D .&lt;  { puts "before each nested test" }
+  D .&gt;  { puts "after  each nested test" }
+  D .&lt;&lt; { puts "before all nested tests" }
+  D .&gt;&gt; { puts "after  all nested tests" }
+
+  D "inner test" do
+    # assertions and logic here
+  end
+end
+</code></pre>
+
+<p>A hook method may be called multiple times.  Each call registers
+additional logic to execute during the hook:</p>
+
+<pre><code>D .&lt; { puts "do something" }
+D .&lt; { puts "do something more!" }
+</code></pre>
+
+<h3 id="Logging">Logging</h3>
+
+<p>The <code>L()</code> method lets you insert log messages, composed of arbitrary
+Ruby objects, into the test execution report.</p>
+
+<h3 id="Sharing">Sharing</h3>
+
+<dl>
+<dt class="flush"><code>S()</code></dt><dd><p>Mechanism for sharing code.  When called with a block, it shares the given
+block (under a given identifier) for injection into other tests.  When
+called without a block, it injects a previously shared block (under a given
+identifier) into the environment where it is called.</p></dd>
+<dt class="flush"><code>S!()</code></dt><dd><p>Combination of the two uses of the <code>S()</code> method: it lets you simultaneously
+share a block of code while injecting it into the environment where that
+method is called.</p></dd>
+<dt class="flush"><code>S?()</code></dt><dd><p>Checks whether any code has been shared under a given identifier.</p></dd>
+</dl>
+
+
+<h3 id="Insulation">Insulation</h3>
+
+<p>The <code>D!()</code> method defines a new test that is explicitly insulated from
+the tests that contain it and also from the top-level Ruby environment.
+Root-level calls to the <code>D()</code> method are insulated by default.</p>
+
+<p>Inside an insulated test, you are free to mix-in any modules your test
+logic needs and also define your own constants, methods, and classes.</p>
+
+<h2 id="ASSERTIONS">ASSERTIONS</h2>
+
+<p>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 failure reports (see <strong>Failures</strong> below) if they fail.</p>
+
+<dl>
+<dt class="flush"><code>T()</code></dt><dd><p>assert true (not <code>nil</code> and not <code>false</code>)</p></dd>
+<dt class="flush"><code>F()</code></dt><dd><p>assert not true (<code>nil</code> or <code>false</code>)</p></dd>
+<dt class="flush"><code>E()</code></dt><dd><p>assert that an execption is raised</p></dd>
+<dt class="flush"><code>C()</code></dt><dd><p>assert that a symbol is thrown</p></dd>
+</dl>
+
+
+<h3 id="Negation">Negation</h3>
+
+<p>The following methods are the <em>opposite</em> of normal assertions.  They also
+accept an optional message, which is shown in failure reports (see
+<strong>Failures</strong> below) if they fail.</p>
+
+<dl>
+<dt class="flush"><code>T!()</code></dt><dd><p>same as <code>F()</code></p></dd>
+<dt class="flush"><code>F!()</code></dt><dd><p>same as <code>T()</code></p></dd>
+<dt class="flush"><code>E!()</code></dt><dd><p>assert that an exception is <em>not</em> raised</p></dd>
+<dt class="flush"><code>C!()</code></dt><dd><p>assert that a symbol is <em>not</em> thrown</p></dd>
+</dl>
+
+
+<h3 id="Sampling">Sampling</h3>
+
+<p>The following methods let you <em>check the outcome</em> of an assertion without
+recording a success or failure in the test execution report.</p>
+
+<dl>
+<dt class="flush"><code>T?()</code></dt><dd><p>returns true if <code>T()</code> passes; false otherwise</p></dd>
+<dt class="flush"><code>F?()</code></dt><dd><p>returns true if <code>F()</code> passes; false otherwise</p></dd>
+<dt class="flush"><code>E?()</code></dt><dd><p>returns true if <code>E()</code> passes; false otherwise</p></dd>
+<dt class="flush"><code>C?()</code></dt><dd><p>returns true if <code>C()</code> passes; false otherwise</p></dd>
+</dl>
+
+
+<h3 id="Failures">Failures</h3>
+
+<p>When an assertion fails, details about the failure will be shown:</p>
+
+<pre><code>- fail: block must yield true (!nil &amp;&amp; !false)
+  code: |-
+    [12..22] in test/simple.rb
+       12
+       13     D "with more nested tests" do
+       14       x = 5
+       15
+       16       T { x &gt; 2 }   # passes
+    =&gt; 17       F { x &gt; 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
+</code></pre>
+
+<p>You will then be placed into a debugger to investigate the failure if
+the <code>:debug</code> option is enabled in the <code>Dfect.options</code> hash.</p>
+
+<p>Details about all assertion failures and a trace of all tests executed
+are stored by Dfect and provided by the <code>Dfect.report()</code> method.</p>
+
+<h2 id="EMULATION">EMULATION</h2>
+
+<p>Dfect provides emulation layers for several popular testing libraries:</p>
+
+<dl>
+<dt>dfect/unit</dt><dd><p><a href="http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html">Test::Unit</a> emulation layer</p></dd>
+<dt>dfect/mini</dt><dd><p><a href="http://blog.zenspider.com/minitest/">Minitest</a> emulation layer</p></dd>
+<dt>dfect/spec</dt><dd><p><a href="http://rspec.info">RSpec</a> emulation layer</p></dd>
+</dl>
+
+
+<p>Simply load one of these emulation layers into your test suite and you can
+write your tests using the familiar syntax of that testing library.  See
+their source code for more information.</p>
+
+<h2 id="EXAMPLES">EXAMPLES</h2>
+
+<p>Begin by loading Dfect into your program:</p>
+
+<pre><code>require 'rubygems' # might not be necessary; see HACKING
+require 'dfect'
+</code></pre>
+
+<p>You now have access to the <code>Dfect</code> module, which provides methods that can
+be either mixed-in or called directly, according to your preference:</p>
+
+<pre><code>Dfect.D "hello" do  # D() is a class method
+  puts "world"
+end
+
+# the above is same as:
+
+include Dfect       # mix-in the Dfect API
+
+D "hello" do        # D() is an instance method
+  puts "world"
+end
+</code></pre>
+
+<h3 id="Logging-information-in-the-execution-report">Logging information in the execution report</h3>
+
+<p>When the following test is run:</p>
+
+<pre><code>require 'dfect/auto'
+
+D 'Wizard' do
+  L 'Preparing spell to defeat mortal foes...'
+end
+
+D 'Magician' do
+  L 'Preparing rabbits to pull from hat...', rand(15)
+end
+
+D 'Calculator' do
+  L Math::PI, [1, 2, 3, ['a', 'b', 'c']], {:foo =&gt; 'bar!'}
+end
+</code></pre>
+
+<p>Dfect will output the following:</p>
+
+<pre><code>--- 
+- Wizard: 
+  - Preparing spell to defeat mortal foes...
+- Magician: 
+  - Preparing rabbits to pull from hat...
+  - 0
+- Calculator: 
+  - 3.14159265358979
+  - - 1
+    - 2
+    - 3
+    - - a
+      - b
+      - c
+  - foo: bar!
+--- 
+time: 0.000182276
+</code></pre>
+
+<h3 id="Sharing-code-between-tests">Sharing code between tests</h3>
+
+<p>When the following test is run:</p>
+
+<pre><code>require 'dfect/auto'
+
+S :knowledge do
+  L 'Knowledge is power!'
+end
+
+D 'Healer' do
+  S :knowledge
+end
+
+D 'Warrior' do
+  S! :strength do
+    L 'Strength is power!'
+  end
+end
+
+D 'Wizard' do
+  S :knowledge
+  S :strength
+end
+
+D 'King' do
+  T { S? :knowledge }
+  T { S? :strength }
+  F { S? :power }
+  L 'Power is power!'
+end
+</code></pre>
+
+<p>Dfect will output the following:</p>
+
+<pre><code>--- 
+- Healer: 
+  - Knowledge is power!
+- Warrior: 
+  - Strength is power!
+- Wizard: 
+  - Knowledge is power!
+  - Strength is power!
+- King: 
+  - Power is power!
+--- 
+pass: 3
+time: 0.000436242
+</code></pre>
+
+<h3 id="Insulated-and-uninsulated-tests">Insulated and uninsulated tests</h3>
+
+<p>When the following test is run:</p>
+
+<pre><code>require 'dfect/auto'
+
+D "a root-level test" do
+  @outside = 1
+  T { defined? @outside }
+  T { @outside == 1 }
+
+  D "an inner, non-insulated test" do
+    T { defined? @outside }
+    T { @outside == 1 }
+  end
+
+  D! "an inner, insulated test" do
+    F { defined? @outside }
+    F { @outside == 1 }
+
+    @inside = 2
+    T { defined? @inside }
+    T { @inside == 2 }
+  end
+
+  F { defined? @inside }
+  F { @inside == 2 }
+end
+</code></pre>
+
+<p>Dfect will output the following:</p>
+
+<pre><code>--- 
+- a root-level test: 
+  - an inner, non-insulated test: []
+
+  - an inner, insulated test: []
+
+--- 
+pass: 10
+time: 0.000504211
+</code></pre>
+
+<h2 id="HACKING">HACKING</h2>
+
+<p>This section is meant for people who want to develop Dfect's source code.</p>
+
+<h3 id="Prerequisites">Prerequisites</h3>
+
+<p>Install Ruby libraries necessary for development:</p>
+
+<pre><code>gem install dfect --development
+</code></pre>
+
+<h3 id="Infrastructure">Infrastructure</h3>
+
+<p><a href="http://snk.tuxfamily.org/lib/inochi/">Inochi</a> serves as the project infrastructure for Dfect.  It handles tasks
+such as building this help manual and API documentation, and packaging,
+announcing, and publishing new releases.  See its help manual and list of
+tasks to get started:</p>
+
+<pre><code>inochi --help     # display help manual
+inochi --tasks    # list available tasks
+</code></pre>
+
+<h3 id="-LOAD_PATH-setup">$LOAD_PATH setup</h3>
+
+<p>Ensure that the <code>lib/</code> directory is listed in Ruby's <code>$LOAD_PATH</code> before you
+use any libraries therein or run any executables in the <code>bin/</code> directory.</p>
+
+<p>This can be achieved by passing an option to Ruby:</p>
+
+<pre><code>ruby -Ilib bin/dfect
+irb -Ilib -r dfect
+</code></pre>
+
+<p>Or by setting the <code>$RUBYLIB</code> environment variable:</p>
+
+<pre><code>export RUBYLIB=lib   # bash, ksh, zsh
+setenv RUBYLIB lib   # csh
+set -x RUBYLIB lib   # fish
+
+ruby bin/dfect
+irb -r dfect
+</code></pre>
+
+<p>Or by installing the <a href="http://github.com/chneukirchen/rup">ruby-wrapper</a> tool.</p>
+
+<h3 id="RubyGems-setup">RubyGems setup</h3>
+
+<p>If you use Ruby 1.8 or older, then ensure that RubyGems is activated before
+you use any libraries in the <code>lib/</code> directory or run any executables in the
+<code>bin/</code> directory.</p>
+
+<p>This can be achieved by passing an option to Ruby:</p>
+
+<pre><code>ruby -rubygems bin/dfect
+irb -rubygems -r dfect
+</code></pre>
+
+<p>Or by setting the <code>$RUBYOPT</code> environment variable:</p>
+
+<pre><code>export RUBYOPT=-rubygems   # bash, ksh, zsh
+setenv RUBYOPT -rubygems   # csh
+set -x RUBYOPT -rubygems   # fish
+</code></pre>
+
+<h3 id="Running-tests">Running tests</h3>
+
+<p>Simply execute the included test runner, which sets up Ruby's <code>$LOAD_PATH</code> for
+testing, loads the included <code>test/test_helper.rb</code> file, and then evaluates all
+<code>test/**/*_test.rb</code> files:</p>
+
+<pre><code>test/runner
+</code></pre>
+
+<p>Its exit status will indicate whether all tests have passed.  It may also
+print additional pass/fail information depending on the testing library used
+in the <code>test/test_helper.rb</code> file.</p>
+
+<h3 id="Contributing">Contributing</h3>
+
+<p>Fork this project on GitHub (see <strong>Resources</strong> above) and send a pull request.</p>
+
+<h2 id="VERSIONS">VERSIONS</h2>
+
+<p>This section contains release notes of current and past releases.</p>
+
+<h3 id="Version-2-2-0-2010-04-28-">Version 2.2.0 (2010-04-28)</h3>
+
+<p>This release adds a UNIX manual page and a sub-library for full method names.</p>
+
+<p>New features:</p>
+
+<ul>
+<li><p>Add <code>dfect/full</code> sub-library that provides full name aliases to Dfect's
+abbreviated vocabulary:</p>
+
+<p><code>D</code>escribe, <code>T</code>rue, <code>F</code>alse, <code>E</code>rror, <code>C</code>atch, <code>S</code>hare, and <code>L</code>og.</p></li>
+<li><p>Run <code>dfect --help</code> to see the UNIX manual page!</p></li>
+</ul>
+
+
+<p>Housekeeping:</p>
+
+<ul>
+<li>Upgrade to Inochi 3.0.0 and revise the help manual.</li>
+</ul>
+
+
+<h3 id="Version-2-1-0-2010-03-31-">Version 2.1.0 (2010-03-31)</h3>
+
+<p>This release adds a command-line test runner and performs some minor
+housekeeping.</p>
+
+<p>New features:</p>
+
+<ul>
+<li>Add <code>bin/dfect</code> executable as command-line interface to this library.</li>
+</ul>
+
+
+<p>Housekeeping:</p>
+
+<ul>
+<li><p>Do not <code>require 'rubygems'</code> before loading the "ruby-debug" library.</p></li>
+<li><p>Upgrade to Inochi 2.0.0-rc2 for managing this project.</p></li>
+</ul>
+
+
+<h3 id="Version-2-0-0-2010-03-21-">Version 2.0.0 (2010-03-21)</h3>
+
+<p>This release adds the ability to insulate tests from each other, share code
+between them, makes the order of parameters consistent in the API, improves
+user interactivity, fixes some bugs, and revises the user manual.</p>
+
+<p>Incompatible changes:</p>
+
+<ul>
+<li><p>Root-level calls to the <code>Dfect::D()</code>
+method are automatically insulated now.</p></li>
+<li><p>The <code>Dfect::E()</code> methods now expects its optional message
+parameter to be the <em>last parameter</em> in the parameter list.</p></li>
+<li><p>The <code>Dfect::C()</code> methods now expect their first parameter to
+be a symbol instead of the optional message to be shown in
+case of assertion failure.</p></li>
+<li><p>The <code>Dfect::R()</code> has been renamed to <code>Dfect::L()</code>,
+which is a mnemonic for "Logging".</p></li>
+<li><p>Shorten names of hash keys in the execution trace for brevity
+and rename <code>:raise</code> key in report statistics to <code>:error</code>.</p></li>
+<li><p>Only the most helpful subset of the failure details is shown before
+placing the user into a debugger because they can query the omitted
+information (on demand) inside the debugger.</p></li>
+<li><p>The execution trace is only shown if all tests passed in <code>Dfect::run()</code>.</p></li>
+<li><p>The <code>:debug</code> option is now set to Ruby's <code>$DEBUG</code> global by default.</p></li>
+</ul>
+
+
+<p>New features:</p>
+
+<ul>
+<li><p>Print failures as they occur instead of waiting until the end.</p></li>
+<li><p>Allow passing condition as argument to true/false assertions instead
+of requiring the condition to be passed as a code block, and also fall
+back to the binding of inner-most enclosing test or hook when
+debugging or constructing a failure report for an assertion that was
+not given a block.</p>
+
+<p>This allows you to reduce "line noise" in your tests:</p>
+
+<pre><code>D "Lottery" do
+  winning_ticket = rand()
+
+  D "My chances of winning" do
+    my_ticket = rand()
+    F my_ticket == winning_ticket, "I won?!  Dream on."
+  end
+end
+</code></pre></li>
+<li><p>Add <code>Dfect::S()</code> methods for sharing code between tests.</p></li>
+<li><p>Add <code>Dfect::D!()</code> method to explicitly insulate a test from other
+tests, the top-level Ruby environment, and the code being tested.</p></li>
+<li><p>Add <code>Dfect::info()</code> method which returns the details of
+the failure that is currently being debugged by the user.</p></li>
+<li><p>Add instance variables to the <code>:vars</code> section of a failure report.</p></li>
+<li><p>Add <code>setup!()</code> and <code>teardown!()</code> methods for before-all and
+after-all hooks in the dfect/unit emulation library.</p></li>
+<li><p>Add test execution time to statistics hash (under the <code>:time</code> key).</p></li>
+</ul>
+
+
+<p>Bug fixes:</p>
+
+<ul>
+<li><p>Do not print any output when <code>:quiet</code> option is active.</p></li>
+<li><p>Allow passing multiple strings/objects to <code>Dfect::D()</code> like in RSpec.</p></li>
+<li><p>Make before and after hook methods mixin-able like assertions.</p></li>
+<li><p>Do not assume that <code>Module#to_s</code> is the same as <code>Module#name</code>.</p></li>
+</ul>
+
+
+<p>Housekeeping:</p>
+
+<ul>
+<li><p>Upgrade to Inochi 2.0.0-rc1 for managing this project.</p></li>
+<li><p>Make emulation libraries modify Dfect module instead of Kernel.</p></li>
+<li><p>Do not pollute the user's output with our <code>Class#to_yaml</code> workaround.</p></li>
+<li><p>Remove "Motivation" section from user manual.  It was too fanatic!</p></li>
+</ul>
+
+
+<h3 id="Version-1-1-0-2009-10-27-">Version 1.1.0 (2009-10-27)</h3>
+
+<p>This release adds a new method for emitting status messages and does some
+internal housekeeping.</p>
+
+<p>Thank you:</p>
+
+<ul>
+<li>Iñaki Baz Castillo used Dfect and suggested new features.</li>
+</ul>
+
+
+<p>New features:</p>
+
+<ul>
+<li>Add <code>Dfect::S()</code> method for adding status messages to the
+execution report.  This feature was <a href="http://github.com/sunaku/dfect/issues/1">requested
+by</a> Iñaki Baz Castillo.</li>
+</ul>
+
+
+<p>Housekeeping:</p>
+
+<ul>
+<li><p>Remove unused require of 'delegate' standard library in 'dfect/spec'
+RSpec emulation layer.</p></li>
+<li><p>Mention emulation layers for popular testing libraries.</p></li>
+<li><p>Mention that assertions take an optional message parameter.</p></li>
+<li><p>Replace sample unit test with Dfect test suite.</p></li>
+<li><p>Upgrade user manual to ERBook 9.0.0.</p></li>
+</ul>
+
+
+<h3 id="Version-1-0-1-2009-10-07-">Version 1.0.1 (2009-10-07)</h3>
+
+<p>This release fixes a bug in the <a href="http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html">Test::Unit</a> emulation library and revises the
+user manual.</p>
+
+<p>Bug fixes:</p>
+
+<ul>
+<li>The parameters for the <code>assert_equal()</code> method in the
+dfect/unit library were in the wrong order.</li>
+</ul>
+
+
+<p>Housekeeping:</p>
+
+<ul>
+<li><p>Revise user manual to better fit jQuery UI tabs.</p></li>
+<li><p>Justify the use of <code>eval()</code> in emulation libraries.</p></li>
+<li><p>Use simpler Copyright reminder at the top of every file.</p></li>
+<li><p>Make SLOC count in user manual reflect the <em>core</em> library only.</p></li>
+<li><p>Mark code spans with <code>{:lang=ruby}</code> instead of HTML <code>&lt;code/&gt;</code> tags.</p></li>
+<li><p>Open source is for fun, so <a href="http://loiclemeur.com/english/2009/03/never-criticize-your-competitors.html">be nice</a> and speak of "related works" instead of "competitors".</p></li>
+</ul>
+
+
+<h3 id="Version-1-0-0-2009-05-03-">Version 1.0.0 (2009-05-03)</h3>
+
+<p>This release improves default choices, adds emulation layers to mimic other
+testing libraries, and fixes some bugs.</p>
+
+<p>Incompatible changes:</p>
+
+<ul>
+<li><p>The <code>:debug</code> option is now enabled by default and is no longer linked to
+the value of <code>$DEBUG</code>.</p></li>
+<li><p><code>Dfect.run()</code> now appends to previous results by default.</p>
+
+<p>This behavior can be disabled by passing <code>false</code> to the method.</p></li>
+</ul>
+
+
+<p>New features:</p>
+
+<ul>
+<li>Add emulation layers to mimic other testing libraries:
+
+<ul>
+<li>dfect/unit --- <a href="http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html">Test::Unit</a></li>
+<li>dfect/mini --- <a href="http://blog.zenspider.com/minitest/">Minitest</a></li>
+<li>dfect/spec --- <a href="http://rspec.info">RSpec</a></li>
+</ul>
+</li>
+</ul>
+
+
+<p>Bug fixes:</p>
+
+<ul>
+<li>Do not blindly replace <code>Class#to_yaml</code>; it might be fixed someday.</li>
+</ul>
+
+
+<p>Housekeeping:</p>
+
+<ul>
+<li><p>Add "Motivation" section in user manual to promote interactive
+debugging.</p></li>
+<li><p>Add brief History of this project's inception.</p></li>
+<li><p>Remove redundant assertions for F!() and T!() methods in test suite.</p></li>
+<li><p>Add copyright notice at the top of every file.</p></li>
+</ul>
+
+
+<h3 id="Version-0-1-0-2009-04-28-">Version 0.1.0 (2009-04-28)</h3>
+
+<p>This release adds new variations to assertion methods, fixes several bugs,
+and improves test coverage.</p>
+
+<p>Thank you:</p>
+
+<ul>
+<li>François Beausoleil contributed patches for both code <em>and</em> tests! :-)</li>
+</ul>
+
+
+<p>New features:</p>
+
+<ul>
+<li><p>Added negation (m!) and sampling (m?) variations to normal assertion
+methods.  These new methods implement assertion functionality missing so
+far (previously we could not assert that a given exception was NOT thrown)
+and thereby allow us to fully test Dfect using itself.</p></li>
+<li><p>Added documentation on how to insulate tests from the global Ruby
+namespace.</p></li>
+</ul>
+
+
+<p>Bug fixes:</p>
+
+<ul>
+<li><p>The <code>E()</code> method did not consider the case where a block does not raise
+anything as a failure. ---<em>François Beausoleil</em></p></li>
+<li><p>When creating a report about an assertion failure, an exception would be
+thrown if any local variables pointed to an empty array.</p></li>
+<li><p>The <code>Dfect::&lt;()</code> method broke the inheritance-checking behavior of the &lt;
+class method.</p>
+
+<p>Added a bypass to the originial behavior so that <code>RCov::XX</code> can properly
+generate a report about code that uses Dfect.</p></li>
+<li><p>Added workaround for YAML error when serializing a class object:</p>
+
+<pre><code>TypeError: can't dump anonymous class Class
+</code></pre></li>
+</ul>
+
+
+<p>Housekeeping:</p>
+
+<ul>
+<li>Filled the big holes in test coverage.  Everything except the runtime
+debugging logic is now covered by the unit tests.</li>
+</ul>
+
+
+<h3 id="Version-0-0-0-2009-04-13-">Version 0.0.0 (2009-04-13)</h3>
+
+<p>For the longest time, I took <a href="http://ruby-doc.org/stdlib/libdoc/test/unit/rdoc/classes/Test/Unit.html">Test::Unit</a> and <a href="http://rspec.info">RSpec</a> for granted.  They were
+the epitomy of modern Ruby practice; the insurmountable status quo;
+immortalized in books, conferences, and blogs alike.</p>
+
+<p>Why would <em>anyone</em> think of using anything remotely different, let alone be
+foolish enough to write an alternative testing library when these are clearly
+<em>good enough</em>?</p>
+
+<p>Recent experiments in assertion testing libraries smashed my world view:</p>
+
+<ul>
+<li><a href="http://assert2.rubyforge.org">assert{ 2.0 }</a></li>
+<li><a href="http://github.com/ahoward/testy/tree/master">Testy</a></li>
+<li><a href="http://www.ruby-forum.com/topic/183354">Verify</a></li>
+</ul>
+
+
+<p>The status quo was certainly <em>not</em> "good enough", as I had so blindly
+believed all these years.  In fact, they were <em>verbose</em> behemoths that chose
+to encode endless permutations of conjecture into methods.</p>
+
+<p>Empowered by this revelation and inspired by <a href="http://www.ruby-forum.com/topic/183354#801895">Sean O'Halpin's musing</a> on alternative names for
+assertion methods, I rose to challenge the status quo.</p>
+
+<p>And so I present to you the first public release of "Dfect".</p>
+
+<h2 id="AUTHORS">AUTHORS</h2>
+
+<p>Suraj N. Kurapati</p>
+
+<h2 id="CREDITS">CREDITS</h2>
+
+<p>François Beausoleil,
+Iñaki Baz Castillo,
+Sean O'Halpin</p>
+
+<h2 id="LICENSE">LICENSE</h2>
+
+<p>(the ISC license)</p>
+
+<p>Copyright 2009 Suraj N. Kurapati <a href="&#x6d;&#97;&#x69;&#x6c;&#x74;&#111;&#x3a;&#115;&#x75;&#110;&#97;&#x6b;&#117;&#64;&#103;&#x6d;&#x61;&#105;&#108;&#46;&#x63;&#111;&#x6d;" data-bare-link="true">&#115;&#x75;&#x6e;&#x61;&#107;&#x75;&#64;&#x67;&#109;&#x61;&#105;&#x6c;&#46;&#99;&#111;&#109;</a></p>
+
+<p>Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.</p>
+
+<p>THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.</p>
+
+<h2 id="SEE-ALSO">SEE ALSO</h2>
+
+<p><a href="http://assert2.rubyforge.org">assert{ 2.0 }</a>,
+<a href="http://github.com/ahoward/testy/tree/master">Testy</a>,
+<a href="http://www.ruby-forum.com/topic/183354">Verify</a></p>
+
+
+<ol class='foot man'>
+  <li class='tl'></li>
+  <li class='tc'>April 2010</li>
+  <li class='tr'>dfect(1)</li>
+</ol>
+
+</div>
+</body>
+</html>