rubyjedi-testunitxml 0.1.5

data/CHANGES

@@ -0,0 +1,19 @@
+= Changes
+
+== Version 0.1.5
+
+* Fixed a bug when comparing attributes containing entity references.
+* Added an <tt>assert_xml_not_equal</tt> method.
+
+== Version 0.1.4
+
+* Added support for Doctype comparisons in +assert_xml_equal+
+* Added <tt>setup.rb</tt> file to distribution packages
+* Added installation section to README file
+* Added links to online tutorial to README file
+* Added CHANGES file
+
+
+== Version 0.1.3
+
+The initial release.

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+= MIT-LICENSE
+
+Copyright � 2006 Henrik M�rtensson
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 
+IN THE SOFTWARE.

data/README

@@ -0,0 +1,119 @@
+= Test::Unit::XML
+== An XML Test Framework
+
+Version: 0.1.5
+
+Author: Henrik M�rtensson
+
+(c) 2006 by Henrik M�rtensson
+
+== Introduction
+
+Test::Unit::XML extends the Test::Unit framework with
+an assertion for testing well-formed XML documents.
+
+Using Test::Unit::XML is easy. All you have to do is to
+require +testunitxml+, and you will then have an
++assert_xml_equal+ assertion available in the
+Test::Unit::TestCase class.
+
+In addition to the API documentation included in the package, you can get information about how
+to use Test::Unit::XML from the following sources:
+
+* The online tutorial[http://kallokain.blogspot.com/2006/01/testunitxml-quick-start-tutorial.html] at
+  the Kallokain[http://kallokain.blogspot.com/] blog.
+* The {test cases}[link:../../test/] included in the distribution package.
+
+== Installation
+
+=== Install Using the +RubyGem+ Package Manager
+
+The easiest way to install Test::Unit::XML is to make a remote installation via the RubyGem
+package manager:
+
+<tt>gem install testunitxml</tt>
+
+If you have downloaded a gem package from Rubyforge, you can do a local installation:
+
+<tt>cd <em>download_directory_path</em></tt>
+
+<tt>gem install testunitxml -l</tt>
+
+=== Install from a Zip file or Tarball
+
+If you do not have RubyGem installed, you can download a Zip file or tarball and install
+from it instead:
+
+1::  Unpack the Zip or tarball archive.
+2::  cd to the directory you just unpacked.
+3::  Run the command:
+     <tt>ruby setup.rb install</tt>
+
+
+
+== What Does _Equal_ XML Documents Mean?
+
+It is hard to define exactly what _equal_ means in the
+context of XML documents. I have tried to follow W3C
+XML recommendations as far as possible. There are a
+few things worthy of note:
+
+* Namespace _declarations_, i.e. attributes that declare
+  namespaces, are ignored for comparison purposes. (The
+  namespaces _are_ used in comparisons.) The reason is
+  that XML processors may move the declarations from one
+  element to another, or change prefixes in ways that
+  cannot be directly controlled by a programmer. For
+  example, two different XSLT processors could use
+  the same stylesheet and produce XML documents that use
+  different namespace prefixes, and have declarations
+  on different elements, but are still considered equal.
+
+* Text nodes that are empty or contain only whitespace
+  are ignored for comparison purposes. This makes it
+  easier to test output from various transformation
+  engines. These often produce extraneous whitespace.
+
+== The Future
+
+There are a few things in the pipeline:
+
+* assert_xml_equal_structure - checks that the structure
+  of two documents are equal, but ignores content, attributes,
+  processing istructions, comments, CDATA, and doctype
+  declarations.
+* assert_xml_similar - Like assert_xml_equal, but ignores the
+  order of child elements.
+* Configurability. It _might_ be useful to be able to set
+  configuration options for testing. I'll have to think a
+  bit about this though.
+* Document difference functions, like the Java XMLUnit test
+  suite.
+
+I plan to implement these features as I need them in other
+projects, so there is no time plan, and no guarantee as to the
+order in which I'll implement anything.
+
+== License
+
+See the {MIT-LICENSE}[link:files/MIT-LICENSE.html] file.
+
+== Contact
+
+You can email bug reports, opinions and questions to
+mailto:self@henrikmartensson.org. You may also wish to visit
+my home page, www.henrikmartensson.org, for more information
+about Test::Unit::XML and other projects. I will write about
+Test::Unit::XML at the the Kallokain[http://kallokain.blogspot.com/]
+blog. You are welcome to visit, and comment.
+
+If you find Test::Unit::XML useful, please do tell me about it. I would like
+to list projects that use it on the {Test::Unit::XML web site}[http://testunitxml.rubyforge.org/].
+
+If you find Test::Unit::XML lacking in some respect, or buggy,
+I am even more interested. I can't fix bugs I do not know about.
+
+Finally, if you write about Test::Unit::XML, I'd like to link to
+the article on my web site, or at least mention it if you write
+for a magazine, so please tell me.
+

data/lib/test/unit/xml/attributes_mixin.rb

@@ -0,0 +1,21 @@
+module REXML
+  
+  # The REXML::Attributes mix-in adds methods that are useful for
+  # attribute collections, but not present in the standard
+  # REXML::Attributes class
+  class Attributes
+    
+    # The +get_attribute_ns+ method retrieves a method by its namespace
+    # and name. Thus it is possible to reliably identify an attribute
+    # even if an XML processor has changed the prefix.
+    def get_attribute_ns(namespace, name)
+      each_attribute() { |attribute|
+        if name == attribute.name &&
+           namespace == attribute.namespace()
+          return attribute
+        end
+      }
+      nil
+    end
+  end
+end

data/lib/test/unit/xml/conditionals.rb

@@ -0,0 +1,147 @@
+
+module Test
+  module Unit
+    module XML
+      
+      # This singleton class compares all types of REXML nodes.
+      class Conditionals
+        
+        private_class_method :new
+        @@conditionals = nil
+        
+        # The +create+ method is used to create a singleton instance
+        # of the Conditionals class.
+        def Conditionals.create
+          @@conditionals = new unless @@conditionals
+          @@conditionals
+        end
+        
+        # The method compares two REXML nodes representing an XML document,
+        # or part of a document. If the nodes are equal, the method returns
+        # +true+. If the nodes are not equal, the method returns +false+.
+        # If the nodes have child nodes, for example if the nodes are
+        # +Element+ nodes with content, they will _not_ be recursively compared.
+        def compare_xml_nodes(expected_node, actual_node)
+          #puts "Conditionals, Expected: #{expected_node.class} : #{expected_node.name}"
+          #puts "Conditionals, Expected: #{actual_node.class} : #{actual_node.name}"
+          return false unless actual_node.instance_of? expected_node.class
+          return false if expected_node == nil && actual_node != nil
+          return false if expected_node != nil && actual_node == nil
+          #puts "actual_node is nil" unless actual_node
+          #puts "expected_node is nil" unless expected_node
+          case actual_node
+          when REXML::Document
+            # TODO: Implement Document comparison
+            true
+          when REXML::DocType
+            compare_doctypes(expected_node, actual_node)
+          when REXML::Element
+            compare_elements(expected_node, actual_node)
+          when REXML::CData
+            compare_texts(expected_node, actual_node)
+          when REXML::Text
+            compare_texts(expected_node, actual_node)
+          when REXML::Comment
+            compare_comments(expected_node, actual_node)
+          when REXML::Instruction
+            compare_pi(expected_node, actual_node)
+          when REXML::XMLDecl
+            compare_xml_declaration(expected_node, actual_node)
+          #when REXML::Entity
+          #  compare_xml_entities(expected_node, actual_node)
+          else
+            puts "Unknown node type #{actual_node.class}"
+            false
+          end
+        end
+        
+        private
+        
+        def compare_doctypes(expected_node, actual_node)
+          return compare_system_id(expected_node.system, actual_node.system) &&
+            expected_node.public == actual_node.public &&
+            compare_xml_internal_dtd_subset(expected_node, actual_node)
+        end
+        
+        def compare_system_id(expected_id, actual_id)
+          is_expected_urn = expected_id =~ /^urn:/i
+          is_actual_urn = actual_id =~ /^urn:/i
+          if is_expected_urn || is_actual_urn
+            expected_id == actual_id
+          else
+            true
+          end
+        end
+        
+        def compare_elements(expected_node, actual_node)
+          return  expected_node.name == actual_node.name &&
+                  expected_node.namespace() == actual_node.namespace() &&
+                  compare_attributes(expected_node.attributes, actual_node.attributes)
+        end
+              
+        def compare_attributes(expected_attributes, actual_attributes)
+          return false unless attribute_count(expected_attributes) == attribute_count(actual_attributes)
+          expected_attributes.each_attribute do |expected_attribute|
+            expected_prefix = expected_attribute.prefix()
+            unless expected_prefix == 'xmlns' then
+              expected_name = expected_attribute.name
+              expected_namespace = expected_attribute.namespace
+              actual_attribute = actual_attributes.get_attribute_ns(expected_namespace, expected_name)
+              return false unless actual_attribute
+              return false if expected_attribute.value() != actual_attribute.value()
+            end
+          end
+          true
+        end
+        
+        def attribute_count(attributes)
+          # Do not count namespace declarations
+          attributes.size - attributes.prefixes.size
+        end
+            
+        def compare_texts(expected_node, actual_node)
+          expected_node.value.eql?(actual_node.value)
+        end  
+        
+        def compare_comments(expected_node, actual_node)
+          expected_node == actual_node
+        end
+        
+        def compare_pi(expected_pi, actual_pi)
+          return expected_pi.target == actual_pi.target &&
+                expected_pi.content == actual_pi.content
+        end
+        
+        def compare_xml_declaration(expected_decl, actual_decl)
+          return expected_decl == actual_decl
+        end
+        
+        def compare_xml_internal_dtd_subset(expected_node, actual_node)
+          expected_subset = expected_node.children()
+          actual_subset = actual_node.children()
+          return false unless expected_subset.length == actual_subset.length
+          expected_subset.inject(true) { |memo, expected_decl|
+            case expected_decl
+            when REXML::Entity
+              memo &&
+              expected_decl.value == actual_node.entities[expected_decl.name].value &&
+              expected_decl.ndata == actual_node.entities[expected_decl.name].ndata
+            when REXML::NotationDecl
+              actual_notation_decl = actual_node.notation(expected_decl.name)
+              memo &&
+              actual_notation_decl != nil &&
+              expected_decl.name == actual_notation_decl.name &&
+              expected_decl.public == actual_notation_decl.public &&
+              expected_decl.system == actual_notation_decl.system
+            when REXML::Comment
+              true
+            else
+              raise "Unexpected node type in internal DTD subset of expected document: " + expected_decl.inspect
+            end
+          }
+        end
+        
+      end
+    end
+  end
+end

data/lib/test/unit/xml/doctype_mixin.rb

@@ -0,0 +1,54 @@
+
+require 'test/unit/xml/notationdecl_mixin'
+
+module REXML
+
+  # The REXML::DocType mix-in adds methods that are useful for
+  # Doctype declarations, but not present in the standard
+  # REXML::DocType class
+  class DocType
+    
+    # This method retrieves the public identifier identifying the document's DTD.
+    def public
+      case @external_id
+      when "SYSTEM"
+        nil
+      when "PUBLIC"
+        strip_quotes(@long_name)
+      end
+    end
+    
+    # This method retrieves the system identifier identifying the document's DTD
+    def system
+      case @external_id
+      when "SYSTEM"
+        strip_quotes(@long_name)
+      when "PUBLIC"
+        @uri.kind_of?(String) ? strip_quotes(@uri) : nil
+      end
+    end
+    
+    # This method returns a list of notations that have been declared in the
+    # _internal_ DTD subset. Notations in the external DTD subset are not listed.
+    def notations
+      children().select {|node| node.kind_of?(REXML::NotationDecl)}
+    end
+    
+    # Retrieves a named notation. Only notations declared in the internal
+    # DTD subset can be retrieved.
+    def notation(name)
+      notations.find { |notation_decl|
+        notation_decl.name == name
+      }
+    end
+    
+    private
+    
+    def strip_quotes(quoted_string)
+      quoted_string =~ /^[\'\"].*[\�\"]$/ ?
+        quoted_string[1, quoted_string.length-2] :
+        quoted_string
+    end
+    
+  end
+end

data/lib/test/unit/xml/nodeiterator.rb

@@ -0,0 +1,67 @@
+#! /usr/bin/ruby
+
+module Test
+  module Unit
+    module XML
+      class NodeIterator
+        
+        class NullNodeFilter
+          def accept(node)
+            true
+          end
+        end
+        
+        # This class method takes a node as an argument and locates the
+        # next node. The first argument is a node. The second argument
+        # is an optional node filter.
+        def NodeIterator.find_next_node(node, node_filter = NullNodeFilter.new)
+          #puts "In NodeIterator: #{node.class}"
+          #puts "  has_children: #{NodeIterator.has_children?(node)}"
+          #puts "  next_sibling_node: #{node.next_sibling_node}"
+          #puts "  has_parent_with_sibling?: #{NodeIterator.has_parent_with_sibling?(node)}"
+          #node.write if node.respond_to?(:name) && node.name == 'TestThing'
+          return nil unless node
+          next_node = nil
+          if NodeIterator.has_children?(node) then
+            next_node = node[0] # The index should be 1 according to the REXML docs
+          elsif node.next_sibling_node
+            next_node = node.next_sibling_node
+          elsif NodeIterator.has_parent_with_sibling?(node)
+            next_node = node.parent.next_sibling_node
+          end
+          return next_node if node_filter.accept(next_node) || next_node == nil
+          find_next_node(next_node, node_filter)
+        end
+        
+        
+        def initialize(node, node_filter = NullNodeFilter.new)
+          @node_filter = node_filter
+          @next_node = node
+        end
+        
+        def has_next()
+          @next_node ? true : false
+        end
+        
+        def next
+          node = @next_node
+          @next_node = NodeIterator.find_next_node(node, @node_filter)
+          node
+        end
+        
+        
+        
+        
+        private
+        
+        def NodeIterator.has_children?(node)
+         node.respond_to?(:[]) && node.respond_to?(:size) && node.size > 0
+        end
+        
+        def NodeIterator.has_parent_with_sibling?(node)
+          node.parent && node.parent.next_sibling_node
+        end
+      end
+    end
+  end
+end

data/lib/test/unit/xml/notationdecl_mixin.rb

@@ -0,0 +1,54 @@
+module REXML
+
+  # The REXML::NotationDecl mix-in adds methods that are useful for
+  # notation declarations, but not present in the standard
+  # REXML::NotationDecl class
+  class NotationDecl
+    
+    # This method retrieves the name of the notation.
+    def name
+      @name
+    end
+    
+    # This method retrieves the system identifier specified in the notation
+    # declaration. If there is no system identifier defined, the method returns
+    # +nil+
+    def system
+      parse_rest(@rest)[1]
+    end
+    
+    # This method retrieves the public identifier specified in the notation
+    # declaration. If there is no public identifier defined, the method returns
+    # +nil+
+    def public
+      return nil unless @middle == "PUBLIC"
+      parse_rest(@rest)[0]
+    end
+    
+    private
+    
+    def parse_rest(rest)
+      case rest
+      when /^"([^"]+)"\s+"([^"]+)"$/
+        return [$1,$2]
+      when /^'([^']+)'\s+'([^']+)'$/
+        return [$1,$2]
+      when /^"([^"]+)"\s+'([^']+)'$/
+        return [$1,$2]
+      when /^'([^']+)'\s+"([^"]+)"$/
+        return [$1,$2]
+      when /^"([^"]+)"$/
+        return [nil, $1] if @middle == 'SYSTEM'
+        return [$1, nil] if @middle == 'PUBLIC'
+        raise "Unknown notation keyword: #{@middle}"
+      when /^'([^']+)'$/
+        return [nil, $1] if @middle == 'SYSTEM'
+        return [$1, nil] if @middle == 'PUBLIC'
+        raise "Unknown notation keyword: #{@middle}"
+      else
+        raise "Could not parse \@rest variable in REXML::NotationDecl: |#{@rest}|"
+      end
+    end
+  end
+
+end

