Benutzung

Wir gehen davon aus, dass Sie sich mit einer Kommandozeile / Shell im Verzeichnis NCDiff-X.Y befinden.

Nahezu sämtliche Einstellungen für einen erfolgreichen NCDiff Lauf können via Konfigurationsdatei und/oder Kommandozeile bzw. Shell getroffen werden. NCDiff wird bereits mit einer Standardkonfiguration (ncdiff.cfg) und Testreports ausgeliefert, welche gerne für Ihre Bedürfnisse erweitert werden kann.

Graphische Benutzeroberfläche

Diese lässt sich unter Windows mit einem Doppelklick auf NCDiff.lnk oder durch das Kommando

./ncdiff-launcher

von der Kommandozeile aus starten und bietet folgende Möglichkeiten:

• Start von Vergleichsläufen

• Darstellung der Ergebnisse nach einem Lauf

• Überschreiben von Konfigurationsparametern wie das Ausgabeverzeichnis

• Öffnen der Konfiguration in einem Text Editor

  

Die folgenden Einstellmöglichkeiten sind vorhanden:

• Das Configuration Directory legt fest aus welchem Verzeichnis die Konfigurationsdateien angezeigt werden.

• Das Result Directory überschreibt die globale Einstellung resultDirectory in der Konfigurationsdatei (dorthin werden die Ausgabe Daten generiert).

• In der Spalte Configurations können eine oder mehrere Konfigurationsdateien ausgewählt werden. Daraufhin werden die verfügbaren Diff Targets in der rechten Spalte angezeigt.

• Nun können einzelne oder mehrere Targets selektiert werden. Wird das Häckchen bei Select all targets automatically gesetzt, so werden automatisch alle Targets ausgewählt.

• Durch einen Doppelklick auf eine Konfigurationsdatei in der Spalte Configurations wird ein Texteditor mit dieser Datei geöffnet damit diese bearbeitet werden kann.

• Im Bereich Parameter Override lassen sich Konfigurationsparameter aus der Datei für den nächsten Lauf überschreiben.

Sind alle Einstellungen vorgenommen so startet der Klick auf Run den Vergleich.

Aus dem Ergebnis Fenster lassen sich die Ergebnisse, je nach definiertem Ausgabeformat, in einem Webbrowser (HTML) oder andernfalls in einer Tabellenkalkulation (XLSX) öffnen.

Kommandozeile / Shell

Um NCDiff mit der Standardkonfiguration zu starten tippen Sie einfach

Unix:

./ncdiff

Windows:

ncdiff

Um eine bestimmtes Target, d.h. den Vergleich zweier Dateien mit einem bestimmten Namen in der Konfiguration – in diesem Fall TestReport1 durchzuführen, verwenden Sie:

ncdiff –-targets TestReport1

Mehrere ausgewählte Targets lassen sich in einer mit Kommata getrennten Liste starten:

ncdiff –-targets TestReport1,TestReport2,TestReport3

Targets lassen sich auch mit * und ? Wildcards auswählen:

ncdiff –-targets Test*
ncdiff --targets TestReport?

Die erste Zeile wählt alle Targets deren Name mit Test beginnt aus. Die zweite Zeile wählt alle Targets, die auf TestReport plus ein weiteres Zeichen lauten, aus.

Weiters ist es möglich sich einen Hilfetext ausgeben zu lassen:

ncdiff –-help

Für die Kommandozeile / Shell gilt im allgemeinen dass alle Konfigurationsparameter mittels Kommandozeile überschrieben werden können. Dazu kann man diese einfach folgendermaßen beim Aufruf spezifizieren:

ncdiff --Parameter1=Parameterwert1 --Parameter2=Parameterwert2....

Die NCDiff-Parameter werden detailliert in Konfiguration beschrieben

Ad-hoc Vergleiche

Um zwei Dateien mittels NCDiff vergleichen zu können braucht man immer eine Konfigurationsdatei (z.B. regression-test.cfg). Normalerweise startet man einen solchen Vergleich über folgenden Aufruf:

ncdiff --configurations regression-test.cfg

Hat man aber 2 Dateien und weiß nicht genau in welcher Konfigurationsdatei die Beschreibung zum Vergleich hinterlegt ist steht man vor einem größeren Problem.

Abhilfe schafft hier das sogenannte „Ad-hoc“ Feature von NCDiff. Es erlaubt es dem Benutzer einfach nur die 2 zu vergleichenden Dateien anzugeben und NCDiff versucht die dazugehörige Datei selbständig zu finden.

Nachfolgender Aufruf startet einen Ad-hoc Vergleich:

ncdiff <referenzDatei> <testDatei>

Damit die Ad-hoc Funktionalität genutzt werden kann müssen aber mehrere Voraussetzungen erfüllt sein:

• Konfigurationsdateien sind am besten zentral auf einem Share verwaltet

• Die Umgebungsvariable NCDIFF_CFGHOME muss definiert sein und zeigt auf das Verzeichnis wo sich die Konfigurationsdateien befinden bzw. können sie sich auch in einem der Unterverzeichnisse befinden.

• Konfigurationsdateien enden auf das Kürzel *.cfg

• Eine passende Konfigurationsdatei muss existieren!

• Die Reihenfolge ist von Bedeutung da die referenzDatei immer gegen oldFilePath und die testDatei immer gegen newFilePath, im gleichen Target, verglichen wird.

Der Algorithmus selbst versucht nur übereinstimmende Treffen in Bezug auf die Dateinamen zu finden. Es existiert keinerlei Logik um vom Inhalt der angegeben Dateien auf etwaige Konfigurationsdateien schließen zu können.

History Tool

Das NCDiff Tool wird häufig bei Regressionstests verwendet. Dabei werden meist iterativ Tests ausgeführt, die Ergebnisse werden dann mittels NCDiff mit den Erwartungswerten verglichen und danach Probleme analysiert und behoben. Üblicherweise werden automatisiert regelmäßig NCDiff Vergleiche gestartet um die iterativen Verbesserungen nachvollziehen zu können.

Um den Fortschritt zu visualisieren bietet NCDiff ein einfaches ncdiff-history Tool um aus den NCDiff Ergebnissen ` eine HTML Übersichtsseite zu generieren. Die Seite enthält verschiedene Grafiken über den zeitlichen Verlauf von übereinstimmenden Datensätzen, gefundenen Problemen, erfolgreichen Targets und den Ausführungszeiten von NCDiff.

Das Tool wird gestartet mit:

ncdiff-history --resultDir test/results

Wobei folgende Parameter gesetzt werden können:

resultDir

Das Verzeichnis in dem die NCDiff Ergebnisse liegen.

name

Name der Testhistorie, der für die Überschrift verwendet wird.

maxRuns

Anzahl der NCDiff Ergebnisse die in der Übersichtsseite verwendet werden sollen. Als Standardwert werden die 30 neusten NCDiff Ergebnisse verwendet. Wird der Wert auf 0 gesetzt werden alle gefundenen Ergebnisse verwendet.

showReport

Öffnet automatisch den Browser mit der Übersichtsseite.

Als Ergebnis wird eine HTML Seite history.html im „resultDir“ Verzeichnis generiert.