assert2 0.3.6 → 0.3.8

data/lib/assert2/xhtml.rb

@@ -0,0 +1,246 @@
+=begin
+One Yury Kotlyarov recently posted this Rails project as a question:
+
+  http://github.com/yura/howto-rspec-custom-matchers/tree/master
+
+It asks: How to write an RSpec matcher that specifies an HTML
+<form> contains certain fields, and enforces their properties
+and nested structure? He proposed [the equivalent of] this:
+
+    get :new  # a Rails "functional" test - on a controller
+
+    assert_xhtml do
+      form :action => '/users' do
+        fieldset do
+          legend 'Personal Information'
+          label 'First name'
+          input :type => 'text', :name => 'user[first_name]'
+        end
+      end
+    end
+
+The form in question is a familiar user login page:
+
+<form action="/users">
+  <fieldset>
+    <legend>Personal Information</legend>
+    <ol>
+      <li id="control_user_first_name">
+        <label for="user_first_name">First name</label>
+        <input type="text" name="user[first_name]" id="user_first_name" />
+      </li>
+    </ol>
+  </fieldset>
+</form>
+
+If that form were full of <%= eRB %> tags, testing it would be 
+mission-critical. (Adding such eRB tags is left as an exercise for 
+the reader!)
+
+This post creates a custom matcher that satisfies the following 
+requirements:
+
+ - the specification <em>looks like</em> the target code
+    * (except that it's in Ruby;)
+ - the specification can declare any HTML element type
+     _without_ cluttering our namespaces
+ - our matcher can match attributes exactly
+ - our matcher strips leading and trailing blanks from text
+ - the matcher enforces node order. if the specification puts
+     a list in collating order, for example, the HTML's order
+     must match
+ - the specification only requires the attributes and structural 
+     elements that its matcher demands; we skip the rest - 
+     such as the <ol> and <li> fields. They can change
+     freely as our website upgrades
+ - at fault time, the matcher prints out the failing elements
+     and their immediate context.
+
+First, we take care of the paperwork. This spec works with Yuri's
+sample website. I add Nokogiri, for our XML engine:
+=end
+
+require 'nokogiri'
+
+=begin
+That block after "response.body.should be_html_with" answers
+Yuri's question. Any HTML we can think of, we can specify
+it in there.
+
+If we inject a fault, such as :name => 'user[first_nome]', we 
+get this diagnostic:
+
+  <input type="text" name="user[first_nome]">
+  does not match
+  <fieldset>
+  <legend>Personal Information</legend>
+      <ol>
+  <li id="control_user_first_name">
+          <label for="user_first_name">First name</label>
+          <input type="text" name="user[first_name]" id="user_first_name">
+  </li>
+      </ol>
+  </fieldset>
+
+The diagnostic only reported the fault's immediate 
+context - the <fieldset> where the matcher sought the 
+errant <input> field. It would not, for example, spew
+an entire website into our faces.
+
+To support that specification, we will create a new
+RSpec "matcher":
+=end
+
+  class BeHtmlWith
+
+    def matches?(stwing, &block)
+   #   @scope.wrap_expectation self do
+        begin
+          bwock = block || @block || proc{}
+          builder = Nokogiri::HTML::Builder.new(&bwock)
+          match = builder.doc.root
+          doc = Nokogiri::HTML(stwing)
+          @last_match = 0
+          @failure_message = match_nodes(match, doc)
+          return @failure_message.nil?
+        end
+  #    end
+    end
+
+=begin
+The trick up our sleeve is Nokogiri::HTML::Builder. We passed
+the matching block into it - that's where all the 'form', 
+'fieldset', 'input', etc. elements came from. And this trick 
+exposes both our target page and our matched elements to the 
+full power of Nokogiri. Schema validation, for example, would 
+be very easy.
+
+The matches? method works by building two DOMs, and forcing
+our page's DOM to satisfy each element, attribute, and text
+in our specification's DOM.
+
+To match nodes, we first find all nodes, by name, below
+the current node. Note that match_nodes() recurses. Then
+we throw away all nodes that don't satisfy our matching
+criteria.
+
+We pick the first node that passes that check, and 
+then recursively match its children to each child,
+if any, from our matching node.
+=end
+ 
+ #  TODO does a multi-modal top axis work?
+ 
+    def match_nodes(match, doc)
+      node = doc.xpath("descendant::#{match.name.sub(/\!$/, '')}").
+                select{|n| resemble(match, n) }.
+                first or return complaint(match, doc)
+
+      this_match = node.xpath('preceding::*').length
+      
+      if @last_match > this_match
+        return complaint(match, doc, 'node is out of specified order!')
+      end
+      
+      @last_match = this_match
+
+      # http://www.zvon.org/xxl/XPathTutorial/Output/example18.html
+      # The preceding axis contains all nodes in the same document 
+      # as the context node that are before the context node in 
+      # document order, excluding any ancestors and excluding 
+      # attribute nodes and namespace nodes 
+
+#p [node.name, node.text]
+# p node.path if lastest
+#p node.text
+# p lastest.path if lastest
+
+        #  TODO  try xpath('*')
+      match.children.grep(Nokogiri::XML::Element).each do |child|
+        issue = match_nodes(child, node) and 
+          return issue
+      end
+
+      return nil
+    end
+    
+=begin
+At any point in that recursion, if we can't find a match,
+we build a string describing that situation, and pass it
+back up the call stack. This immediately stops any iterating
+and recursing underway!
+
+Two nodes "resemble" each other if their names are the
+same (naturally!); if your matching element's
+attributes are a subset of your page's element's 
+attributes, and if their text is similar:
+=end
+
+    def resemble(match, node)
+      keys = match.attributes.keys
+      node_keys = valuate(node.attributes.select{|k,v| keys.include? k })
+      match_keys = valuate(match.attributes)
+      node_keys == match_keys or return false
+        
+    #  TODO  try
+#       match_text = match.xpath('text()').map{|x|x.to_s}
+#        node_text = match.xpath('text()').map{|x|x.to_s}
+
+      match_text = match.children.grep(Nokogiri::XML::Text).map{|t| t.to_s.strip }
+       node_text = node .children.grep(Nokogiri::XML::Text).map{|t| t.to_s.strip }
+      match_text.empty? or 0 == ( match_text - node_text ).length
+    end
+
+=begin
+That method cannot simply compare node.text, because Nokogiri
+conglomerates all that node's descendants' texts together, and
+these would gum up our search. So those elaborate lines with
+grep() and map() serve to extract all the current node's 
+immediate textual children, then compare them as sets.
+
+Put another way, <form> does not appear to contain "First name".
+Specifications can only match text by declaring their immediate 
+parent.
+
+The remaining support methods are self-explanatory. They
+prepare Node attributes for comparison, build our diagnostics,
+and plug our matcher object into RSpec:
+=end
+ 
+    def valuate(attributes)
+      attributes.inject({}) do |h,(k,v)| 
+        h.merge(k => v.value) 
+      end  #  this converts objects to strings, so our Hashes
+    end    #  can compare for equality
+
+    def complaint(node, match, berate = nil)
+      "\n    #{berate}".rstrip +
+      "\n\n#{node.to_html}\n" +
+          "    does not match\n\n" +
+           match.to_html
+    end
+
+    attr_accessor :failure_message
+ 
+    def negative_failure_message
+      "yack yack yack"
+    end
+    
+    def initialize(scope, &block)
+      @scope, @block = scope, block
+    end
+  end
+
+module Test::Unit::Assertions
+  def assert_xhtml(xhtml = @response.body, &block)  # TODO merge
+   _assert_xml(xhtml) # , XML::HTMLParser)
+    if block
+     # require 'should_be_html_with_spec'
+      matcher = BeHtmlWith.new(self, &block)
+      matcher.matches?(xhtml, &block)
+      message = matcher.failure_message
+      flunk message if message.to_s != ''
+    end
+    return @xdoc
+  end
+end

data/lib/assert2/xhtml.rb~

@@ -0,0 +1,246 @@
+=begin
+One Yury Kotlyarov recently posted this Rails project as a question:
+
+  http://github.com/yura/howto-rspec-custom-matchers/tree/master
+
+It asks: How to write an RSpec matcher that specifies an HTML
+<form> contains certain fields, and enforces their properties
+and nested structure? He proposed [the equivalent of] this:
+
+    get :new  # a Rails "functional" test - on a controller
+
+    assert_xhtml do
+      form :action => '/users' do
+        fieldset do
+          legend 'Personal Information'
+          label 'First name'
+          input :type => 'text', :name => 'user[first_name]'
+        end
+      end
+    end
+
+The form in question is a familiar user login page:
+
+<form action="/users">
+  <fieldset>
+    <legend>Personal Information</legend>
+    <ol>
+      <li id="control_user_first_name">
+        <label for="user_first_name">First name</label>
+        <input type="text" name="user[first_name]" id="user_first_name" />
+      </li>
+    </ol>
+  </fieldset>
+</form>
+
+If that form were full of <%= eRB %> tags, testing it would be 
+mission-critical. (Adding such eRB tags is left as an exercise for 
+the reader!)
+
+This post creates a custom matcher that satisfies the following 
+requirements:
+
+ - the specification <em>looks like</em> the target code
+    * (except that it's in Ruby;)
+ - the specification can declare any HTML element type
+     _without_ cluttering our namespaces
+ - our matcher can match attributes exactly
+ - our matcher strips leading and trailing blanks from text
+ - the matcher enforces node order. if the specification puts
+     a list in collating order, for example, the HTML's order
+     must match
+ - the specification only requires the attributes and structural 
+     elements that its matcher demands; we skip the rest - 
+     such as the <ol> and <li> fields. They can change
+     freely as our website upgrades
+ - at fault time, the matcher prints out the failing elements
+     and their immediate context.
+
+First, we take care of the paperwork. This spec works with Yuri's
+sample website. I add Nokogiri, for our XML engine:
+=end
+
+require 'nokogiri'
+
+=begin
+That block after "response.body.should be_html_with" answers
+Yuri's question. Any HTML we can think of, we can specify
+it in there.
+
+If we inject a fault, such as :name => 'user[first_nome]', we 
+get this diagnostic:
+
+  <input type="text" name="user[first_nome]">
+  does not match
+  <fieldset>
+  <legend>Personal Information</legend>
+      <ol>
+  <li id="control_user_first_name">
+          <label for="user_first_name">First name</label>
+          <input type="text" name="user[first_name]" id="user_first_name">
+  </li>
+      </ol>
+  </fieldset>
+
+The diagnostic only reported the fault's immediate 
+context - the <fieldset> where the matcher sought the 
+errant <input> field. It would not, for example, spew
+an entire website into our faces.
+
+To support that specification, we will create a new
+RSpec "matcher":
+=end
+
+  class BeHtmlWith
+
+    def matches?(stwing, &block)
+   #   @scope.wrap_expectation self do
+        begin
+          bwock = block || @block || proc{}
+          builder = Nokogiri::HTML::Builder.new(&bwock)
+          match = builder.doc.root
+          doc = Nokogiri::HTML(stwing)
+          @last_match = 0
+          @failure_message = match_nodes(match, doc)
+          return @failure_message.nil?
+        end
+  #    end
+    end
+
+=begin
+The trick up our sleeve is Nokogiri::HTML::Builder. We passed
+the matching block into it - that's where all the 'form', 
+'fieldset', 'input', etc. elements came from. And this trick 
+exposes both our target page and our matched elements to the 
+full power of Nokogiri. Schema validation, for example, would 
+be very easy.
+
+The matches? method works by building two DOMs, and forcing
+our page's DOM to satisfy each element, attribute, and text
+in our specification's DOM.
+
+To match nodes, we first find all nodes, by name, below
+the current node. Note that match_nodes() recurses. Then
+we throw away all nodes that don't satisfy our matching
+criteria.
+
+We pick the first node that passes that check, and 
+then recursively match its children to each child,
+if any, from our matching node.
+=end
+ 
+ #  TODO does a multi-modal top axis work?
+ 
+    def match_nodes(match, doc)
+      node = doc.xpath("descendant::#{match.name.sub(/\!$/, '')}").
+                select{|n| resemble(match, n) }.
+                first or return complaint(match, doc)
+
+      this_match = node.xpath('preceding::*').length
+      
+      if @last_match > this_match
+        return complaint(match, doc, 'node is out of specified order!')
+      end
+      
+      @last_match = this_match
+
+      # http://www.zvon.org/xxl/XPathTutorial/Output/example18.html
+      # The preceding axis contains all nodes in the same document 
+      # as the context node that are before the context node in 
+      # document order, excluding any ancestors and excluding 
+      # attribute nodes and namespace nodes 
+
+#p [node.name, node.text]
+# p node.path if lastest
+#p node.text
+# p lastest.path if lastest
+
+        #  TODO  try xpath('*')
+      match.children.grep(Nokogiri::XML::Element).each do |child|
+        issue = match_nodes(child, node) and 
+          return issue
+      end
+
+      return nil
+    end
+    
+=begin
+At any point in that recursion, if we can't find a match,
+we build a string describing that situation, and pass it
+back up the call stack. This immediately stops any iterating
+and recursing underway!
+
+Two nodes "resemble" each other if their names are the
+same (naturally!); if your matching element's
+attributes are a subset of your page's element's 
+attributes, and if their text is similar:
+=end
+
+    def resemble(match, node)
+      keys = match.attributes.keys
+      node_keys = valuate(node.attributes.select{|k,v| keys.include? k })
+      match_keys = valuate(match.attributes)
+      node_keys == match_keys or return false
+        
+    #  TODO  try
+#       match_text = match.xpath('text()').map{|x|x.to_s}
+#        node_text = match.xpath('text()').map{|x|x.to_s}
+
+      match_text = match.children.grep(Nokogiri::XML::Text).map{|t| t.to_s.strip }
+       node_text = node .children.grep(Nokogiri::XML::Text).map{|t| t.to_s.strip }
+      match_text.empty? or 0 == ( match_text - node_text ).length
+    end
+
+=begin
+That method cannot simply compare node.text, because Nokogiri
+conglomerates all that node's descendants' texts together, and
+these would gum up our search. So those elaborate lines with
+grep() and map() serve to extract all the current node's 
+immediate textual children, then compare them as sets.
+
+Put another way, <form> does not appear to contain "First name".
+Specifications can only match text by declaring their immediate 
+parent.
+
+The remaining support methods are self-explanatory. They
+prepare Node attributes for comparison, build our diagnostics,
+and plug our matcher object into RSpec:
+=end
+ 
+    def valuate(attributes)
+      attributes.inject({}) do |h,(k,v)| 
+        h.merge(k => v.value) 
+      end  #  this converts objects to strings, so our Hashes
+    end    #  can compare for equality
+
+    def complaint(node, match, berate = nil)
+      "\n    #{berate}".rstrip +
+      "\n\n#{node.to_html}\n" +
+          "    does not match\n\n" +
+           match.to_html
+    end
+
+    attr_accessor :failure_message
+ 
+    def negative_failure_message
+      "yack yack yack"
+    end
+    
+    def initialize(scope, &block)
+      @scope, @block = scope, block
+    end
+  end
+
+module Test::Unit::Assertions
+  def assert_xhtml(xhtml = @response.body, &block)  # TODO merge
+   _assert_xml(xhtml) # , XML::HTMLParser)
+    if block
+     # require 'should_be_html_with_spec'
+      matcher = BeHtmlWith.new(self, &block)
+      matcher.matches?(xhtml, &block)
+      message = matcher.failure_message
+      flunk message if message.any?
+    end
+    return @xdoc
+  end
+end

data/lib/assert2/xpath.rb

@@ -3,6 +3,7 @@ require 'assert2'
 require 'rexml/document'
 require 'rexml/entity'
 require 'rexml/formatters/pretty'
+require 'nokogiri'  #  must be installed to use xpath{}!
 
 module Test; module Unit; module Assertions
   
@@ -30,6 +31,30 @@ module Test; module Unit; module Assertions
     end
   end 
 
+  def assert_xhtml_(xhtml)
+    return _assert_xml_(xhtml) # , XML::HTMLParser)
+  end 
+
+  def _assert_xml_(xml) #, parser = XML::Parser)
+    if false
+      xp = parser.new()
+      xp.string = xml
+      
+      if XML.respond_to? :'default_pedantic_parser='
+        XML.default_pedantic_parser = true
+      else
+        XML::Parser.default_pedantic_parser = true
+      end  #  CONSIDER  uh, figure out the best libxml-ruby??
+      
+      @xdoc = xp.parse.root
+    else
+      #  TODO  figure out how entities are supposed to work!!
+      xml = xml.gsub('—', '--')
+      doc = Nokogiri::XML(xml)
+      @xdoc = doc.root
+    end
+  end 
+
   class AssertXPathArguments
     
     def initialize(path = '', id = nil, options = {})
@@ -102,6 +127,35 @@ module Test; module Unit; module Assertions
     @xdoc = former_xdoc
   end  #  TODO trap LibXML::XML::XPath::InvalidPath and explicate it's an XPath problem
  
+  def xpath_(path, id = nil, options = {}, &block)
+    former_xdoc = @xdoc
+    apa = AssertXPathArguments.new(path, id, options)
+    node = @xdoc.xpath(apa.xpath) #, nil, apa.subs)
+       # TODO  advise Nokogiri to provide substitution arguments
+    
+    add_diagnostic :clear do
+      diagnostic = "xpath: #{ apa.xpath.inspect }\n"
+      diagnostic << "arguments: #{ apa.subs.pretty_inspect }\n" if apa.subs.any?
+      diagnostic + "xml context:\n" + indent_xml
+    end
+
+    if node
+      def node.[](symbol)
+        return attributes[symbol.to_s]
+      end
+    end
+
+    if block
+      assert_('this xpath cannot find a node', :keep_diagnostics => true){ node }
+      assert_ nil, :args => [@xdoc = node], :keep_diagnostics => true, &block  #  TODO  need the _ ?
+    end
+    
+    return node
+    # TODO raid http://thebogles.com/blog/an-hpricot-style-interface-to-libxml/
+  ensure
+    @xdoc = former_xdoc
+  end  #  TODO trap LibXML::XML::XPath::InvalidPath and explicate it's an XPath problem
+ 
   def indent_xml(node = @xdoc)
     bar = REXML::Formatters::Pretty.new
     out = String.new

data/lib/assert2.rb

@@ -81,6 +81,7 @@ module Test; module Unit; module Assertions
   end
 
   module Coulor  #:nodoc:
+    #  TODO  shell into term-ansicolor!
     def colorize(we_color)
       @@we_color = we_color
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: assert2
 version: !ruby/object:Gem::Version 
-  version: 0.3.6
+  version: 0.3.8
 platform: ruby
 authors: 
 - Phlip
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-02-15 00:00:00 -08:00
+date: 2009-03-11 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -23,14 +23,15 @@ extra_rdoc_files: []
 
 files: 
 - lib/assert2
+- lib/assert2/xhtml.rb~
 - lib/assert2/flunk.rb
 - lib/assert2/rubynode_reflector.rb
 - lib/assert2/xpath.rb
 - lib/assert2/ripper_reflector.rb
 - lib/assert2/ripdoc.html.erb
 - lib/assert2/ripdoc.rb
+- lib/assert2/xhtml.rb
 - lib/assert2.rb
-- lib/assert2.rb~
 has_rdoc: false
 homepage: http://assert2.rubyforge.org/
 post_install_message: 

data/lib/assert2.rb~

@@ -1,344 +0,0 @@
-require 'test/unit'
-
-#  FIXME  the first failing assertion of a batch should suggest you get with Ruby1.9...
-#  TODO  install Coulor (flibberty) 
-#  TODO  add :verbose => option to assert{}
-#  TODO  pay for Staff Benda Bilili  ALBUM: Tr�s Tr�s Fort (Promo Sampler) !
-#  TODO  evaluate parts[3]
-#  ERGO  if the block is a block, decorate with do-end
-#  ERGO  decorate assert_latest's block at fault time
-
-#~ if RUBY_VERSION > '1.8.6'
-  #~ puts "\nWarning: This version of assert{ 2.0 } requires\n" +
-       #~ "RubyNode, which only works on Ruby versions < 1.8.7.\n" +
-       #~ "Upgrade to Ruby1.9, and try 'gem install assert21'\n\n"
-#~ end
-
-  #~ def colorize(whatever)
-    #~ # FIXME stop ignoring this and start colorizing v2.1!
-  #~ end
-
-if RUBY_VERSION < '1.9.0'
-  require 'assert2/rubynode_reflector'
-else
-  require 'assert2/ripper_reflector'
-end
-
-#  CONSIDER  fix if an assertion contains more than one command - reflect it all!
-
-module Test; module Unit; module Assertions
-
-  FlunkError = if defined? Test::Unit::AssertionFailedError
-                 Test::Unit::AssertionFailedError
-               else
-                 MiniTest::Assertion
-               end
-
-  def add_diagnostic(whatever = nil, &block)
-    @__additional_diagnostics ||= []  #  TODO move that inside the reflector object, and persist it thru a test case event
-    
-    if whatever == :clear
-      @__additional_diagnostics = []
-      whatever = nil
-    end
-    
-    @__additional_diagnostics += [whatever, block]  # note .compact will take care of them if they don't exist
-  end
-
-  def assert(*args, &block)
-  #  This assertion calls a block, and faults if it returns
-  #  +false+ or +nil+. The fault diagnostic will reflect the
-  #  assertion's complete source - with comments - and will
-  #  reevaluate the every variable and expression in the
-  #  block.
-  #
-  #  The first argument can be a diagnostic string:
-  #
-  #    assert("foo failed"){ foo() }
-  #
-  #  The fault diagnostic will print that line.
-  # 
-  #  The next time you think to write any of these assertions...
-  #  
-  #  - +assert+
-  #  - +assert_equal+
-  #  - +assert_instance_of+
-  #  - +assert_kind_of+
-  #  - +assert_operator+
-  #  - +assert_match+
-  #  - +assert_not_nil+
-  #  
-  #  use <code>assert{ 2.1 }</code> instead.
-  #
-  #  If no block is provided, the assertion calls +assert_classic+,
-  #  which simulates RubyUnit's standard <code>assert()</code>.
-    if block
-      assert_ *args, &block
-    else
-      assert_classic *args
-    end
-    return true # or die trying ;-)
-  end
-
-  module Coulor  #:nodoc:
-    def colorize(we_color)
-      @@we_color = we_color
-    end
-    unless defined? BOLD
-      BOLD  = "\e[1m" 
-      CLEAR = "\e[0m" 
-    end       # ERGO  modularize these; anneal with Win32
-    def colour(text, colour_code)
-      return colour_code + text + CLEAR  if colorize?
-      return text
-    end
-    def colorize?  #  ERGO  how other libraries set these options transparent??
-      we_color = (@@we_color rescue true)  #  ERGO  parens needed?
-      return false if ENV['EMACS'] == 't'
-      return (we_color == :always or we_color && $stdout.tty?)
-    end
-    def bold(text)
-      return BOLD + text + CLEAR  if colorize?
-      return text
-    end
-    def green(text); colour(text, "\e[32m"); end
-    def red(text); colour(text, "\e[31m"); end
-    def magenta(text); colour(text, "\e[35m"); end
-    def blue(text); colour(text, "\e[34m"); end
-    def orange(text); colour(text, "\e[3Bm"); end
-  end
-  
-  class RubyReflector
-    attr_accessor :captured_block_vars,
-                  :args
-
-    include Coulor
-    
-    def split_and_read(called)
-      if called + ':' =~ /([^:]+):(\d+):/
-        file, line = $1, $2.to_i
-        return File.readlines(file)[line - 1 .. -1]
-      end
-      
-      return nil
-    end
-    
-    def __evaluate_diagnostics
-      @__additional_diagnostics.each_with_index do |d, x|
-        @__additional_diagnostics[x] = d.call if d.respond_to? :call
-      end
-    end  #  CONSIDER  pass the same args as blocks take?
-
-    def __build_message(reflection)
-      __evaluate_diagnostics
-      return (@__additional_diagnostics.uniq + [reflection]).compact.join("\n")
-    end  #  TODO  move this fluff to the ruby_reflector!
-
-    def format_inspection(inspection, spaces)
-      spaces = ' ' * spaces
-      inspection = inspection.gsub('\n'){ "\\n\" +\n \"" } if inspection =~ /^".*"$/
-      inspection = inspection.gsub("\n"){ "\n" + spaces }
-      return inspection.lstrip
-    end
-
-    def format_assertion_result(assertion_source, inspection)
-      spaces = " --> ".length
-      inspection = format_inspection(inspection, spaces)
-      return assertion_source.rstrip + "\n --> #{inspection.lstrip}\n"
-    end
-
-    def format_capture(width, snip, value)
-      return "#{ format_snip(width, snip) } --> #{ format_value(width, value) }"
-    end
-
-    def format_value(width, value)  #  TODO  width is a de-facto instance variable
-      width += 4
-      source = value.pretty_inspect.rstrip
-      return format_inspection(source, width)
-    end
-
-    def measure_capture(kap)
-      return kap.split("\n").inject(0){|x, v| v.strip.length > x ? v.strip.length : x } if kap.match("\n")
-      kap.length
-      # TODO  need the if?
-    end
-
-  end
-  
-  def colorize(to_color)
-    RubyReflector.new.colorize(to_color)
-  end
-
-  #  TODO  work with raw MiniTest 
-
-  # This is a copy of the classic assert, so your pre-existing
-  # +assert+ calls will not change their behavior
-  #
-  if defined? MiniTest::Assertion 
-    def assert_classic(test, msg=nil)
-      msg ||= "Failed assertion, no message given."
-      self._assertions += 1
-      unless test then
-        msg = msg.call if Proc === msg
-        raise MiniTest::Assertion, msg
-      end
-      true
-    end
-    
-    def add_assertion
-      self._assertions += 1
-    end
-  else
-    def assert_classic(boolean, message=nil)
-      #_wrap_assertion do
-        assert_block("assert<classic> should not be called with a block.") { !block_given? }
-        assert_block(build_message(message, "<?> is not true.", boolean)) { boolean }
-      #end
-    end
-  end
-
-  #  The new <code>assert()</code> calls this to interpret
-  #  blocks of assertive statements.
-  #
-  def assert_(diagnostic = nil, options = {}, &block)
-    options[:keep_diagnostics] or add_diagnostic :clear
-    
-    begin
-      if got = block.call(*options[:args])
-        add_assertion
-        return got
-      end
-    rescue FlunkError
-      raise  #  asserts inside assertions that fail do not decorate the outer assertion
-    rescue => got
-      add_exception got
-    end
-
-    flunk diagnose(diagnostic, got, caller[1], options, block)
-  end
-
-  def add_exception(ex)
-    ex.backtrace[0..10].each do |line|
-      add_diagnostic '  ' + line
-    end
-  end
-
-  #  This assertion replaces:
-  #  
-  #  - +assert_nil+
-  #  - +assert_no_match+
-  #  - +assert_not_equal+
-  #
-  #  It faults, and prints its block's contents and values,
-  #  if its block returns non-+false+ and non-+nil+.
-  #  
-  def deny(diagnostic = nil, options = {}, &block)
-      #  "None shall pass!" --the Black Knight
-      
-    options[:keep_diagnostics] or add_diagnostic :clear
-    
-    begin
-      got = block.call(*options[:args]) or (add_assertion and return true)
-    rescue FlunkError
-      raise
-    rescue => got
-      add_exception got
-    end
-  
-    flunk diagnose(diagnostic, got, caller[0], options, block)
-  end  #  "You're a looney!"  -- King Arthur
-
-  def deny_(diagnostic = nil, options = {}, &block)
-      #  "None shall pass!" --the Black Knight
-      
-    options[:keep_diagnostics] or add_diagnostic :clear
-    
-    begin
-      got = block.call(*options[:args]) or (add_assertion and return true)
-    rescue FlunkError
-      raise
-    rescue => got
-      add_exception got
-    end
-  
-    flunk diagnose(diagnostic, got, caller[0], options, block)
-  end  #  "You're a looney!"  -- King Arthur
-
-#  FIXME  document why this deny_ is here, and how to alias it back to deny
-
-  alias denigh deny  #  to line assert{ ... } and 
-                     #          denigh{ ... } statements up neatly!
-
-  #~ def __reflect_assertion(called, options, block, got)
-    #~ effect = RubyReflector.new(called)
-    #~ effect.args = *options[:args]
-    #~ return effect.reflect_assertion(block, got)
-  #~ end
-
-  #~ def __reflect_assertion(called, options, block, got)
-    #~ effect = RubyReflector.new(called)
-    #~ effect.args = *options[:args]
-    #~ effect.block = block
-    #~ return effect.reflect_assertion(block, got)  #  TODO  merge this and its copies into assert2_utilities
-  #~ end
-
-  #!doc!
-  def diagnose(diagnostic = nil, got = nil, called = caller[0],
-                options = {}, block = nil)                    #   TODO  make this directly callable
-    rf = RubyReflector.new
-    rf.diagnose(diagnostic, got, called, options, block, @__additional_diagnostics)
-    #~ options = { :args => [] }.merge(options)
-     #~ # CONSIDER only capture the block_vars if there be args?
-    #~ @__additional_diagnostics.unshift diagnostic
-    #~ return __build_message(__reflect_assertion(called, options, block, got))
-  end
-
-if RubyReflector::HAS_RUBYNODE
-  #  wrap this common idiom:
-  #    foo = assemble()
-  #    deny{ foo.bar() }
-  #    foo.activate()
-  #    assert{ foo.bar() }
-  #
-  #  that becomes:
-  #    foo = assemble()
-  #
-  #    assert_yin_yang proc{ foo.bar() } do
-  #      foo.activate()
-  #    end
-  #
-  def assert_yin_yang(*args, &block)
-      # prock(s), diagnostic = nil, &block)
-    procks, diagnostic = args.partition{|p| p.respond_to? :call }
-    block ||= procks.shift
-    source = reflect_source(&block)
-    fuss = [diagnostic, "fault before calling:", source].compact.join("\n")
-    procks.each do |prock|  deny(fuss, &prock);  end
-    block.call
-    fuss = [diagnostic, "fault after calling:", source].compact.join("\n")
-    procks.each do |prock|  assert(fuss, &prock);  end
-  end
-
-  #  the prock assertion must pass on both sides of the called block
-  #
-  def deny_yin_yang(*args, &block)
-      # prock(s), diagnostic = nil, &block)
-    procks, diagnostic = args.partition{|p| p.respond_to? :call }
-    block ||= procks.shift
-    source = reflect_source(&block)
-    fuss = [diagnostic, "fault before calling:", source].compact.join("\n")
-    procks.each do |prock|  assert(fuss, &prock);  end
-    block.call
-    fuss = [diagnostic, "fault after calling:", source].compact.join("\n")
-    procks.each do |prock|  assert(fuss, &prock);  end
-  end
-
-end
-
-end ; end ; end
-
-class File
-  def self.write(filename, contents)
-    open(filename, 'w'){|f|  f.write(contents)  }
-  end
-end