data/lib/test/unit/xml/xml_assertions.rb

@@ -0,0 +1,163 @@
+#! /usr/bin/ruby
+
+require 'rexml/document'
+require 'test/unit/xml/attributes_mixin' # Must be required after rexml/document
+require 'test/unit/xml/doctype_mixin' # Must be required after rexml/document
+require 'test/unit/xml/notationdecl_mixin' # Must be required after rexml/document
+require 'test/unit'
+require 'test/unit/xml/conditionals'
+require 'test/unit/xml/xmlequalfilter'
+require 'test/unit/xml/nodeiterator'
+
+=begin rdoc
+This module contains assertions about XML documents. The assertions are
+meant to be mixed in to test classes such as Test::Unit::TestCase.
+=end
+module Test
+  module Unit
+    module XML
+      
+      # This method checks whether two well-formed XML documents are equal.
+      # Two XML documents are considered equal if:
+      # * They contain the same type of nodes, in the same order,
+      #   except for text nodes that are empty, or contain only
+      #   whitespace. Such text nodes are ignored.
+      # * The corresponding nodes in the two documents are equal.
+      #
+      # Nodes are tested for equality as follows:
+      # XML Declarations::
+      #      XML declarations are equal if they have the same version,
+      #      encoding, and stand-alone pseudo-attributes.
+      # Doctype::
+      #      Doctypes are equal if they fulfill all of the following conditions:
+      #      * They have the same public identifier, or neither has a public identifier
+      #      * If one of the doctypes has a system identifier that is a URN,
+      #        the other doctype must have a system identifier that is the same URN.
+      #        System identifiers that are URLs are ignored for comparison purposes.
+      #        The reason is that the same DTD is very often stored in many different
+      #        locations (for example different directories on different computers).
+      #        Therefore the physical location of the DTD does not say anything useful
+      #        about whether two documents are equal.
+      #      * An entity declaration present in one of the doctype declarations
+      #        must also be present in the other.
+      #      * A notation declaration present in one of the doctype declarations
+      #        must also be present in the other.
+      # Internal General Entity Declaration::
+      #      Internal General entity declarations are equal if they have the same name,
+      #      and the same value.
+      # External General Entity Declaration::
+      #      External general entity declarations are equal if they have the same name,
+      #      and if the identifiers are of the same type (PUBLIC or SYSTEM) and have
+      #      the same value. Note that if the identifiers are URLs, a comparison may
+      #      fail even though both URLS point to the same resource, for example if one
+      #      URL is relative and the other is absolute.
+      # Notation Declaration::
+      #      Notation declarations are equal if they have the same name,
+      #      and if the identifiers are of the same type (PUBLIC or SYSTEM) and have
+      #      the same value. 
+      # Elements::
+      #      Elements are considered equal if they have the same generic
+      #      identifier (tag name), belong to the same namespace, and have the same
+      #      attributes. Note that the namespace _prefixes_ of two elements may be different
+      #      as long as they belong to the same namespace.
+      # Attributes::
+      #      Attributes are equal if they belong to the same namespace,
+      #      have the same name, and the same value.
+      # Namespace Declarations::
+      #      Namespace _declarations_ (attributes named <tt>xmlns:<em>prefix</em></tt>)
+      #      are ignored. There are several reasons for this:
+      #      - As long as two elements or attributes
+      #        belong to the same namespace, it does not matter what prefixes
+      #        are used. XML processors may also change prefixes in unpredictable
+      #        ways without this being an error.
+      #      - XML processors may _move_ namespace
+      #        declarations from one element to another (usually an ancestor,
+      #        sometimes a descendant) without this being an error, or under
+      #        control by the programmer.
+      #      - XML processors may _add_ extraneous namespace declarations
+      #        in a manner that is hard for programmers to control.
+      # Processing Instructions::
+      #      Processing instructions are considered equal if the string
+      #      values of their targets and contents are equal.
+      # Text::
+      #      Text nodes are equal if their values are equal. However, empty
+      #      text nodes, and text nodes containing only whitespace are ignored.
+      # CDATA::
+      #      CDATA nodes are equal if their text content is equal. Whitespace
+      #      is _not_ normalized.
+      # Comments::
+      #      Comments are equal if they have the same content.
+      #
+      # The +expected_doc+ and +actual_doc+ arguments to this method may be of
+      # the following types:
+      # * A +REXML+ node, usually a <tt>REXML::Document</tt> or <tt>REXML::Element</tt>
+      # * A +File+ or other +IO+ object representing an XML document
+      # * A string containing an XML document
+      def assert_xml_equal(expected_doc, actual_doc, message = nil)
+        expected_doc = parse_xml(expected_doc)
+        actual_doc = parse_xml(actual_doc)
+        _wrap_assertion do
+          full_message = build_message(message, <<EOT, actual_doc.inspect, expected_doc.inspect)
+
+<?> expected to be equal to
+<?> but was not.
+EOT
+          assert_block(full_message){are_equal?(expected_doc, actual_doc)}
+        end
+      end
+      
+      
+      # This method compares two XML documents and returns +true+ if they are
+      # _not_ equal, +false+ otherwise. This is the inverse of assert_xml_equal.
+      def assert_xml_not_equal(expected_doc, actual_doc, message = nil)
+        expected_doc = parse_xml(expected_doc)
+        actual_doc = parse_xml(actual_doc)
+        _wrap_assertion do
+          full_message = build_message(message, <<EOT, actual_doc.inspect, expected_doc.inspect)
+
+<?> expected not to be equal to
+<?> but was equal.
+EOT
+          assert_block(full_message){ ! are_equal?(expected_doc, actual_doc)}
+        end
+      end
+      
+      
+      private
+      
+      def parse_xml(xml)
+        case xml
+        when IO
+          REXML::Document.new(xml)
+        when String
+          REXML::Document.new(xml)
+        else
+          xml
+        end
+      end
+      
+      def are_equal?(expected_doc, actual_doc)
+        comparator = Conditionals.create
+        iterate(expected_doc, actual_doc) do |expected_node, actual_node|
+          unless comparator.compare_xml_nodes(expected_node, actual_node)
+            return false
+          end
+        end
+        true
+      end
+      
+      def iterate(expected_doc, actual_doc)
+        filter = Test::Unit::XML::XmlEqualFilter.new()
+        expected_iterator = NodeIterator.new(expected_doc, filter)
+        actual_iterator = NodeIterator.new(actual_doc, filter)
+        while expected_iterator.has_next()
+          expected_node = expected_iterator.next()
+          actual_node = actual_iterator.next()
+          yield expected_node, actual_node
+        end
+      end
+
+    end
+  end
+end
+