dfect 0.0.0 → 0.1.0

data/doc/intro.erb

@@ -1,21 +1,32 @@
+% api_url = './api/index.html'
+% src_url = 'http://github.com/sunaku/' + $program
+% git_url = 'http://git-scm.com'
+
 %|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
+    <%= $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.
+    <%= $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:
+  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)
 
   %|paragraph "Etymology"
-    **<%= $project %>** is named after the 5 methods it provides: D F E C T.
+    <%= $project %> is named after the D F E C T methods it provides.
 
     The name is also play on the word "defect", whereby the intentional misspelling of "defect" as "dfect" is a defect in itself!  <tt>;-)</tt>
 
@@ -23,14 +34,14 @@
 
   %|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.
+    * [Source code](<%= src_url %>) --- obtain via [Git](<%= git_url %>) or browse online.
+    * [API reference](<%= api_url %>) --- 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*
+      <%= $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:
@@ -73,6 +84,8 @@
     %< "../LICENSE"
 
   %|section "Credits"
-    **<%= $project %>** is made possible by
+    <%= $project %> is made possible by
     <%= xref "History", "contributions" %>
-    from users like you.
+    from users like you:
+
+    %< "../CREDITS"

data/doc/setup.erb

@@ -1,6 +1,6 @@
 %|chapter "Setup"
   %|section "Requirements"
-    Your system needs the following software to run **<%= $project %>**.
+    Your system needs the following software to run <%= $project %>.
 
     | Software                                          | Description               | Notes                                                                                  |
     | --------                                          | -----------               | -----                                                                                  |
@@ -9,17 +9,17 @@
     | [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:
+    You can install <%= $project %> by running this command:
 
         gem install <%= $program %>
 
   %|section "Manifest"
-    You will see the following items inside **<%= $project %>**'s installation
+    You will see the following items inside <%= $project %>'s installation
     directory:
 
     * <tt>lib/</tt>
 
-      * <tt><%= $program %>.rb</tt> --- the main **<%= $project %>** library.
+      * <tt><%= $program %>.rb</tt> --- the main <%= $project %> library.
 
       * <tt><%= $program %>/</tt>
 

data/doc/usage.erb

@@ -1,17 +1,17 @@
 % dfect_api = 'api/classes/Dfect.html'
 
 %|chapter "Usage"
-  Begin by loading **<%= $project %>** into your program:
+  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):
+  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>
-  Dfect.D "hello" do
+  Dfect.D "hello" do  # D() is a not-mixed-in class method
     puts "world"
   end
 
@@ -19,52 +19,72 @@
 
   include Dfect
 
-  D "hello" do
+  D "hello" do        # D() is a mixed-in instance method
     puts "world"
   end
   </code>
 
-  The following sections explain these methods in detail.
+  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.  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
+    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`) |
+
+    %|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                                |
+
+    %|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 |
 
     %|section "Failures"
-      When an assertion fails, the details about the failure will be shown like this:
+      When an assertion fails, details about the failure will be shown:
 
       <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
+      - 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>
 
-      If the `:debug` option is enabled in [`Dfect.options`](<%= dfect_api %>), you will then be placed into a debugger to investigate the failure.
+      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.
+      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.
@@ -104,11 +124,54 @@
       D .< { puts "do something more!" }
       </code>
 
+    %|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>
+
+      Inside this insulated environment, you are free to:
+      * mix-in any modules your test logic needs
+      * define your own constants, methods, and classes
+
+      For example:
+
+      <code>
+      class << Object.new
+        include SomeModule
+        extend AnotherModule
+
+        YOUR_CONSTANT = 123
+
+        D "your tests here" do
+          # your test logic here
+
+          your_helper_method
+        end
+
+        def self.your_helper_method
+          # your helper logic here
+
+          helper = YourHelperClass.new
+          helper.do_something_helpful
+
+          T { 2 + 2 != 5 }
+        end
+
+        class YourHelperClass
+          # your helper logic here
+        end
+      end
+      </code>
+
   %|section "Execution"
     You can configure test execution using:
 
     <code>
-    Dfect.options = your_options
+    Dfect.options = your_options_hash
     </code>
 
     You can execute all tests defined thus far using:
@@ -159,27 +222,23 @@
 
           T { x > 2 }   # passes
           F { x > 2 }   # fails
-          E { x.hello } # fails
+          E { x.hello } # passes
         end
       end
 
-      # equivalent of before(:each) or setup()
-      D.< do
+      D .< do
         puts "this is executed before every test in this scope"
       end
 
-      # equivalent of after(:each) or teardown()
-      D.> do
+      D .> do
         puts "this is executed after every test in this scope"
       end
 
-      # equivalent of before(:all)
-      D.<< do
+      D .<< do
         puts "this is executed once, before all tests in this scope"
       end
 
-      # equivalent of after(:all)
-      D.>> do
+      D .>> do
         puts "this is executed once, after all tests in this scope"
       end
     end