Zurück |  | Weiter

# Kapitel 10. Validierungsregeln in Excel-Dateien

Regeln für eine Validierung von PDF-Dokumenten können in Excel-Dateien abgelegt werden. Deren Struktur sowie die an der Struktur hängende Funktionalität wird in den folgenden Abschnitten beschrieben.

### Aufbau einer Excel-Datei

Eine Excel-Datei wird nach Tabellenblättern (Sheets) mit festgelegten Namen durchsucht:

Excel-Sheet | Bedeutung
--- | ---
regions | Definition von Seitenausschnitten
check | Definition von Testfällen für einzelne PDF-Dokumente
compare | Definition von Testfällen für den Vergleich eines PDF-Dokumentes mit einer geprüften Vorlage

Alle drei Tabellenblätter haben einen festgelegten Aufbau, der in den nachfolgenden Abschnitten beschrieben wird. In allen drei Tabellenblättern bewirkt ein Stern '`*`' in der ersten Spalte, dass die Zeile als Kommentar gilt.

Die Reihenfolge der Spalten darf nicht geändert werden. Zusätzliche, individuelle Spalten hinter den festgelegten Spalten sind erlaubt. Zusätzliche Tabellenblätter in der Excel-Datei stören ebenfalls nicht.

Ein Tabellenblatt darf Leerzeilen enthalten. Falls ein Blatt aber zu viele leere Zeilen hat, kann es passieren, dass die letzten Zeilen mit Daten nicht mehr ausgelesen werden. Deshalb sollten leere Zeilen nicht verwendet werden. Setzen Sie in Spalte 1 einen Stern, dann gilt die Zeile als nicht-leer und bereitet keine technischen Probleme.

### Definition von Seitenausschnitten

Zusätzlich zu der Angabe von Seiten, ist es fast immer notwendig, Tests lediglich auf Ausschnitte einzelner Seiten zu beschränken. So macht ein Vergleich zweier Dokumente mit dem Text der vollen Seiten häufig keinen Sinn, weil sich die Dokumente in ihrem Datum unterscheiden. Deshalb erwartet PDFUnit, dass jeder Test in Excel einen Seitenausschnitt referenziert. Alle Seitenausschnitte werden in dem Sheet 'regions' definiert.

Ein Seitenausschnitt wird durch 4 Werte beschrieben: die x/y-Koordinaten der linken oberen Ecke und die Breite und Höhe des Ausschnitts. Alle Werte sind Millimeter-Angaben. Die Werte dürfen zwar Nachkommastellen haben, jedoch werden die Nachkommastellen auf die nächste Ganzzahl gerundet. Das nächste Bild zeigt ein Beispiele für Ausschnitte:

Wie zu erkennen ist, enthält das Tabellenblatt neben den 4 Werten für die Ausschnitte noch die Spalte mit der Überschrift `id`. Jeder Ausschnitt muss eine eindeutige ID besitzen. Diese ID wird von den Testfalldeklarationen in den Tabellenblättern 'check' und 'compare' referenziert.

### Struktur des Excel-Sheets 'check', Definition von Testfällen

Das Tabellenblatt 'check' dient zur Erfassung aller Informationen, die für Testfälle benötigt werden, die sich auf Einzeldokumente beziehen, also nicht für Testfälle, bei denen zwei Dokumente miteinander verglichen werden. Das sind:

Name der Spalte | Bedeutung
--- | ---
id | Name (ID) des Testfalls.
pages | Definition der Seiten, auf die sich ein Testfall bezieht.
region | Referenz auf einen Seitenausschnitt, der im Tabellenblatt 'regions' definiert ist.
constraint | Art der Überprüfung. Die erlaubten Werte sind weiter unten beschrieben.
expected value | Der erwartete Wert, der in die Validierung einfließt.
whitespace | Angabe, wie mit Whitespaces (Leerzeichen, Zeilenumbrüchen, etc.) umgegangen werden soll. Die erlaubten Werte für diese Spalte werden weiter unten beschrieben.
message | Diese Spalte nimmt eine Fehlermeldung auf. Eine Fehlermeldung kann Platzhalter enthalten. Die erlaubten Platzhalter werden ebenfalls weiter unten beschrieben.

### Benennung der Seiten, auf die sich ein Test bezieht

Ein Testfall bezieht sich häufig auf bestimmte Seiten eines Dokumentes. Deshalb können die gewünschten Seiten spezifiziert werden. Die folgende Liste zeigt alle verfügbaren Beispiele:

