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:

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:

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:


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

      <body>This is the body</body>


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


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(





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(...);

            "A Title", "//title", reader);

        reader = new InputStreamReader(...);


            "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();


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


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





Java 1.4 or above.


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


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