XSpec installieren und den ersten Test starten

Für die Beispiele brauchen wir Java ab Version 17, XSpec 4.0.3 und Saxon-HE 12.9. Die Hilfsskripte im Download setzen außerdem Python ab Version 3.11 voraus. Saxon 12.9 ist die für dieses Paket gewählte Version, nicht die Aussage über den jeweils neuesten Saxon-Stand.

Die Skripte nehmen einen Teil der Einrichtung ab. Wer XSpec schon verwendet, kann die Testdateien auch direkt mit XSpec starten. Wichtig ist in beiden Fällen, die verwendeten Versionen festzuhalten. Sonst läuft der Test im Editor und scheitert später auf dem Build-Server.

Das Beispielprojekt einrichten

Nach dem Entpacken werden die folgenden Befehle im Projektordner ausgeführt:

Der erste Befehl lädt XSpec, Saxon und den XML Resolver nach .tools/. Dafür ist Internetzugriff nötig. Der zweite prüft die bereits heruntergeladenen Dateien ohne erneuten Download. Der dritte startet die Funktionsbeispiele. Java muss vorher installiert sein.

Die Download-Adressen stehen in dependency-sources.json. Das Skript protokolliert die SHA-256-Prüfsummen der geladenen Dateien. Noch nicht unabhängig bestätigte Prüfsummen sind dort leer. Vor einer Veröffentlichung müssen Herkunft und Versionen kontrolliert werden: Eine selbst berechnete Prüfsumme erkennt spätere Änderungen, bestätigt aber nicht von sich aus die Herkunft des ersten Downloads.

Einen Test direkt aufrufen

Wenn XSPEC_HOME und SAXON_CP eingerichtet sind, geht es auf einem Unix-artigen System auch ohne den Paket-Runner:

Unter Windows lautet der entsprechende Aufruf:

Übergeben wird die .xspec-Datei, nicht das Stylesheet. Mit -j entsteht zusätzlich ein JUnit-Bericht für die automatische Auswertung. -e sorgt dafür, dass fehlgeschlagene Erwartungen auch einen Fehlerstatus beim Aufruf auslösen. Das ist besonders wichtig, wenn ein Build bei kaputten Tests stoppen soll.

Wo finde ich das Ergebnis?

Der Paket-Runner legt für jede Testsuite einen Ordner unter .build/xspec/ an. Dort stehen die Konsolenausgabe sowie die HTML-, XML- und JUnit-Berichte. Zum Lesen eignet sich der HTML-Bericht. Die gemeinsame Zusammenfassung liegt in reports/xspec-summary.json.

Bei einem Fehler lohnt sich zuerst diese Unterscheidung: Hat der Test ein falsches Ergebnis gefunden, oder konnte er gar nicht laufen? Eine fehlende JAR-Datei, ein falscher Modulpfad oder ein Kompilierungsfehler muss zuerst behoben werden. Das ist kein bestandener Test und auch kein erfolgreich geprüfter Fehlerfall. Der Runner unterscheidet diese Situationen und speichert einen Fingerabdruck der Quellen, damit alte Berichte nicht zu geändertem Code passen.

XSpec lässt sich auch in Oxygen ausführen. Dabei sollten die dort verwendeten XSpec- und Saxon-Versionen mit der Projektumgebung abgeglichen werden. Alte lokale Pfade aus den Schulungsberichten sind keine Installationsanleitung für einen neuen Rechner.

Für das spätere XProc-Beispiel kommt XML Calabash 3 hinzu. Die XSLT-, XQuery- und Schematron-Beispiele brauchen diese zusätzliche Laufzeit nicht.