Images in a PDF document are seldom optical decorations of minor importance. More often, they transfer information which can have contractual meaning. Typical errors with images include:

All errors can be detected with these test methods:

// Testing images in PDF:
.hasImage().matching(..)
.hasImage().matchingOneOf(..)

.hasImage().withBarcode()           3.4: “Bar Code” 
.hasImage().withBarcodeInRegion()   3.4: “Bar Code” 
.hasImage().withText().xxx(..)      3.31: “Text - in Images (OCR)” 
.hasImage().withTextInRegion()      3.31: “Text - in Images (OCR)” 
.hasImage().withQRCode()            3.27: “QR Code” 
.hasImage().withQRCodeInRegion()    3.27: “QR Code” 
.hasImage().withHeightInPixel()
.hasImage().withWidthInPixel()

.hasNoImage()

.hasNumberOfDifferentImages(..)
.hasNumberOfVisibleImages(..)

The number of images inside a PDF document is typically not the same as the number of images you can see when it is printed. A logo visible on 10 pages is stored only once within the document. So, PDFUnit provides two test methods. The method hasNumberOfDifferentImages(..) validates the number of images stored internally and the method hasNumberOfVisibleImages(..) validates the number of visible images.

The following listing shows the syntax for verifing the number of images internally stored in PDF:

@Test
public void hasNumberOfDifferentImages() throws Exception {
  String filename = "documentUnderTest.pdf";
  
  AssertThat.document(filename)
            .hasNumberOfDifferentImages(2) 
  ;
}

How do you know in this example that “2” is the right number? How do you know which images are stored internally for a given PDF? The answer to both questions is given by the utility program ExtractImages. You can use it to extract all images from a document into separate files. Chapter 9.7: “Extract Images from PDF” describes this topic in detail.

The next example validates the number of visible images:

@Test
public void hasNumberOfVisibleImages() throws Exception {
  String filename = "documentUnderTest.pdf";
  
  AssertThat.document(filename)
            .hasNumberOfVisibleImages(8) 
  ;
}

The sample document has 8 images on 6 pages, but 2 images on page 3, no image on page 4 and 3 images on page 6.

The test for the visual images can be limited to specified pages. In the following example, only the images in a defined region on page 6 are counted:

@Test
public void numberOfVisibleImages() throws Exception {
  String filename = "documentUnderTest.pdf";
  
  int leftX  = 14; // in millimeter
  int upperY = 91;
  int width  = 96;
  int height = 43;
  PageRegion pageRegion = new PageRegion(leftX, upperY, width, height);
  PagesToUse page6 = PagesToUse.getPage(6);

  AssertThat.document(filename)
            .restrictedTo(page6)
            .restrictedTo(pageRegion)
            .hasNumberOfVisibleImages(1)
  ;
}

The same image shown twice on a page is counted twice.

The possibilities for limitting tests to specified pages are described in chapter 13.2: “Page Selection”.

After counting images you might need to test the images themselves. In the following example, PDFUnit verifies that a given image is part of a PDF document:

@Test  
public void hasImage() throws Exception {
  String filename = "documentUnderTest.pdf";
  String imageFile = "images/apache-software-foundation-logo.png";
  
  AssertThat.document(filename)
            .restrictedTo(ANY_PAGE)
            .hasImage()
            .matching(imageFile)
  ; 
}

The result of a comparison of two images depends on their file formats. PDFUnit can handle all image formats which can be converted into java.awt.image.BufferedImage: JPEG, PNG, GIF, BMP and WBMP. The images are compared byte by byte. Therefore, BMP and PNG versions of an image are not recognized as equal.

The picture may pass to the method in different types:

// Types for images:

.hasImage().matching(BufferedImage image);
.hasImage().matching(String imageFileName);
.hasImage().matching(File imageFile);
.hasImage().matching(InputStream imageStream);
.hasImage().matching(URL imageURL);

A tool which generates PDF files may do a format conversion when importing images from a file because not all image formats are supported in PDF. This might make it impossible for PDFUnit to successfully compare an image from the PDF file with the original image file. If you have encounter this problem, extract the images of the PDF under test into new image files and use them for the tests. Validate them 'by eye' first.

All images in a PDF document can be compared to the images of a referenced PDF. Those tests are described in chapter 4.8: “Comparing Images”.

It might be, that a PDF document contains one of three possible signature images. Use the method matchingOneOf(..) to test such a situation:

@Test
public void containsOneOfManyImages() throws Exception {
  BufferedImage signatureAlex = ImageHelper.getAsImage("images/signature-alex.png");
  BufferedImage signatureBob  = ImageHelper.getAsImage("images/signature-bob.png");
  BufferedImage[] allPossibleImages = {signatureAlex, signatureBob};

  String documentSignedByAlex = "letter-signed-by-alex.pdf";
  AssertThat.document(documentSignedByAlex)
            .restrictedTo(LAST_PAGE)
            .matchingOneOf(allPossibleImages)
  ;
  
  String documentSignedByBob = "letter-signed-by-bob.pdf";
  AssertThat.document(documentSignedByBob)
            .restrictedTo(LAST_PAGE)
            .matchingOneOf(allPossibleImages)
  ;
}

This test can also refer to several sides of a document, as the following section shows.

The tests for images can be restricted to single pages, multiple individual or multiple contiguous pages. All possibilities are described in chapter 13.2: “Page Selection”.

Here is an example:

@Test 
public void containsImage_OnAllPagesAfter5() throws Exception {
  String filename = "documentUnderTest.pdf";
  String imageFileName = "images/apache-ant-logo.jpg";
  File imageFile = new File(imageFileName);
  
  AssertThat.document(filename)
            .restrictedTo(EVERY_PAGE.after(5))
            .hasImage()
            .matching(imageFile)
  ; 
}

Some pages or page regions are meant to be empty. That can also be tested. The following example validates that the page body - without header and footer - does not have images or text:

@Test
public void lastPageBodyShouldBeEmpty() throws Exception {
  String pdfUnderTest = "documentUnderTest.pdf";
  PageRegion textBody = createBodyRegion();
  
  AssertThat.document(pdfUnderTest)
            .restrictedTo(LAST_PAGE)
            .restrictedTo(textBody)
            .hasNoImage()
            .hasNoText()
  ;
}