An XML Test Framework

Version: 0.1.5

Author: Henrik M?rtensson

(c) 2006 by Henrik M?rtensson


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:


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:

gem install testunitxml

If you have downloaded a gem package from Rubyforge, you can do a local installation:

cd download_directory_path

gem install testunitxml -l

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:


Unpack the Zip or tarball archive.


cd to the directory you just unpacked.


Run the command: ruby setup.rb install

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.


See the MIT-LICENSE file.


You can email bug reports, opinions and questions to [email protected]. 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 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.

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.