PDF documents can be compared as rendered images (PNG) to ensure that a test document and a master document have the same layout.

<testcase name="haveSameAppearance_CompleteDocument">
  <assertThat testDocument="test/test.pdf"
              masterDocument="master/master.pdf"
  >
    <haveSameAppearance on="EVERY_PAGE" />
  </assertThat>
</testcase>

You can select individual pages in many ways. All possibilities are described in chapter 13.2: “Page Selection”.

You can compare the layout of entire pages or you can restrict the comparison to sections of a page:

<testcase name="haveSameAppearance_OnFirstPage_InClippingArea">
  <assertThat testDocument="test/test.pdf"
              masterDocument="master/master.pdf"
  >
    <haveSameAppearance on="FIRST_PAGE">
      <inClippingArea upperLeftX="50" upperLeftY="755" 
                      width="370" height="35" 
                      unit="POINTS"
      />
    </haveSameAppearance>
  </assertThat>
</testcase>

A clipping area can be defined using the measuring units POINTS, MILLIMETER, CENTIMETER, INCH and DPI72. All constants are declared with XML Schema for the attribute unit="..". If you omit a measuring unit, the values are taken as MILLIMETER.

In case of a test error, PDFUnit creates a diff image.

The diff image contains the name of the test in the header. And the name of the diff image is shown in the error message. That allows a cross reference between test and diff image.

The filename of a diff-image file is built as follows:

Due to the default configuration a diff image for test files is stored in the same directory in which the test file is located. Diff images for streams and byte arrays are stored in the home directory of the current Java process. You can change these settings in the config.properties file.

If you need to analyze the layout of two PDF documents after a test fails, you can use the very powerful program DiffPDF. Information about this Open-Source application by Mark Summerfield is available on the project site http://soft.rubypdf.com/software/diffpdf. You can install the program under Linux with a package manager, for example apt-get install diffpdf. On Windows you can use it as a “portable application” available from http://portableapps.com/apps/utilities/diffpdf_portable.