PDFUnit in Perl - Einige Beispiele

PDFUnit testet sichtbare und unsichtbare Teile eines PDF-Dokumentes. Texte einer PDF-Seite können als echter Text (kein Bild) oder als gerendertes Bild verarbeitet werden.

Weiterhin ist es möglich, viele Eigenschaften eines Test-PDF Dokumentes gegen ein Referenz-Dokument zu vergleichen.

Die nachfolgenden Beispiele geben einen kleinen Einblick in die Benutzung von PDFUnit mit Perl.

Textinhalte auf einer bestimmten Seite

lives_ok {
  my $pdfUnderTest = "$resources_dir/document-under-test.pdf";
  my $expectedText = "Chapter 3";
  my $page2        = PagesToUse->getPage(2);
  
  AssertThat->document($pdfUnderTest)
            ->restrictedTo($page2)
            ->hasText()
            ->containing($expectedText)
  ;
} "validateTextOnPageTwo";

---

Seitenausschnitte als Text vergleichen

Das folgende Beispiel zeigt die Verwendung von Seitenausschnitten. Der Text im Ausschnitt des Testdokumentes muss mit dem Text in dem Referenz-Dokument identisch sein.

lives_ok {
  my $pdfUnderTest = "$resources_dir/document-under-test.pdf";
  my $pdfReference = "$resources_dir/reference.pdf";
  my $pages12 = PagesToUse->getPages( [1, 2] );
    
  AssertThat->document($pdfUnderTest)
            ->and($pdfReference)
            ->restrictedTo($pages12)
            ->haveSameText()
  ;
} "comparePageBodyWithReference";

---

Seitenausschnitte als gerenderte Bilder vergleichen

PDFUnit kann nicht nur Text vergleichen, sondern auch Seiten oder Seitenausschnitte als Bilder (rendered page). Im nächsten Beispiel wird der Vergleich auf einen Ausschnitt der ersten Seite beschränkt.

lives_ok {
  my $pdfUnderTest = "$resources_dir/document-under-test.pdf";
  my $pdfReference = "$resources_dir/reference.pdf";
  
  my $leftX  =  80;  # in millimeter
  my $ipperY = 175;
  my $width  =  60;
  my $height =   9;
  my $region = PageRegion->new($leftX, $upperY, $width, $height);
  
  AssertThat->document($pdfUnderTest)
            ->and($pdfReference)
            ->restrictedTo(FIRST_PAGE)
            ->restrictedTo(region)
            ->haveSameAppearance()
  ;
} "haveSameAppearanceOnFirstPageInRegion";

---

Inhalt eines QR-Codes

QR-Codes sind immer mehr Teil von PDF-Dokumenten. Aus diesem Grund bietet PDFUnit auch Methoden zur Validierung der QR-Code Inhalte.

lives_ok {
  my $expectedText = "hello, world";
  my $page2        = PagesToUse->getPage(2);
  my $firstQRCodeRegion = _createQRCodeRegion();
    
  AssertThat->document($pdfUnderTest)
            ->restrictedTo($page2)
            ->restrictedTo($firstQRCodeRegion)
            ->hasImage()
            ->withQRCode()
            ->equalsTo($expectedText)
  ;
} "validateQRCode";

---

Inhalte von ZUGFeRD-Daten

Die unsichtbaren ZUGFeRD-Daten und die sichtbaren Daten eines PDF-Dokumentes sollten zusammenpassen. Für diese Anforderung gibt es in PDFUnit passende Testmethoden. Das folgende Beispiel prüft, ob die Kontonummer aus den ZUGFeRD-Daten mit der Kontonummer in einem vorgegebenen Bereich der ersten Seite des Rechnungsdokumentes übereinstimmt:

lives_ok {
  my $pdfUnderTest = "$resources_dir/document-under-test.pdf";
  my $nodeIBAN = XMLNode->new("ram:IBANID");

  my $ibanLeftX  =  80;  # in millimeter
  my $ibanUpperY = 175;
  my $ibanWidth  =  60;
  my $ibanHeight =   9;
  my $regionIBAN = PageRegion->new($ibanLeftX, $ibanUpperY, $ibanWidth, $ibanHeight);

  AssertThat->document($pdfZugferd)
            ->restrictedTo(FIRST_PAGE)
            ->restrictedTo($regionIBAN)
            ->hasText()
            ->containingZugferdData($nodeIBAN)
  ;
} "validateIBANInZugferdData";

---

Weitere Beispiele

Eine vollständige Beschreibung aller Testfunktionen ist im Handbuch für PDFUnit-Java zu finden. Das Handbuch für PDFUnit-Perl beschreibt zwar viele Beispiele, aber nicht alle, letztendlich um den Dokumentationsaufwand gering zu halten. Perl-Entwickler sind der Erfahrung nach clever genug, die Syntax von Java nach Perl zu übertragen. Die Namen der Methoden sind in Java und Perl identisch.

Beide Handbücher können als PDF heruntergeladen werden.