Seiten | Syntax in Excel
--- | ---
eine einzelne Seite | 1
mehrere einzelne Seiten | 1, 3, 5
alle Seiten | all
alle Seiten ab der angegebenen (einschließlich) | 2...
alle Seiten vor der angegebenen (einschließlich) | ...5
alle Seiten zwischen den angegebenen (einschließlich) | 2...5

Zwei Seitenzahlen müssen durch ein Leerzeichen getrennt werden. Das Komma ist optional, es dient lediglich der besseren Lesbarkeit.

### Spalte 'constraint', verschiedene Arten von Textvergleichen

Die Spalte 'constraint' dient dazu, festzulegen, welche Prüfungen durchgeführt werden sollen, ob beispielsweise ein bestimmter Text in einem Bereich enthalten sein soll ('must contain') oder ob dieser Text gerade nicht in dem Bereich enthalten sein darf ('must not contain'). Die folgende Liste zeigt die mögliche Werte der Spalte 'constraint' im Tabellenblatt 'check' für Textvergleiche:

Schlüsselwort | Verhalten
--- | ---
'must contain' | Der Text, der in der Spalte 'expected value' steht, muss innerhalb des angegebenen Bereichs im PDF-Dokument vorkommen. Zusätzlich muss die interne Behandlung von Leerzeichen vorgegeben werden.
'must not contain' | Der Text, der in der Spalte 'expected value' steht, darf innerhalb des angegebenen Bereichs im PDF-Dokument nicht vorkommen. Zusätzlich muss die interne Behandlung von Leerzeichen vorgegeben werden.
'must be empty' | Der angegebene Bereich darf keinen Text enthalten.
'must not be empty' | Der angegebene Bereich muss Text enthalten
'must match' | Der Text, der in der Spalte 'expected value' angegeben ist, wird als regulärer Ausdruck auf den Text im angegebenen Bereich angewendet. Es muss mindestens einen Treffer geben.
'must not match' | Der reguläre Ausdruck in der Spalte 'expected value' darf für den Text innerhalb des angegebenen Bereichs keinen Treffer ergeben.

Wichtig: die Spalte 'constraint' darf nicht leer sein. In einem solchen Fall bringt das System eine Fehlermeldung.

Im Tabellenblatt 'compare' sind in der Spalte 'constraint' andere Werte erlaubt. Sie werden weiter unten erläutert.

### Spalte 'constraint', Signaturen und Bilder testen

Weiterhin kann die Spalte 'constraint' im Tabellenblatt 'check' auch Schlüsselwörter für Tests auf Unterschriften und Bilder enthalten:

Schlüsselwort | Verhalten
--- | ---
'is signed' | Ein PDF-Dokument muss unterschrieben sein.
'is signed by' | Ein PDF-Dokument muss von der Person unterschrieben sein, deren Name in der Spalte 'expected value' steht.
'has number of images' | Auf den ausgewählten Seiten und Seitenausschnitten wird die Anzahl der sichtbaren Bilder überprüft. Die erwartete Anzahl muss in der Spalte 'expected value' angegeben werden.

### Spalte 'whitespace', Umgang mit Leerzeichen

Textvergleiche können an Leerzeichen und Zeilenumbrüchen scheitern. Schon bei einem Wechsel der Schriftart können andere Zeilenumbrüche entstehen. Um Tests davon unabhängig zu machen, kann PDFUnit auf dreierlei Arten mit Whitespaces umgehen:

Schlüsselwort | Verhalten
--- | ---
'ignore' | Text wird so komprimiert, dass er keine Whitespaces mehr enthält.
'keep' | Alle Whitespaces bleiben erhalten.
'normalize' | Whitespaces am Anfang und am Ende eines Textes werden gelöscht. Mehrfache Whitespaces innerhalb eines Textes werden auf ein Leerzeichen reduziert.

Fehlerhafte Whitespace-Werte führen zu einer Fehlermeldung. Die Spalte 'whitespace' darf aber leer gelassen werden. In dem Falle gilt 'normalize' als Voreinstellung.

Beim Vergleich zweier PDF-Dokumente spielen Whitespaces nicht immer eine Rolle, beispielsweise beim Vergleich von Lesezeichen (Bookmarks). In den Fälle wird eine vorhandene Angabe der Whitespace-Behandlung ignoriert.

