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 tag <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.

<!-- Testing a section of a rendered page: -->

<testcase name="..">
  <assertThat testDocument="..">
    <asRenderedPage on="..">              (page selection)
      <isEqualTo positionUpperLeftX=".."  (optional)
                 positionUpperLeftY=".."  (optional)
                 unit=".."                (optional)
                 image=".."               (required)
      />
    </asRenderedPage>
  </assertThat>
</testcase>

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:

<testcase name="compareAsRenderedPage_LeftMargin">
  <assertThat testDocument="master/documentUnderTest.pdf">
    <asRenderedPage on="EVERY_PAGE">
      <isEqualTo positionUpperLeftX="0" positionUpperLeftY="0"
                 unit="DPI72"
                 image="master/marginFullHeight2cmWidth.png"
      />
    </asRenderedPage>
  </assertThat>
</testcase>

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.

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

<testcase name="compareRenderedSectionToImages_ImageAsFilename">
  <assertThat testDocument="images/documentWithLogo.pdf">
    <asRenderedPage onPage="1, 2">
      <isEqualTo positionUpperLeftX="135" positionUpperLeftY="35" 
                 unit="MILLIMETER"
                 image="images/logo.png"
      />
    </asRenderedPage>
  </assertThat>
</testcase>

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

<testcase name="compareAsRenderedPage_MultipleInvocation">
  <assertThat testDocument="master/documentUnderTest.pdf">
    <asRenderedPage onPage="3, 4">
      <isEqualTo positionUpperLeftX="0" positionUpperLeftY="0"
                 unit="DPI72"
                 image="master/marginFullHeight2cmWidth.png"
      />
      <isEqualTo positionUpperLeftX="480" positionUpperLeftY="50"
                 unit="DPI72" 
                 image="master/subImage_page3-page4.png"
      />
    </asRenderedPage>
  </assertThat>
</testcase>

However, you should consider whether it is better to write two tests. 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.