PDFUnit and JUnit - Typical Examples

PDFUnit can test visible and invisible parts of a PDF document. Text from a PDF page can be processed as text or as a rendered image.

Furthermore, it is possible to compare many properties of a PDF document against a reference document.

The following examples show a small part of the capabilities.

Contents on individual PDF pages

 @Test
 public void hasText_OnIndividualPages() throws Exception {
   String filename = PATH + "content/diverseContentOnMultiplePages.pdf";
   PagesToUse page2 = PagesToUse.getPage(2);
  
   AssertThat.document(filename)
             .restrictedTo(page2)
             .hasText() 
             .containing("Lorem ipsum")
   ;
 }

---

Contents in a page region

The following example shows how to define and use a page region. Within the region the text can be checked with all available functions to compare normal text.

 // Comparing text in a part of a PDF page
 @Test
 public void hasText_OnFirstPage_InRegion() throws Exception {
   String filename = PATH + "content/diverseContentOnMultiplePages.pdf";
     
   int leftX  =  17;  // in millimeter
   int upperY =  45;
   int width  =  60;
   int height =   9; 
   PageRegion addressRegion = new PageRegion(leftX, upperY, width, height);
     
   AssertThat.document(filename)
             .restrictedTo(FIRST_PAGE)
             .restrictedTo(addressRegion)
             .hasText()                    
             .startingWith("Lorem")  
             .containing("ipsum") 
             .endingWith("est laborum.")
   ;
 }

---

Contents in form fields

Forms are often part of a process chain. So it has to be ensured that the generated form fields are correct. PDFUnit can check many properties of the fields and also the content.

 @Test
 public void hasField_MatchingComplete() throws Exception {
   String filename = PATH + "acrofields/letter.pdf";
   String fieldName = "customer-name";
   String expectedValue = "John";
   
   AssertThat.document(filename)
             .hasField(fieldName)
             .matchingComplete(expectedValue)
   ;
 }

---

Too much text in a form field?

A form field can contain so much text that it no longer fits into the field after rendering by a PDF reader. However, we can test for this situation. The PDF document used in the following example has such a field with too much text. So a test failure is expected.

 @Test(expected=PDFUnitError.class)
 public void hasFields_WithoutTextOverflow_Fieldname() throws Exception {
   String filename = PATH + "acrofields/fieldSizeAndText.pdf";
   String fieldname = "Textfield, too much text, multiline:";
 
   AssertThat.document(filename)
             .hasField(fieldname)
             .withoutTextOverflow()
   ;
 }

---

Compare rendered PDF pages with a reference

PDFUnit can compare both the text, as well as a rendered page with a reference document. The following example shows such a comparison which is also limited to a region of the first page.

 @Test
 public void haveSameAppearance_OnFirstPage_InRegion() throws Exception {
   String filenameTest = PATH + "test/test.pdf";
   String filenameReference = PATH + "reference/reference.pdf";
   
   int leftX  =  20;  // in millimeter
   int upperY =  20;
   int width  = 180;
   int height =  40; 
   PageRegion region = new PageRegion(leftX, upperY, width, height);

   AssertThat.document(filenameTest)
             .and(filenameReference)
             .restrictedTo(FIRST_PAGE)
             .restrictedTo(region)
             .haveSameAppearance()
   ;
 }

---

Contents in ZUGFeRD data

Often, the invisible ZUGFeRD data and the visible data of a PDF document should be the same. PDFUnit provides appropriate test methods for this requirement. The next example validates that the International Bank Account Number (IBAN) in the ZUGFeRD data is the same as the IBAN in a given region of the first page of a document:

 @Test
 public void validateIBANInZugferdData() throws Exception {
   String filename = PATH + "zugferd10/ZUGFeRD_1p0_BASIC_Einfach.pdf";
  
   XMLNode nodeIBAN = new XMLNode("ram:IBANID");
   PageRegion regionIBAN = createRegionIBAN();
  
   AssertThat.document(filename)
             .restrictedTo(FIRST_PAGE)
             .restrictedTo(regionIBAN)
             .hasText()
             .containingZugferdData(nodeIBAN)
   ;
 }

---

More examples

The manual contains detailed examples for all types of tests. It is available online or can be downloaded as PDF.