Introduction to XHTMLUnit

Purpose of XHTMLUnit

XHTMLUnit comes to your help whenever you want to generate some XHTML within your Java classes and don’t want or cannot use other web presentation technology like JSPs or XSLT. Moreover, it usually is a good idea nowadays to have XHTML as output whenever you can.

For those who don’t know: XHTML is HTML with a few changes and added features:

All tags are in lower case, thus <HTML> becomes <html> in XHTML.
All tags have to be balanced, i.e. every opening tag must have a corresponding closing tag or use the short form for a tag without. For example, write <p>This is a paragraph.</p> instead of <P>This is a paragraph. And <hr/> instead of <HR>.
XHTML 1.0 comes in three flavors or modes: strict, transitional and frameset. Each mode has a DTD of its own.

The advantage of using XHTML as opposed to HTML is basically that it can be easily validate using the appropriate DTD. From a programmer’s point of view XHTML is easier to test since you can develop and test it more easily – using the same techniques as when developing and testing other XML-based applications. One of the tools you are likely to use is XMLUnit, J. B. Rainsberger describes its efficient use in [Rainsberger04].

However, XMLUnit out of the box is sometimes awkward to use for testing XHTML generation. Some issues are:

It does not come with the appropriate DTDs, what makes using entities like > difficult to handle.
The default configuration of what is the same XML is not always useful for XHTML, e.g. in XHTML the order of elements is usually very important whereas by default XMLUnit ignores the order of elements with different tag names.

Therefore, XHTMLUnit builds on XMLUnit and provides you with some convenience code and configuration to facilitate testing the generation of XHTML, both of complete pages and of individual parts of a page.

Simple Example

Let’s do the most obvious thing, i.e. testing a complete html page:

<html>

<head><title>A Title</title></head>

</html>

We can test several things, checking for valid XHTML is one:

import java.io.*;

import junit.framework.TestCase;

import xhtmlunit.XHTMLTester;

public class FullPageTest extends TestCase {

public void testValidXHTML() throws Exception {

XHTMLTester tester = new XHTMLTester();

Reader reader = new InputStreamReader(

getClass().getResourceAsStream("page.html"));

tester.assertValid(reader);

}

XHTMLTester is XHTMLUnit’s most important class, just instantiate it and start testing.

The following test will assert that title and body are present and match expectations:

public class FullPageTest…

public void testTitleAndBody() throws Exception {

XHTMLTester tester = new XHTMLTester();

Reader reader = new InputStreamReader(...);

tester.assertXpathEvaluatesTo(
"A Title", "//title", reader);

reader = new InputStreamReader(...);

tester.assertXpathEvaluatesTo(

"This is the body", "//body", reader);

}

There’s much more you can do, e.g. asserting that an Xpath expressions exists and checking that two XHTML pages are equal (considering both structure and content).

Partial XHTML

Validating static XHTML in unit tests is not worth the effort in most cases; checking correct generation of (X)HTML, however, is crucial. That’s what XHTMLUnit has been made for in the first place. Consider a class XHTMLBuilder which supports the generation of various parts of a page:

public class XHTMLBuilder {

public static String buildTitle(String title) {...}

public static String buildTable(String contents) {...}

public static String buildRow(String contents) {...}

...

}

In order to test the individual methods you need a way to tell XHTMLUnit that only a certain part of a page is being expected. This can be done by calling XHTMLTester.setContextTag(...) as in the following example:

public class XHTMLBuilderTest extends TestCase {

public void testBuildTitle() throws Exception {

XHTMLTester tester = new XHTMLTester();

tester.setContextTag(XHTMLContextTag.HEAD);

String titleHtml = XHTMLBuilder.buildTitle("A Title");

tester.assertXHTMLEqual(

"<title>A Title</title>", titleHtml);

}

Features

Supports three XHTML modes: strict, transitional and frameset
Can check for HTML4 compatibility
Allows to check XHTML fragments
Exact meaning of contents equality can be configured, e.g. surplus attributes and child nodes can be ignored.

Requirements

Java 1.4 or above.

Installation

Add xhtmlunit-xxxx.jar and all the jars in lib/ to your class path.

References

[Rainsberger04] J. B. Rainsberger: JUnit Recipes, Manning Publications,
2004.

[XHTML] http://www.xhtml.org/

[XMLUnit] http://xmlunit.sourceforge.net/