13.2.  Page Selection

Predefined Pages

Constants allow your tests to focus on specific pages in a PDF document. Their names clearly express their intent:

<!-- Possibilities to focus tests to specific pages:  -->

<!-- Predefined constants for pages: -->
<xxx on="ANY_PAGE"   />
<xxx on="EVEN_PAGES" />
<xxx on="EACH_PAGE"  />
<xxx on="EVERY_PAGE" />
<xxx on="FIRST_PAGE" />
<xxx on="LAST_PAGE"  />
<xxx on="ODD_PAGES"  />

<!-- Attributes for individual pages: -->
<xxx onPage=".."            />
<xxx onEveryPageAfter=".."  />
<xxx onEveryPageBefore=".." />
<xxx onAnyPageAfter=".."    />
<xxx onAnyPageBefore=".."   />

on="EACH_PAGE" and on="EVERY_PAGE" are functionally identical. The redundancy is intended due to linguistic reasons.

Here an example using the attribute on=".." and a predefined page constant:

<testcase name="hasText_MultipleSearchTokens_EvenPages">
  <assertThat testDocument="content/diverseContentOnMultiplePages.pdf">
    <hasText on="EVEN_PAGES">
      <containing>even pagenumber</containing>

Individual Pages

The next example shows how individual pages can be addressed. Page numbers must be separated by commas:

<testcase name="hasText_OnMultiplePages_SelectedPages">
  <assertThat testDocument="content/diverseContentOnMultiplePages.pdf">
    <hasText onPage="1, 2, 3">
      <containing>Content on</containing>

Open Ranges

Constants are available for contiguous ranges of pages at the beginning and at the end of a document:

<testcase name="hasText_OnAnyPageAfter1">
  <assertThat testDocument="content/diverseContentOnMultiplePages.pdf">
    <hasText onAnyPageAfter="1">
      <containing>Content on</containing>
<testcase name="hasText_OnEveryPageBefore3">
  <assertThat testDocument="content/diverseContentOnMultiplePages.pdf">
    <hasText onEveryPageBefore="3">
      <containing>Content on</containing>

Inner Ranges

And finally attributes exist to set the scope of a test to a range of pages inside a document, <hasText fromPage="1" toPage="2" >.

<testcase name="hasText_SpanningOver2Pages_matchingRegex">
  <assertThat testDocument="&pdfdir;/content/text-starts-on-page1-continues-on-page2.pdf">
    <hasText fromPage="1" toPage="2" >
      <inClippingArea upperLeftX="18" upperLeftY="30" 
                      width="182" height="238" 
        <matchingRegex>Text starts  on page 1.*continues on page 2</matchingRegex>

In combination with <hasText fromPage="1" toPage="2" > only the tags <containing>, <matchingRegex>, <notContaining> and <notMatchingRegex> can be used.

Important Hints

  • Page numbers begin with '1'.

  • The page number in onXxxPageBefore and onXxxPageAfter are both exclusive.

  • The page number in the attributes from and to are both inclusive.

  • The attribute onEveryPageXxx means that the expected text has to exist on each page in the given range.

  • When using onAnyPageXXX, a test is successful if the expected string exists on one or more pages in the given range.