3.21.  Layout - in Page Regions

Overview

Comparing entire pages as rendered images will cause problems if a page contains variable content. A date is a typical example of content that changes frequently.

The syntax for comparing sections of a rendered page is very similiar to the syntax for comparing entire pages. The method isEqualToImage(..) is extended with the x/y values of the upper left corner used to position the image on the page. Only the area corresponding to the size of the image.

// Compare rendered page(s) with a given image. 
// The left-upper corner is defined by the given x/y values.
.asRenderedPage(..).isEqualToImage(upperLeftX, upperLeftY, FormatUnit, BufferedImage)
.asRenderedPage(..).isEqualToImage(upperLeftX, upperLeftY, FormatUnit, File)
.asRenderedPage(..).isEqualToImage(upperLeftX, upperLeftY, FormatUnit, imageFileName)
.asRenderedPage(..).isEqualToImages(upperLeftX, upperLeftY, FormatUnit, BufferedImage)
.asRenderedPage(..).isEqualToImages(upperLeftX, upperLeftY, FormatUnit, File)
.asRenderedPage(..).isEqualToImages(upperLeftX, upperLeftY, FormatUnit, imageFileName)

Example - Left Margin on Every Page

If you want to check that the left margin of each page is empty for at least 2 cm, then you can write this test:

@Test
public void compareAsRenderedPage_LeftMargin() throws Exception {
  String filename = "documentUnderTest.pdf";
  
  String fullImage2cmWidthFromLeft = "images/marginFullHeight2cmWidth.png";
  int leftX  = 0;
  int upperY = 0;
  
  AssertThat.document(filename)
            .restrictedTo(EVERY_PAGE)
            .asRenderedPage()
            .isEqualToImage(leftX, upperY, MILLIMETERS, fullImage2cmWidthFromLeft)
  ;
}

The image is 2 cm wide and as high as the page. It contains the background color of the PDF pages. So, the example verifies that the margin of each page has the same background color. That means the margin is empty.

Every section needs an x/y position within the PDF page. The values 0/0 correspond to the upper left corner of a page.

The test assumes that all pages of the PDF have the same size. If you want to check left margins for pages of different formats in a single PDF document, you have to write multiple tests, each for pages of the same format.

Example - Logo on Page 1 and 2

The next example verifies that the company logo is placed at an expected position on pages 1 and 2:

@Test  
public void verifyLogoOnEachPage() throws Exception {
  String filename = "documentUnderTest.pdf";
  String logo = "images/logo.png";
  
  int leftX  = 135;                                          1
  int upperY =  35;
  PagesToUse pages12 = PagesToUse.getPages(1, 2);            2
  
  AssertThat.document(filename)
            .restrictedTo(pages12)
            .asRenderedPage()
            .isEqualToImage(leftX, upperY, MILLIMETERS, logo) 3
  ;
}

1

Set the x/y position of the upper left corner of the region

2

Specify the pages, see chapter 13.2: “Page Selection”

3

Invoke the test method

Multiple Comparisons

Multiple pages can be compared with multiple images in a single test:

@Test
public void compareAsRenderedPage_MultipleInvocation() throws Exception {
  String filename = "documentUnderTest.pdf";
  
  String fullImage2cmWidthFromLeft = "images/marginFullHeight2cmWidth.png";
  int ulX_Image1 = 0;  // upper left X
  int ulY_Image1 = 0;  // upper left Y

  String subImagePage3And4 = "images/subImage_page3-page4.png";
  int ulX_Image2 = 480;
  int ulY_Image2 = 765;
  
  PagesToUse pages34 = PagesToUse.getPages(3, 4);

  AssertThat.document(filename)
            .asRenderedPage(pages34)
            .isEqualToImage(ulX_Image1, ulY_Image1, POINTS, fullImage2cmWidthFromLeft)
            .isEqualToImage(ulX_Image2, ulY_Image2, POINTS, subImagePage3And4)
  ;
}

However, you should consider whether it is better to write two tests for this. The decisive argument for separate tests is that you can choose two different names. The name chosen here is not good enough for a real project.