### Spalte 'expected value', erwarteter Text

Wenn eine Prüfung gegen einen Erwartungswert stattfindet, muss es eine Spalte geben, die diesen Wert aufnimmt. Diese Spalte heißt 'expected value'.

Der Inhalt der Spalte 'expected value' wird als Regulärer Ausdruck interpretiert, wenn die Spalte 'constraint' die Werte 'must match' oder 'must not match' enthält. Informationen über reguläre Ausdrücke gibt es im Internet unter anderem bei selfhtml.

Der Inhalt der Spalte 'expected value' wird in eine Ganzzahl umgewandelt, wenn die Spalte 'constraint' den Text 'has number of images' enthält.

### Spalte 'message', Fehlermeldungen mit Platzhaltern

In den Excel-Dateien können auch individuelle Fehlermeldung hinterlegt werden, die im Fehlerfalle zusätzlich zu den Standardmeldungen von PDFUnit ausgegeben werden. Eine solche Fehlermeldung kann Platzhalter für Laufzeitinformationen enthalten. Das folgende Bild zeigt mehrere Beispiele:

Wie aus dem Bild ersichtlich ist, werden Platzhalter im Text in geschweifte Klammern eingefasst. Folgende Platzhalter können benutzt werden:

Platzhalter, Schlüsselwort | Bedeutung
--- | ---
{id} | Die ID des aktuellen Testfalls
{pages} | Seitenzahl der Seite, auf der ein Fehler erkannt wurde
{region} | Der Wert der Spalte 'region'
{constraint} | Der Wert der Spalte 'constraint'

Die Platzhalter können an beliebiger Stelle im Text eingebaut werden. Die Werte des aktuellen Tests für die Platzhalter werden zur Laufzeit in Hochkommata eingefasst. Insofern müssen solche Hochkommata im Meldungstext nicht berücksichtigt werden.

### Struktur des Excel-Sheets 'compare', Definition von Testfällen für Vergleiche

Mit Excel-Validierungsregeln können auch vergleichende Tests durchgeführt werden. Dabei wird das aktuelle PDF-Dokument gegen eine Vorlage verglichen.

Vergleichendes Testen hat zur Folge, dass in der Excel-Datei keine Angabe mehr über einen erwarteten Text gemacht werden muss. Somit entfällt im Tabellenblatt 'compare' die Spalte 'expected value'. Es verbleiben diese:

Die Bedeutungen der Spalten ändert sich nicht, sie sind in den vorhergehenden Abschnitten beschrieben. Lediglich die erlaubten Werte für die Spalte 'constraint', also die Angabe, wie ein Test ausgeführt werden soll, hat sich geändert. Für Vergleiche sind folgende Constraint-Typen erlaubt:

Schlüsselwort | Verhalten
--- | ---
'same text' | Zwei PDF-Dokumente müssen im angegebenen Bereich den gleichen Text enthalten. Zusätzlich muss noch die interne Behandlung von Leerzeichen vorgegeben werden.
'same appearance' | Zwei PDF-Dokumente müssen im angegebenen Bereich als gerendertes Bild identisch sein.
'same bookmarks' | Zwei PDF-Dokumente müssen die gleichen Lesezeichen haben. Aus technischen Gründen darf der Wert in der Spalte 'region' nicht leer sein. Da sich Lesezeichen aber nicht auf einen Seitenausschnitt beziehen, muss die Spalte 'region' den Wert 'NO_REGION' enthalten.

Ein Test, Lesezeichen eines PDF-Dokumentes mit einer Vorlage zu vergleichen, sieht folgendermaßen aus:

PDFUnit sucht die PDF-Dokumente für einen Vergleichs im Unterverzeichnis mit dem Namen 'reference' direkt unterhalb des Verzeichnisses der gerade im Test befindlichen PDF-Datei. Dort wird eine Datei mit dem gleichen Namen, wie die aktuelle Test-PDF-Datei geladen.

### Fehlermeldungen zur Laufzeit

Eine Validierung eines PDF-Dokumentes gegen einer Excel-Datei endet nicht mit dem ersten erkannten Fehler. Alle Regeln werden durchlaufen. Für jede Regelverletzung wird eine Fehlermeldung erzeugt.

Zurück |  | Weiter
9.15. ZUGFeRD-Daten extrahieren | Zum Anfang | Kapitel 11. Unicode