13.2.  Page Selection

Predefined Pages

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

// Possibilities to focus tests to specific pages:

com.pdfunit.Constants.ANY_PAGE      com.pdfunit.Constants.ON_ANY_PAGE
com.pdfunit.Constants.EVEN_PAGES    com.pdfunit.Constants.ON_EVEN_PAGES
com.pdfunit.Constants.EACH_PAGE     com.pdfunit.Constants.ON_EACH_PAGE
com.pdfunit.Constants.EVERY_PAGE    com.pdfunit.Constants.ON_EVERY_PAGE
com.pdfunit.Constants.FIRST_PAGE    com.pdfunit.Constants.ON_FIRST_PAGE
com.pdfunit.Constants.LAST_PAGE     com.pdfunit.Constants.ON_LAST_PAGE
com.pdfunit.Constants.ODD_PAGES     com.pdfunit.Constants.ON_ODD_PAGES

The constants on the left-hand side have the same meaning as those on the right-hand side. The right-hand side is supported to be compatible with older releases.

Here an example using one of the constants:

@Test
public void hasText_MultipleSearchTokens_EvenPages() throws Exception {
  String filename = "documentUnderTest.pdf";
  
  AssertThat.document(filename)
            .restrictedTo(EVEN_PAGES)
            .hasText() 
            .containing("Content", "even pagenumber") 
  ;
}

Individual Pages

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

@Test
public void hasText_OnMultiplePages() throws Exception {
  String filename = "documentUnderTest.pdf";
  PagesToUse pages123 = PagesToUse.getPages(1, 2, 3);

  AssertThat.document(filename)
            .restrictedTo(pages123)
            .hasText() 
            .containing("Content on")
  ;
}

Two methods are available to select a single page or a set of pages:

// How to define individual pages:

PagesToUse.getPage(2);
PagesToUse.getPages(1, 2, 3);

Open Ranges

Various methods are available to define a ranges of pages at the beginning or at the end of a document:

// How to define open ranges:

ON_ANY_PAGE.after(2);
ON_ANY_PAGE.before(3);

ON_EVERY_PAGE.after(2);
ON_EVERY_PAGE.before(2);

The lower- or upper-limits are excluded from the expected date range.

The following example validates a PDF document starting with page 3.

@Test
public void compareFormat_OnEveryPageAfter() throws Exception {
  String filename = "documentUnderTest.pdf";
  String filenameReference = "reference.pdf";
  PagesToUse pagesAfter2 = ON_ANY_PAGE.after(2);

  AssertThat.document(filename)
            .and(filenameReference)
            .restrictedTo(pagesAfter2)
            .haveSameFormat()
  ;
}

Inner Ranges

And finally, it's possible to define a range of pages inside a document using PagesToUse.spanningFrom().to().

@Test
public void hasText_SpanningOver2Pages() throws Exception {
  String filename = "documentUnderTest.pdf";
  String textOnPage1 = "Text starts  on page 1 and ";
  String textOnPage2 = "continues on page 2";
  String expectedText = textOnPage1 + textOnPage2;
  PagesToUse pages1to2 = PagesToUse.spanningFrom(1).to(2);
  
  // Mark the section without header and footer:
  int leftX  =  18;
  int upperY =  30;
  int width  = 182;
  int height = 238;
  PageRegion regionWithoutHeaderAndFooter = new PageRegion(leftX, upperY, width, height);
  
  AssertThat.document(filename)
            .restrictedTo(pages1to2)
            .restrictedTo(regionWithoutHeaderAndFooter)
            .hasText() 
            .containing(expectedText)
  ;
}

Important Hints

  • Page numbers begin with '1'.

  • The page number in before(int) and after(int) are both exclusive.

  • The page number in from(int) and to(int) are both inclusive.

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

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

  • The use of restrictedTo(PagesToUse) and restrictedTo(PageRegion) has no effect on methods applied to the full document.