3.6. Bilder in Dokumenten

Überblick

Ein veraltetes Bild in einem Dokument kommt beim Empfänger etwa so gut an, wie eine veraltete Neujahrsansprache (Rede des deutschen Bundeskanzlers in der ARD 1986) - auf jeden Fall anders, als sich die Designer des Dokumentes das gedacht haben. Deshalb sollten Sie überprüfen, ob das neue Unternehmens-Logo auch wirklich dargestellt wird.

Eine weitere Fehlerquelle im Zusammenhang mit Bildern ist, dass ein Bild während des PDF-Erstellungsprozesses nicht gefunden wird und im PDF einfach fehlt. Sichern Sie auch diese Situation durch einen passenden Test ab.

Und als Letztes sei noch der Fehler genannt, dass Bilder auf falschen Seiten auftauchen, weil der Seitenumbruch anders als erwartet funktioniert.

Allen Fehlern kann mit diesen Tags begegnet werden:

<!-- Tags for image tests: -->

<hasNumberOfDifferentImages />
<hasNumberOfVisibleImages />
<containsImage file=".."   (required)
               
               on=".."                 (one of the page selection attributes
               onPage=".."             ...
               onEveryPageAfter=".."   ...
               onEveryPageBefore=".."  ...
               onAnyPageAfter=".."     ...
               onAnyPageBefore=".."    ... is required)
/>

Eine wichtige Bemerkung vorweg: Die Anzahl der sichtbaren Bilder entspricht überlicherweise nicht der Anzahl der im PDF-Dokument selbst gespeicherten Bilder. Ein Logo, das auf 10 Seiten sichtbar ist, wird intern nur einmal gespeichert. Deshalb gibt es zwei Tags. Das Tag <hasNumberOfDifferentImages /> überprüft die Anzahl der internen Bilder, während das Tag <hasNumberOfVisibleImages /> die Anzahl der sichtbaren Bilder überprüft.

Anzahl unterschiedlicher Bilder im Dokument

Das erste Beispiel zeigt die Validierung der Anzahl der PDF-intern gespeicherten Bilder:

<testcase name="hasNumberOfDifferentImages">
  <assertThat testDocument="images/imageDemo.pdf">
    <hasNumberOfDifferentImages>2</hasNumberOfDifferentImages>
  </assertThat>
</testcase>

Wie kommt man in diesem Beispiel auf die 2? Wie können Sie für ein bestimmtes PDF wissen, welche Bilder tatsächlich intern gespeichert sind? Zur Beantwortung dieser Fragen extrahieren Sie alle Bilder Ihres PDF-Dokumentes mit dem von PDFUnit mitgelieferten Hilfsprogramm ExtractImages. Eine Beschreibung dieses Programms steht in Kapitel 9.3: „Bilder aus PDF extrahieren“.

Anzahl sichtbarer Bilder im Dokument

Das nächste Beispiel validiert die Anzahl der sichtbaren Bilder:

<testcase name="hasNumberOfVisibleImages">
  <assertThat testDocument="images/imageDemo.pdf">
    <hasNumberOfVisibleImages>6</hasNumberOfVisibleImages>
  </assertThat>
</testcase>

Das Beispieldokument hat 6 Bilder auf 6 Seiten, davon 2 Bilder auf Seite 3 und kein Bild auf Seite 4.

Der Test auf die sichtbaren Bilder kann auf spezifizierte Seiten beschränkt werden. So werden im nächsten Beispiel nur die Bilder auf Seite 3 überprüft:

<testcase name="hasNumberOfVisibleImages_OnPage3">
  <assertThat testDocument="images/imageDemo.pdf">
    <hasNumberOfVisibleImages onPage="3">2</hasNumberOfVisibleImages>
  </assertThat>
</testcase>

Gleiche Bilder, die mehrfach auf einer Seite zu sehen sind, werden auch mehrfach gezählt.

Die Möglichkeiten, Tests auf bestimmte Seiten zu beschränken, werden in Kapitel 13.2: „Seitenauswahl“ ausführlich beschrieben.

Bestimmte Bilder vergleichen

