13.6.  Defining Page Areas

Comparing text or rendered pages can be restricted to regions of one or more pages. Such an area is defined by four values: the x/y values of the upper left corner, thie width and the height:

<!-- Defining a clipping area: -->

<inClippingArea upperLeftX=".." upperLeftY=".." width=".." height=".." />
<inClippingArea upperLeftY=".." upperLeftX=".." width=".." height=".." unit=".." />

The units are described in chapter 13.7: “Format Units”. If no unit is set, PDFUnit uses the unit MILLIMETER.

Here's an example:

<testcase name="hasText_InClippingArea">
  <assertThat testDocument="content/documentForTextClipping.pdf">
    <hasText on="FIRST_PAGE" >
      <inClippingArea upperLeftX="17.6" upperLeftY="45.8"
                      width="60.0" height="8.8" 
                      unit="MILLIMETER" 
       >
        <containing>Content on first page.</containing>
      </inClippingArea>
    </hasText>
  </assertThat>
</testcase>
<testcase name="haveSameAppearance_InClippingArea">
  <assertThat testDocument="master/compareToMaster_sameImagesDifferentOrder.pdf"
              masterDocument="master/compareToMaster.pdf"
  >
    <haveSameAppearance on="FIRST_PAGE">
      <inClippingArea upperLeftX="50" upperLeftY="755" 
                      width="370" height="35" 
                      unit="POINTS"
      />
    </haveSameAppearance>
  </assertThat>
</testcase>

It's easy to use a region of a page in a test. But it might be more difficult to find the right values for the region you need. PDFUnit provides the utility RenderPdfClippingAreaToImage to extract a page section into an image file (PNG). You can use that program using mm or points:

::
:: Render a part of a PDF page into an image file
::

@echo off
setlocal
set CLASSPATH=./lib/pdfunit-2015.10/*;%CLASSPATH%
set CLASSPATH=./lib/jpedal/*;%CLASSPATH%
set CLASSPATH=./lib/bouncycastle-jdk15on-150/*;%CLASSPATH%
set CLASSPATH=./lib/aspectj-1.8.0/*;%CLASSPATH%

set TOOL=com.pdfunit.tools.RenderPdfClippingAreaToImage
set PAGENUMBER=1
set OUT_DIR=./tmp
set IN_FILE=../content/documentForTextClipping.pdf
set PASSWD=

::  Format unit can only be 'mm' or 'points'
set FORMATUNIT=points
set UPPERLEFTX=50
set UPPERLEFTY=130
set WIDTH=170
set HEIGHT=25

java  %TOOL%  %IN_FILE%  %PAGENUMBER%  %OUT_DIR%  %FORMATUNIT%  %UPPERLEFTX%  
      %UPPERLEFTY%  %WIDTH%  %HEIGHT%  %PASSWD%
endlocal

The generated image needs to be checked. Does it contain the section you want? If not, change the parameters until they are right. Then you can copy the four values into your test.