Chapter 3. Test Scopes

3.1. Overview

An Introduction to the Syntax

All tests need the statement use PDF::PDFUnit. The examples use also function of Test::Exception and Test::More.

use PDF::PDFUnit;
use Test::Exception;
use Test::More;

Each test for a single PDF document begins with the method AssertThat->document(..). The file to be tested is passed as a parameter. Then each following function opens a different test scope, e.g. content, fonts, layouts, etc.:

The next listings give some examples for that. The use statement is omitted for brevity.

my $resources_dir = ...;              # the base folder of your test data
my $pdfUnderTest = "$resources_dir/doc-under-test.pdf";    1

lives_ok {                             # function from Test::Exception 
  my $expectedText = "John Doe";       # 
                                       #
  AssertThat->document($pdfUnderTest)  # document under test
            ->restrictedTo($page2)     # page selection
            ->hasText()                # test scope
            ->...                      # further validation methods
  ;                                    #
} "name of the test";                  # name of the test


#
# Comparing a single document with a reference:
#
lives_ok {                             # 
  my $expectedText = "John Doe";       # 
                                       #
  AssertThat->document($pdfUnderTest)  # the document under test
            ->and($reference)          # the reference document for the comparison
            ->restrictedTo($page2)     # 
            ->hasText()                # 
            ->...                      # 
  ;                                    #
} "comparing a PDF with a reference";  #

1

The PDF document can be passed to the function as a String, File, InputStream, URL or byte array.

It is possible to write test for a given set of PDF documents. Such tests start with the method AssertThat->eachDocument(..):

# Instantiation of PDFUnit for multiple documents:
...
my $pdfArray = [$pdfUnderTest1, $pdfUnderTest2];
AssertThat->eachDocument($pdfArray)    1  5: “Folders and Multiple Documents” 
          ->hasFormat(A4_PORTRAIT)
;
...

1

The PDF documents can be passed to the function as a String[], File[], InputStream[], or URL[].

A test can also cover all PDF documents in a folder. Such tests start with the method AssertThat->eachDocument()->inFolder(..):

# Instantiation of PDFUnit for a folder:
...
AssertThat->eachDocument()
          ->inFolder($folder)              1  5.3: “Validate all documents in a folder” 
          ->passedFilter($allPdfunitFiles)
          -> ...
;
...

1

All PDF documents in this folder will be checked. PDF documents in subfolders will not be checked.

Test Scopes

The following list gives a complete overview over the test scopes of PDFUnit. These tests are not described in this manual, to avoid redundant documentation. To read the details, follow the link to the PDFUnit-Java manual: http://www.pdfunit.com/en/documentation/java/.

# Every one of the following methods opens a new test scope:
# 
# The detailed descriptions can be found in the manual of PDFUnit-Java (to avoid redundancy).
# The names of the methods are exactly the same.
#
# see   http://www.pdfunit.com/en/documentation/java/ 
#  
->asRenderedPage()               

->containsImage(..)              
->containsOneImageOf(..)         

->hasAuthor()                    
->hasBookmark()                  
->hasBookmarks()                 
->hasCreationDate()              
->hasCreator()                   
->hasEmbeddedFile(..)            
->hasEncryptionLength(..)        
->hasField(..)                   
->hasFields(..)                  
->hasFont()                      
->hasFonts()                     
->hasFormat(..)                  
->hasImage(..)                   
->hasJavaScript()                
->hasJavaScriptAction()          
->hasKeywords()                  
->hasLanguageInfo(..)            
->hasLayer()                     
->hasLayers()                    
->hasLessPagesThan()             
->hasLocalGotoAction()           
->hasModificationDate()          
->hasMorePagesThan()             
->hasNamedDestination()          

->hasNoAuthor()                  
->hasNoCreationDate()            
->hasNoCreator()                 
->hasNoImage()                   
->hasNoKeywords()                
->hasNoLanguageInfo()            
->hasNoModificationDate()        
->hasNoProducer()                
->hasNoProperty(..)              
->hasNoSubject()                 
->hasNoText()                    
->hasNoTitle()                   
->hasNoXFAData()                 
->hasNoXMPData()                 

->..  continued
... continuation:

->hasNumberOf...()               

->hasOCG()                       
->hasOCGs()                      
->hasOwnerPassword(..)           
->hasPermission()                
->hasProducer()                  
->hasProperty(..)                
->hasSignatureField(..)          
->hasSignatureFields()           
->hasSubject()                   
->hasText()                      
->hasTitle()                     
->hasUserPassword(..)            
->hasVersion()                   
->hasXFAData()                   
->hasXMPData()                   
->hasZugferdData()               

->haveSame...()                  

->isCertified()                  
->isCertifiedFor(..)             
->isLinearizedForFastWebView()   
->isSigned()                     
->isSignedBy(..)                 
->isTagged()                     

->restrictedTo(..)               

Sometimes, two methods are needed to enter a test scope:

# Validation of bar code and QR code:
->hasImage()->withBarcode()                
->hasImage()->withQRcode()                 

# Validation based on Excel files:
->compliesWith()->constraints(excelRules)  

# Validation of DIN5008 constraints:
->compliesWith()->din5008FormA()           
->compliesWith()->din5008FormB()           
->compliesWith()->pdfStandard()            

# Validation around ZUGFeRD:
->compliesWith()->zugferdSpecification(..) 

Once a again the link to the PDFUnit-Java manual: http://www.pdfunit.com/en/documentation/java/.

PDFUnit is continuously being improved and the manual kept up to date. Wishes and requests for new functions are appreciated. Please, send them to info[at]pdfunit.com.