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 .. image:: img/benutzung_gui.png 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. .. image:: img/benutzung_run.png Aus dem Ergebnis Fenster lassen sich die Ergebnisse, je nach definiertem Ausgabeformat, in einem Webbrowser (HTML) oder andernfalls in einer Tabellenkalkulation (XLSX) öffnen. .. image:: img/benutzung_result.png 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 :doc:`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 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. .. image:: img/benutzung_ncdiff_history.png 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.