Chapter 8.  PDFUnit-Monitor

The PDFUnit-Monitor is an application that shows the result of PDFUnit tests. Tests are written in Excel files, so non-developers can create and run the tests.

The functional scope of the PDFUnit-Monitor is large. Therefore a detailed description of it exists as a separate file, also a demonstration video is available. Both can be downloaded with this link (download). The separate documentation provides also information about the installation and configuration of the PDFUnit-Monitor. The following sections briefly describe the main features.

Monitored Folders

The PDFUnit-Monitor monitors all PDF documents in a defined directory and its subdirectories. It checks the documents against rules which are read from Excel files. The Excel files have to lay also in the monitored directories. If new PDF documents were copied into the monitored directories, the tests started automatically. A manual start is not necessary but can be done. If a PDF document complies with all rules, its name in the folder tree is decorated with a green checkmark. When a PDF test fails, all violations will be listed. Additionally its name is decorated with a red cross. This status is transferred to the directory name. The name of a folder is decorated with a green checkmark only, when the folder itself and all subdirectories contain valid PDF documents. Otherwise, the folder is decorated with a red cross.

Folder with the name 'reference' are not watched. Such folders contain PDF documents which will be used as references when comparing actual documents under test.

The following picture shows the PDFUnit-Monitor. On the left side the folder structure with PDF and Excel files can be seen. The right side shows the validation results in the upper half and details of a selected message in the lower half.

A double click on a PDF or Excel document in the folder structure or in the error list opens the standard application of the operating system for the document.

Each element of the folder structure provides a context menu with various functions. The following figure shows an example:

Overview of Test Results with Filter Options

The Monitor shows all validation results as a list in the upper part of the right-hand side. Each constraint validation is one entry in the list. The details of a validation will be shown in the lower part of the right side when a list entry is selected.

The error list can be filtered by the names of PDF documents, folders, Excel files and regular expressions on error messages. The folder structure on the left side is connected with the filters on the right side. Each time, when a folder or a document is selected in the structure, a corresponding filter is set.

When a cell with a PDF or Excel document is double-clicked, the standard application of the operating system for that document type starts.

Details of an Error

When a row of the error list is selected all details of that entry will be shown in the lower part of the right side of the Monitor.

The first part of the error message was read from the Excel file. That part is designed by the person who created the tests. The next part of the message comes from PDFUnit. Additionally to the error message itself useful information about the PDF document, the constraint file and the execution time are provided.

The error messages of PDFUnit are currently in English and in German. Other languages can be provided with a little work, when requested.

Comparing a PDF with a Reference

PDF document can be compared to a reference. The rules for the comparison are read from Excel files. When the PDFUnit-Monitor detects a difference between the test and the referenced PDF the name of the test document will be decorated with a red cross.

A reference document has to have the same name as the PDF under test and has to be located in a subdirectory named 'reference' below that folder which contains the PDF under test.

If the validation detects a difference, the program 'DiffPDF 1.5.1 portable' can be started by clicking the right mouse button. That program marks the differences very clearly:

The program was created by Mark Summerfield and is available as a 'portable app' from this link (download). DiffPDF can be used in English, German, French and Czech. Many thanks to all who are involved for their work and the great result.

The next image shows the application DiffPDF just after it was started from the PDFUnit-Monitor. The left side shows the referenced PDF and the right side the current test PDF. The application points directly to the first difference, in this case to page 2. The differences are marked with a coloured background. The image does not show the buttons to navigate from one mismatch to the next.

Export and Import of Test Results

The test results can be exported as XML clicking the button 'Export' With XSLT stylesheets the exported files can be converted into HTML reports. With a click on the button 'Import' the can loaded again into the monitor.


The PDFUnit monitor is currently available for in English and in German. An extension to other languages ​​is structurally prepared and can be realized on demand with little effort.