dfect 1.1.0 → 2.0.0

data/CREDITS

@@ -1,2 +1,2 @@
-* [François Beausoleil](http://github.com/francois)
-* [Iñaki Baz Castillo](http://github.com/ibc)
+- François Beausoleil <http://github.com/francois>
+- Iñaki Baz Castillo <http://github.com/ibc>

data/HISTORY

@@ -0,0 +1,306 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+%#----------------------------------------------------------------------------
+%| section "Version 2.0.0 (2010-03-21)"
+%#----------------------------------------------------------------------------
+
+  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.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Incompatible changes"
+  %#--------------------------------------------------------------------------
+
+    * Root-level calls to the `Dfect::D()` method are <%=
+      xref "Insulation", "automatically insulated" %> now.
+
+    * The `Dfect::E()` methods now expects its optional message
+      parameter to be the *last parameter* in the parameter list.
+
+    * The `Dfect::C()` methods now expect their first parameter to be a symbol
+      instead of the optional message to be shown in case of assertion failure.
+
+    * The `Dfect::R()` has been renamed to `Dfect::L()`,
+      which is a mnemonic for <%= xref "Logging" %>.
+
+    * Shorten names of hash keys in the execution trace for brevity
+      and rename `:raise` key in report statistics to `:error`.
+
+    * 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.
+
+    * The execution trace is only shown if all tests passed in `Dfect::run()`.
+
+    * The `:debug` option is now set to Ruby's `$DEBUG` global by default.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "New features"
+  %#--------------------------------------------------------------------------
+
+    * Print failures as they occur instead of waiting until the end.
+
+    * 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.
+
+      This allows you to reduce "line noise" in your tests:
+
+      %|code :ruby
+        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
+
+    %# XXX: this line protects the following list item from the above code
+    * Add <%= xref "Sharing", "`Dfect::S()` methods" %>
+      for sharing code between tests.
+
+    * Add <%= xref "Insulation", "`Dfect::D!()` method" %>
+      to explicitly insulate a test from other tests, the
+      top-level Ruby environment, and the code being tested.
+
+    * Add `Dfect::info()` method which returns the details of
+      the failure that is currently being debugged by the user.
+
+    * Add instance variables to the `:vars` section of a failure report.
+
+    * Add `setup!()` and `teardown!()` methods for before-all and
+      after-all hooks in the <tt>dfect/unit</tt> emulation library.
+
+    * Add test execution time to statistics hash (under the `:time` key).
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Bug fixes"
+  %#--------------------------------------------------------------------------
+
+    * Do not print any output when `:quiet` option is active.
+
+    * Allow passing multiple strings/objects to `Dfect::D()` like in RSpec.
+
+    * Make before and after hook methods mixin-able like assertions.
+
+    * Do not assume that `Module#to_s` is the same as `Module#name`.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Housekeeping"
+  %#--------------------------------------------------------------------------
+
+    * Upgrade to Inochi 2.0.0 for managing this project.
+
+    * Make emulation libraries modify Dfect module instead of Kernel.
+
+    * Do not pollute the user's output with our `Class#to_yaml` workaround.
+
+    * Remove "Motivation" section from user manual.  It was too fanatic!
+
+%#----------------------------------------------------------------------------
+%| section "Version 1.1.0 (2009-10-27)"
+%#----------------------------------------------------------------------------
+
+  This release adds a new method for emitting status messages and does some
+  internal housekeeping.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Thank you"
+  %#--------------------------------------------------------------------------
+
+    * Iñaki Baz Castillo used Dfect and suggested new features.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "New features"
+  %#--------------------------------------------------------------------------
+
+    * Add `Dfect::S()` method for <%= xref "Logging", "adding status
+      messages" %> to the execution report. This feature was [requested
+      by](http://github.com/sunaku/dfect/issues/closed#issue/1) Iñaki Baz
+      Castillo.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Housekeeping"
+  %#--------------------------------------------------------------------------
+
+    * Remove unused require of 'delegate' standard library in 'dfect/spec'
+      RSpec emulation layer.
+
+    * Mention <%= xref "Emulation" %> layers for popular testing libraries.
+
+    * Mention that assertions take an optional message parameter.
+
+    * Replace sample unit test with Dfect test suite.
+
+    * Upgrade user manual to ERBook 9.0.0.
+
+%#----------------------------------------------------------------------------
+%| section "Version 1.0.1 (2009-10-07)"
+%#----------------------------------------------------------------------------
+
+  This release fixes a bug in the Test::Unit emulation library and revises the
+  user manual.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Bug fixes"
+  %#--------------------------------------------------------------------------
+
+    * The parameters for the `assert_equal()` method in the
+      <tt>dfect/unit</tt> library were in the wrong order.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Housekeeping"
+  %#--------------------------------------------------------------------------
+
+    * Revise user manual to better fit jQuery UI tabs.
+
+    * Justify the use of `eval()` in emulation libraries.
+
+    * Use simpler Copyright reminder at the top of every file.
+
+    * Make SLOC count in user manual reflect the *core* library only.
+
+    * Mark code spans with `{:lang=ruby}` instead of HTML `<code/>` tags.
+
+    * Open source is for fun, so [be nice][1] and speak of "related works"
+      instead of "competitors".
+
+    [1]: http://loiclemeur.com/english/2009/03/never-criticize-your-competitors.html
+
+%#----------------------------------------------------------------------------
+%| section "Version 1.0.0 (2009-05-03)"
+%#----------------------------------------------------------------------------
+
+  This release improves default choices, adds emulation layers to mimic other
+  testing libraries, and fixes some bugs.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Incompatible changes"
+  %#--------------------------------------------------------------------------
+
+    * The `:debug` option is now enabled by default and is no longer linked to
+      the value of `$DEBUG`.
+
+    * `Dfect.run()` now appends to previous results by default.
+
+      This behavior can be disabled by passing `false` to the method.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "New features"
+  %#--------------------------------------------------------------------------
+
+    * Add emulation layers to mimic other testing libraries:
+      * <tt>dfect/unit</tt> --- Test::Unit
+      * <tt>dfect/mini</tt> --- Minitest
+      * <tt>dfect/spec</tt> --- RSpec
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Bug fixes"
+  %#--------------------------------------------------------------------------
+
+    * Do not blindly replace `Class#to_yaml`; it might be fixed someday.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Housekeeping"
+  %#--------------------------------------------------------------------------
+
+    * Add "Motivation" section in user manual to promote interactive
+      debugging.
+
+    * Add brief <%= xref "History" %> of this project's inception.
+
+    * Remove redundant assertions for F!() and T!() methods in test suite.
+
+    * Add copyright notice at the top of every file.
+
+%#----------------------------------------------------------------------------
+%| section "Version 0.1.0 (2009-04-28)"
+%#----------------------------------------------------------------------------
+
+  This release adds new variations to assertion methods, fixes several bugs,
+  and improves test coverage.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Thank you"
+  %#--------------------------------------------------------------------------
+
+    * François Beausoleil contributed patches for both code *and* tests! :-)
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "New features"
+  %#--------------------------------------------------------------------------
+
+      * Added <%= xref "Negation", "negation (m!)" %> and <%=
+        xref "Sampling", "sampling (m?)" %> variations to <%=
+        xref "Assertions", "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.
+
+    * Added documentation on <%= xref "Insulation", "how to insulate tests" %>
+      from the global Ruby namespace.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Bug fixes"
+  %#--------------------------------------------------------------------------
+
+    * The `E()` method did not consider the case where a block does not raise
+      anything as a failure. ---*François Beausoleil*
+
+    * When creating a report about an assertion failure, an exception would be
+      thrown if any local variables pointed to an empty array.
+
+    * The `Dfect::<()` method broke the inheritance-checking behavior of the <
+      class method.
+
+      Added a bypass to the originial behavior so that `RCov::XX` can properly
+      generate a report about code that uses Dfect.
+
+    * Added workaround for YAML error when serializing a class object:
+
+          TypeError: can't dump anonymous class Class
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Housekeeping"
+  %#--------------------------------------------------------------------------
+
+    * Filled the big holes in test coverage.  Everything except the runtime
+      debugging logic is now covered by the unit tests.
+
+%#----------------------------------------------------------------------------
+%| section "Version 0.0.0 (2009-04-13)"
+%#----------------------------------------------------------------------------
+
+  For the longest time, I took Test::Unit and [RSpec](http://rspec.info) for
+  granted.  They were the epitomy of modern Ruby practice; the insurmountable
+  status quo; immortalized in books, conferences, and blogs alike.
+
+  Why would *anyone* think of using anything remotely different, let alone be
+  foolish enough to write an alternative testing library when these are
+  clearly *good enough*?
+
+  Recent experiments in assertion testing libraries smashed my world view:
+
+  * [assert{ 2.0 }](http://assert2.rubyforge.org)
+  * [Testy](http://github.com/ahoward/testy/tree/master)
+  * [Verify](http://www.ruby-forum.com/topic/183354)
+
+  The status quo was certainly *not* "good enough", as I had so blindly
+  believed all these years.  In fact, they were *verbose* behemoths that chose
+  to encode endless permutations of conjecture into methods.
+
+  Empowered by this revelation and inspired by [Sean O'Halpin's musing][1] on
+  alternative names for assertion methods, I rose to challenge the status quo.
+
+  And so I present to you the first public release of "Dfect".
+
+  [1]: http://www.ruby-forum.com/topic/183354#801895
+

data/INSTALL

@@ -0,0 +1,35 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+%#----------------------------------------------------------------------------
+%| section "Prerequisites"
+%#----------------------------------------------------------------------------
+
+  * [Ruby](http://ruby-lang.org) 1.8.6 or newer.
+
+  * [RubyGems](http://rubygems.org) 1.3.6 or newer.
+
+  * [ruby-debug](http://www.datanoise.com/ruby-debug) will
+    be used if it is available.  Otherwise the standard
+    interactive Ruby shell (IRB) will be used instead.
+
+%#----------------------------------------------------------------------------
+%| section "Installing"
+%#----------------------------------------------------------------------------
+
+  %|command! "gem install dfect"
+
+%#----------------------------------------------------------------------------
+%| section "Upgrading"
+%#----------------------------------------------------------------------------
+
+  %|command! "gem update dfect"
+
+%#----------------------------------------------------------------------------
+%| section "Uninstalling"
+%#----------------------------------------------------------------------------
+
+  %|command! "gem uninstall dfect"
+

data/README

@@ -0,0 +1,95 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+%#----------------------------------------------------------------------------
+%| project_summary
+%#----------------------------------------------------------------------------
+
+  Dfect is an assertion testing library for Ruby that emphasizes a simple
+  assertion vocabulary, instant debuggability of failures, and flexibility in
+  composing tests.
+
+%#----------------------------------------------------------------------------
+%| paragraph "Resources"
+%#----------------------------------------------------------------------------
+
+  * <%= xref "History", "What's new?" %> ---
+    release notes and project history.
+
+  * [Issue tracker](<%= issue_tracker_url %>) ---
+    report bugs, request features, or ask for help.
+
+  * [Source code](<%= source_code_url %>) ---
+    browse online or obtain using <%= source_code_tool %>
+
+  * [API reference](<%= api_reference_url %>) ---
+    documentation for source code.
+
+  * [Project home](<%= Dfect::WEBSITE %>) ---
+    the official project home page.
+
+%#----------------------------------------------------------------------------
+%| section "Features"
+%#----------------------------------------------------------------------------
+
+  Dfect is exciting because:
+
+  * There are 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.
+
+  * Its core consists of a mere <%= `sloccount lib/dfect.rb`[/^\d+/] %> lines
+    of code.
+
+%#----------------------------------------------------------------------------
+%| section "Etymology"
+%#----------------------------------------------------------------------------
+
+  Dfect 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! ;-)
+
+  This wordplay is similar to [Mnesia][1]'s play on the word "amnesia",
+  whereby the intentional omission of the letter "A" indicates
+  forgetfulness---the key characteristic of having amnesia.  Clever!
+
+  [1]: http://www.erlang.org/doc/apps/mnesia/index.html
+
+%#----------------------------------------------------------------------------
+%| section "License"
+%#----------------------------------------------------------------------------
+
+  %# See the file named "LICENSE" for details.
+  %< "LICENSE"
+
+%#----------------------------------------------------------------------------
+%| section "Credits"
+%#----------------------------------------------------------------------------
+
+  Dfect is made possible by <%= xref "History",
+  "contributions" %> from users like you:
+
+  %# See the file named "CREDITS" for details.
+  %< "CREDITS"
+
+%#----------------------------------------------------------------------------
+%| section "Related works"
+%#----------------------------------------------------------------------------
+
+  * [assert{ 2.0 }](http://assert2.rubyforge.org)
+  * [Bacon](http://chneukirchen.org/repos/bacon/README)
+  * [Context](http://github.com/jeremymcanally/context)
+  * [minitest](http://blog.zenspider.com/minitest)
+  * [RSpec](http://rspec.info)
+  * [Shoulda](http://thoughtbot.com/projects/shoulda)
+  * [test-spec](http://test-spec.rubyforge.org/test-spec)
+  * [Test::Unit](http://www.ruby-doc.org/stdlib/libdoc/test/unit/rdoc/)
+  * [Testy](http://github.com/ahoward/testy/tree/master)
+  * [Verify](http://www.ruby-forum.com/topic/183354)

data/USAGE

@@ -0,0 +1,393 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+% def example_dfect_test *example_node_args, &block_containing_code_to_run
+  % code_to_run = __block_content__(&block_containing_code_to_run).join
+  % code_to_run.insert 0, "require 'dfect/auto'\n\n"
+
+  %|example! *example_node_args
+    When the following test is run:
+
+    <%
+      code :ruby do
+        code_to_run
+      end
+    %>
+
+    Dfect will output the following:
+
+    <%
+      text do
+        IO.popen('ruby -Ilib 2>&1', 'w+') do |ruby|
+          ruby.write code_to_run
+          ruby.close_write
+          ruby.read
+        end
+      end
+    %>
+
+Begin by loading Dfect into your program:
+
+%|code :ruby
+  require 'rubygems' # only necessary if you are using Ruby 1.8
+  require 'dfect'
+
+You now have access to the `Dfect` module, which provides methods that can be
+either mixed-in or called directly, according to your preference:
+
+%|code :ruby
+  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
+
+%#----------------------------------------------------------------------------
+%| section "Assertions"
+%#----------------------------------------------------------------------------
+
+  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_reference %> for more 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
+
+  %#--------------------------------------------------------------------------
+  %| section "Negation"
+  %#--------------------------------------------------------------------------
+
+    These methods are the *opposite* of
+    <%= xref "Assertions", "normal assertions" %>.
+
+    %|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
+
+  %#--------------------------------------------------------------------------
+  %| section "Sampling"
+  %#--------------------------------------------------------------------------
+
+    These methods allow you to *check the outcome* of an assertion without
+    recording a success or failure for that 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:
+
+        - 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 the `Dfect.options` hash.
+
+    Details about all assertion failures and a trace of all tests executed are
+    stored by Dfect and provided by the `Dfect.report()` method.
+
+  %#--------------------------------------------------------------------------
+  %| section "Emulation"
+  %#--------------------------------------------------------------------------
+
+    Dfect provides emulation layers for several popular testing libraries:
+
+    * <tt>dfect/unit</tt> --- Test::Unit
+    * <tt>dfect/mini</tt> --- Minitest
+    * <tt>dfect/spec</tt> --- RSpec
+
+    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.  See [their source code](<%= source_code_url
+    %>/tree/master/lib/dfect/) for more details.
+
+%#----------------------------------------------------------------------------
+%| section "Tests"
+%#----------------------------------------------------------------------------
+
+  The `D()` method defines a new Dfect **test**, which is analagous to the
+  concept of **test case** in xUnit or **describe** in rSpec.  A test may
+  contain nested tests.
+
+  %|code :ruby
+    D "outer test" do
+      # assertions and logic here
+
+      D "inner test" do
+        # more assertions and logic here
+      end
+    end
+
+  %#--------------------------------------------------------------------------
+  %| section "Execution"
+  %#--------------------------------------------------------------------------
+
+    Tests are executed in depth-first order.
+
+    You can configure the test execution process using:
+
+    %|code :ruby
+      Dfect.options = your_options_hash
+
+    You can execute all tests defined thus far using:
+
+    %|code :ruby
+      Dfect.run
+
+    You can stop the execution at any time using:
+
+    %|code :ruby
+      Dfect.stop
+
+    You can view the results of execution using:
+
+    %|code :ruby
+      puts Dfect.report.to_yaml
+
+    See the <%= api_reference %> for details and examples.
+
+    %#------------------------------------------------------------------------
+    %| paragraph "Automatic test execution"
+    %#------------------------------------------------------------------------
+
+      To mix-in the `Dfect` module into your program and execute all tests
+      defined by your program before it terminates, simply add the following
+      line at the top of your program:
+
+      %|code :ruby
+        require 'dfect/auto'
+
+    %#------------------------------------------------------------------------
+    %| section "Hooks"
+    %#------------------------------------------------------------------------
+
+      The `D()` method provides several entry points (hooks) into the test
+      execution process:
+
+      %|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
+          end
+        end
+
+      A hook method may be called multiple times.  Each call registers
+      additional logic to execute during the hook:
+
+      %|code :ruby
+        D .< { puts "do something" }
+        D .< { puts "do something more!" }
+
+    %#------------------------------------------------------------------------
+    %| section "Logging"
+    %#------------------------------------------------------------------------
+
+      The `L()` method lets you insert log messages, composed of arbitrary
+      Ruby objects, into the test execution report.
+
+      %|example_dfect_test "Logging information in the execution report"
+        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 => 'bar!'}
+        end
+
+  %#--------------------------------------------------------------------------
+  %| section "Sharing"
+  %#--------------------------------------------------------------------------
+
+    The `S()` method is a 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.
+
+    The `S!()` method is a combination of the two uses of the `S()` method: it
+    lets you simultaneously share a block of code while injecting it into the
+    environment where that method is called.
+
+    The `S?()` method simply checks whether any code has been shared under a
+    given identifier.
+
+    %|example_dfect_test "Sharing code between tests"
+      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
+
+  %#--------------------------------------------------------------------------
+  %| section "Insulation"
+  %#--------------------------------------------------------------------------
+
+    The `D!()` 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 `D()` method are insulated by default.
+
+    Inside an insulated test, you are free to:
+    * mix-in any modules your test logic needs
+    * define your own constants, methods, and classes
+
+    %|example_dfect_test "Insulated and uninsulated tests"
+      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
+