Nach dem Zählen der Bilder folgt die Prüfung auf das Aussehen der Bilder. Im nachfolgenden Beispiel sucht PDFUnit innerhalb des PDF-Dokumentes ein Bild, das exakt so aussieht, wie das der angegebenen Datei:

<testcase name="containsImage">
  <assertThat testDocument="images/imageDemo.pdf">
    <containsImage file="images/apache-software-foundation-logo.png" 
                   on="ANY_PAGE" 
    />
  </assertThat>
</testcase>

Das Ergebnis eines Vergleiches zweier Bilddateien hängt von den Dateiformaten ab. PDFUnit kann JPEG, PNG, GIF, BMP und WBMP verarbeiten. Die Bilder werden von PDFUnit byte-weise verglichen. Deshalb werden die BMP- und PNG-Versionen eines Bildes nicht als gleich erkannt.

Beim Erzeugen von PDF kann es zu einer Formatumwandlung zwischen den Bildvorlagen als Datei und den intern gespeicherten Bildern kommen. Dadurch wird es unmöglich, die internen Bilder mit den Vorlagen zu vergleichen. Sollte es diese Problem geben, extrahieren Sie das gewünschte Bild als PNG. Gehen Sie dafür folgendermaßen vor:

  • Extrahieren Sie alle Bilder mit dem Hilfsprogramm ExtractImages. Alle Bilder werden als PNG abgespeichert.

  • Überprüfen Sie das gewünschte Bild auf seine Korrektheit.

  • Benutzen Sie es im Test, wie im obigen Listing dargestellt.

Eine Menge von Bildern als Vergleichsvorlage

Es kann die Situation geben, dass ein PDF-Dokument eines von drei möglichen Logos enthält. Oder die Unterschrift ist eine aus einer Menge von fünf erlaubten. Für diese Situation gibt es das Tag <containsOneOfTheseImages />:

<testcase name="containsOneOfManyImages_alex">
  <assertThat testDocument="images/letter-signed-by-alex.pdf">
    <containsOneOfTheseImages on="LAST_PAGE">
      <image file="images/signature-alex.png" />
      <image file="images/signature-bob.png" />
    </containsOneOfTheseImages>
  </assertThat>
</testcase>

Dieser Test kann sich nicht nur auf eine Seite beziehen, wie hier die letzte Seite, sondern auch auf mehrere, wie der folgende Abschnitt zeigt.

Bilder auf unterschiedlichen Seiten

Die Suche nach Bildern kann grundsätzlich auf einzelne, mehrere individuelle oder mehrere zusammenhängende Seiten eingeschränkt werden. Es stehen dafür die gleichen Möglichkeiten zur Verfügung, wie in Kapitel 13.2: „Seitenauswahl“ beschrieben.

Hier ein paar Beispiele:

<testcase name="containsImage_OnEveryPageAfter4">
  <assertThat testDocument="images/imageDemo.pdf">
    <containsImage file="images/apache-software-foundation-logo.png" 
                   onEveryPageAfter="4" 
    />
  </assertThat>
</testcase>
<testcase name="containsImage_OnMultipleSelectedPages">
  <assertThat testDocument="images/imageDemo.pdf">
    <containsImage file="images/apache-software-foundation-logo.png" 
                   onPage="1, 5"  />
  </assertThat>
</testcase>

In einem Test kann die Prüfung auf verschiedene Bilder ausgeführt werden. Überlegen Sie aber, ob es nicht sinnvoller ist, für das folgende Beispiel zwei getrennte Tests zu schreiben:

<testcase name="containsImage_MultipleInvocation">
  <assertThat testDocument="images/imageDemo.pdf">
    <containsImage file="images/apache-software-foundation-logo.png" 
                   onEveryPageAfter="4"
    />
    <containsImage file="images/apache-ant-logo.png" 
                   onPage="3"
    />
  </assertThat>
</testcase>

Die in einem PDF enthaltenen Bilder können auch gegen die Bilder in einem Master-PDF getestet werden. Eine genaue Beschreibung dazu enthält das Kapitel 4.5: „Bilder vergleichen“.